Reference

ECPGPlusには次の言語要素があります。

  • Cプリプロセッサ指示子

  • サポートされているCデータ型

  • タイプコード

  • SQLDA構造

  • ECPGPlusステートメント

Cプリプロセッサ指示子

ECPGPlus Cプリプロセッサは、ECPGPlusを呼び出すモードに応じて2つの動作を強制します。

  • PROC モード

  • Non-PROC モード

PROCモードでのコンパイル

PROC モードでは、ECPGPlusを使用して次のことができます。

  • EXEC SQL BEGIN/END DECLARE SECTION の外部でホスト変数を宣言します。

  • データ型がECPGと互換性がある限り、C変数をホスト変数として使用します。

PROC モードで（ -C PROC キーワードを含めることにより）ECPGPlusを呼び出すと、ECPGコンパイラは次のCプリプロセッサ指示子を受け入れます。

# include
# if expression
# ifdef symbolName
# ifndef symbolName
# else
# elif expression
# endif
# define symbolName expansion
# define symbolName([macro arguments]) expansion
# undef symbolName
# defined(symbolName)

プリプロセッサ指示子は、コンパイラーが受け取るコードに影響を与えるか、指示するために使用されます。たとえば、次のコードサンプルを考えます。

# if HAVE_LONG_LONG == 1
# define BALANCE_TYPE long long
# else
# define BALANCE_TYPE double
# endif
...
BALANCE_TYPE customerBalance;

次のコマンドライン引数を使用してECPGPlusを呼び出すとします。

ecpg –C PROC –DHAVE_LONG_LONG=1

ECPGPlusは、フラグメント全体を変更せずに出力ファイルにコピーします。次のトークンのみをECPGパーサーに送信します。

long long customerBalance;

一方、次のコマンドライン引数を使用して ECPGPlus を呼び出すとします。

ecpg –C PROC –DHAVE_LONG_LONG=0

ECPGパーサーは次のトークンを受け取ります。

double customerBalance;

コードがプリプロセッサ指示子を使用して、コンパイラーに送信されるコードをフィルター処理する場合、ECPGパーサーは処理されたトークンストリームのみを認識しますが、完全なコードは元のコードに保持されます。

EXEC 指示子で次のプリプロセッサ指示子を実行するときに、互換性のある構文を使用することもできます。

EXEC ORACLE DEFINE
EXEC ORACLE UNDEF
EXEC ORACLE INCLUDE
EXEC ORACLE IFDEF
EXEC ORACLE IFNDEF
EXEC ORACLE ELIF
EXEC ORACLE ELSE
EXEC ORACLE ENDIF
EXEC ORACLE OPTION

たとえば、コードに次のものが含まれているとします。

EXEC ORACLE IFDEF HAVE_LONG_LONG;
# define BALANCE_TYPE long long
EXEC ORACLE ENDIF;
BALANCE_TYPE customerBalance;

次のコマンドライン引数を使用してECPGPlusを呼び出します。

ecpg –C PROC DEFINE=HAVE_LONG_LONG=1

ECPGPlusは、次のトークンを出力ファイルとECPGパーサーに送信します。

long long customerBalance;

注釈

EXEC ORACLE プリプロセッサ指示子は、ECPGコマンドラインで`-C PROC` を指定した場合にのみ機能します。

SELECT_ERRORプリコンパイラーオプションの使用

ECPGPlusを互換モードで使用する場合、 SELECT_ERROR プリコンパイラーオプションを使用して、ホスト変数が対応できる以上の行を含む結果セットを処理する方法をプログラムに指示できます。構文は次のとおりです。

SELECT_ERROR={YES|NO}

デフォルト値はYES です。結果セットがホスト変数の容量を超える場合、 SELECT ステートメントはエラーメッセージを返します。 SELECT ステートメントがホスト変数が収容できるよりも多くの行を返した場合にエラーメッセージを抑制するには、 NO を指定します。

EXEC ORACLE OPTION 指示子でSELECT_ERROR を使用します。

非PROCモードでのコンパイル

-C PROC コマンドラインオプションを含めない場合：

  • Cプリプロセッサ指示子はそのまま出力ファイルにコピーされます。

  • EXEC SQL BEGIN/END DECLARE セクションでホスト変数として使用する各C変数の型と名前を宣言する必要があります。

非PROC モードで呼び出されると、ECPGはPostgreSQLコアドキュメントで説明されている動作を実装します。

サポートされているCデータ型

ECPGPlusアプリケーションは、 SQLデータ型（SMALLINT 、DOUBLE PRECISION 、CHARACTER VARYING など）とCデータ型（short 、double 、varchar[n] など）の2つのデータ型を処理する必要があります。アプリケーションがサーバーからデータを取得すると、ECPGPlusは各SQLデータ型をデータが返されるC変数の型にマップします。

一般に、 ECPGPlus はほとんどのSQLサーバー型を同様のC型に変換できますが、すべての組み合わせが有効なわけではありません。たとえば、 ECPGPlusはSQL文字値をC整数値に変換しようとしますが、 SQL文字値に数字以外の文字が含まれている場合、実行時に変換が失敗する場合があります。

逆もまた真です。アプリケーションがサーバーに値を送信すると、ECPGPlusはCデータ型を必要なSQL型に変換しようとします。繰り返しますが、C値を必要なSQL型に変換できない場合、実行時に変換が失敗する可能性があります。

ECPGPlusは、任意のSQL型をC文字値（char[n] またはvarchar[n] ）に変換できます。 SQL型をchar[n] またはvarchar[n] との間で変換しても安全ですが、多くの場合、 int 、double 、またはfloat などのより自然なC型を使用すると便利です。

サポートされているCのデータ型は次のとおりです。

  • short

  • int

  • unsigned int

  • long long int

  • float

  • double

  • char[n+1]

  • varchar[n+1]

  • bool

  • typedef によって作成された同等の

Cでサポートされている数値型と文字型に加えて、 pgtypeslib ランタイムライブラリは、日付/時刻と正確な数値を処理するためのカスタムデータ型と、それらの型を操作する関数を提供します。

  • timestamp

  • interval

  • date

  • decimal

  • numeric

pgtypeslib が提供するデータ型を使用するには、適切なヘッダーファイルを#include する必要があります。

タイプコード

次の表には、 _external_データ型の型コードが含まれています。外部データ型は、Cホスト変数の型を示すために使用されます。アプリケーションが値をパラメーターにバインドするか、バッファーをSELECT -list項目にバインドする場合、対応するSQLDA記述子 (descriptor->T[column]) の型コードを次のいずれかの値に設定します。

Type code

Host variable type (C data type)

1, 2, 8, 11, 12, 15, 23, 24, 91, 94, 95, 96, 97

char[]

3

int

4, 7, 21

float

5, 6

null-terminated string (char[length+1])

9

varchar

22

double

68

unsigned int

次の表には、 _internal_データ型の型コードが含まれています。内部型コードは、データベースにある値の型を示すために使用されます。 DESCRIBE SELECT LIST ステートメントは、次の値を使用してデータ型配列(descriptor->T[column]) を設定します。

Internal type code

Server type

1

VARCHAR2

2

NUMBER

8

LONG

11

ROWID

12

DATE

23

RAW

24

LONG RAW

96

CHAR

100

BINARY FLOAT

101

BINARY DOUBLE

104

UROWID

187

TIMESTAMP

188

TIMESTAMP W/TIMEZONE

189

INTERVAL YEAR TO MONTH

190

INTERVAL DAY TO SECOND

232

TIMESTAMP LOCAL_TZ

SQLDA構造

Oracle動的SQL方法4は、SQLDAデータ構造を使用して、動的SQL文のデータとメタデータを保持します。 SQLDA構造体は、動的ステートメントのテキストまたは動的ステートメントの結果セットにあるパラメーターマーカーに対応する入力パラメーターのセットを記述することができます。 SQLDA構造のレイアウトは次のとおりです。

struct SQLDA
{
  int     N; /* Number of entries             */
  char  **V; /* Variables                 */
  int    *L; /* Variable lengths          */
  short  *T; /* Variable types            */
  short **I; /* Indicators                */
  int     F; /* Count of variables discovered by DESCRIBE */
  char  **S; /* Variable names            */
  short  *M; /* Variable name maximum lengths     */
  short  *C; /* Variable name actual lengths  */
  char  **X; /* Indicator names           */
  short  *Y; /* Indicator name maximum lengths */
  short  *Z; /* Indicator name actual lengths     */
};

パラメーター

N - maximum number of entries

N 構造体メンバーには、SQLDAが記述できるエントリの最大数が含まれています。このメンバーは、SQLDA構造体を割り当てるときにsqlald() ファンクションによって移入されます。 OPEN またはFETCH ステートメントで記述子を使用する前に、記述された値の実際の数にN を設定する必要があります。

V - data values

V 構造体メンバーは、データ値の配列へのポインターです。

  • SELECT -list記述子の場合、 V はFETCH ステートメントによって返される値の配列を指します。配列内の各メンバーは、結果セットの列に対応します。

  • バインド記述子の場合、 V はパラメーター値の配列を指します。記述子を使用するカーソルを開く前に、この配列に値を設定する必要があります。

アプリケーションは、各値を保持するために必要な領域を割り当てる必要があります。 SELECT -list値に領域を割り当てる方法の例については、

displayResultSet を参照してください。

L - length of each data value

L 構造体メンバーは、長さの配列へのポインターです。この配列の各メンバーは、 V 配列の対応するメンバーで使用可能なメモリ量を示す必要があります。たとえば、 V[5] が20バイトのNULL終了文字列を保持するのに十分な大きさのバッファーを指している場合、 L[5] には値21（文字列の文字の20バイトとNULLターミネータの1バイト）が含まれる必要があります。アプリケーションは、 L 配列の各メンバーを設定する必要があります。

T - data types

T 構造体メンバーは、記述子で記述された列（またはパラメーター）ごとに1つのデータ型の配列を指します。

  • バインド記述子の場合、T 配列の各メンバーを設定して、ECPGPlusに各パラメーターのデータ型を指示する必要があります。

  • SELECT -リスト記述子の場合、 DESCRIBE SELECT LIST ステートメントは、対応する列で見つかったデータの型を反映するようにT 配列のメンバーを設定します。

FETCH ステートメントを実行して、対応する値を特定のデータ型に変換する前にT 配列のメンバーを変更できます。たとえば、 DESCRIBE SELECT LIST ステートメントが、特定の列がDATE 型であることを示している場合、対応するT メンバーを変更して、次のFETCH ステートメントがその値をNULLで終わる文字列の形式で返すように要求できます。 T 配列の各メンバーは数値型コードです（型コードのリストは タイプコード を参照）。 DESCRIBE SELECT LIST ステートメントが返すタイプコードは、 FETCH ステートメントが期待するものとは異なります。 DESCRIBE SELECT LIST ステートメントの実行後、 T の各メンバーは、データ型と、対応する列がNULL可能かどうかを示すフラグをエンコードします。 sqlnul() 関数を使用して、 T配列のメンバーから型コードとnullableフラグを抽出できます。 sqlnul() 関数のシグネチャは次のとおりです。

void sqlnul(unsigned short *valType,
            unsigned short *typeCode,
            int            *isNull)

たとえば、resultsという名前の記述子の3列目の型コードとnullableフラグを見つけるには、次のようにsqlnul() を呼び出します。

sqlnul(&results->T[2], &typeCode, &isNull);

I - indicator variables

I 構造体メンバーは、標識変数の配列を指します。この配列は、アプリケーションが sqlald() 関数を呼び出して記述子を割り当てるときに割り当てられます。

  • SELECT -list記述子の場合、 I 配列の各メンバーは、対応する列にNULL（非ゼロ）または非NULL（ゼロ）値が含まれているかどうかを示します。

  • bindパラメーターの場合、アプリケーションはI 配列の各メンバーを設定して、対応するパラメーター値がNULLであるかどうかを示す必要があります。

F - number of entries

F 構造体メンバーは、記述子で記述されている値の数を示します。 N 構造体のメンバーは、記述子が記述できる値の最大数を示します。 F は、値の実際の数を示します。 F メンバーの値は、 DESCRIBE ステートメントを実行するときにECPGPlusによって設定されます。 F は、正、負、またはゼロです。

  • SELECT リスト記述子の場合、結果セットの列数が記述子で許可される値の最大数以下である場合（ N 構造体メンバーによって決定）、 F には正の値が含まれます。ステートメントが SELECT ステートメントでない場合、0が含まれます。クエリが N 構造体メンバーで許可されているよりも多くの列を返す場合、負の値が含まれます。

  • バインド記述子の場合、ステートメントで見つかったパラメーターの数が記述子で許可される値の最大数以下である場合、 F には正の数が含まれます（ N 構造体メンバーによって決定されます）。ステートメントにパラメーターマーカーが含まれていない場合、0 が含まれます。 N 構造体メンバーで許可されているよりも多くのパラメーターマーカーがステートメントに含まれている場合、負の値が含まれます。

F に（ DESCRIBE ステートメントの実行後に）正の数が含まれる場合、その数は結果セットの列数（ SELECT リスト記述子の場合）またはステートメントで見つかったパラメーターマーカーの数（バインド記述子の場合）を反映します。 F に負の値が含まれている場合、 F の絶対値を計算して、必要な値またはパラメーターマーカーの数を検出できます。たとえば、 SELECT リストを記述した後にF に-24 が含まれている場合、クエリが24列を返すことがわかります。

S - column/parameter names

S 構造体メンバーは、NULLで終了する文字列の配列を指します。

  • SELECT -リスト記述子の場合、 DESCRIBE SELECT LIST ステートメントは、この配列の各メンバーを結果セット内の対応する列の名前に設定します。

  • バインド記述子の場合、 DESCRIBE BIND VARIABLES ステートメントは、この配列の各メンバーを対応するバインド変数の名前に設定します。

このリリースでは、各バインド変数の名前は、クエリー内のパラメータマーカーの左から右の順序によって決定されます。たとえば、最初のパラメーターの名前は常に ?0 、2番目のパラメーターの名前は常に ?1 などです。

M - maximum column/parameter name length

M 構造体メンバーは、長さの配列を指します。この配列の各メンバーは、 S 配列の対応するメンバーの最大長を指定します（つまり、 M[0] は、 S[0] で見つかった列/パラメーター名の最大長を指定します）。この配列は、 sqlald() 関数によって設定されます。

C - actual column/parameter name length

C 構造体メンバーは、長さの配列を指します。この配列の各メンバーは、 S 配列の対応するメンバーの実際の長さを指定します（つまり、 C[0] は、 S[0] で見つかった列/パラメーター名の実際の長さを指定します）。

この配列は、 DESCRIBE ステートメントによって設定されます。

X - indicator variable names

X 構造体メンバーは、NULLで終了する文字列の配列を指します。各文字列は、対応する値の NULL インジケータの名前を表します。

このアレイはECPGPlusでは使用されませんが、Pro*Cアプリケーションとの互換性のために提供されています。

Y - maximum indicator name length

Y 構造体メンバーは、長さの配列を指します。この配列の各メンバーは、 X 配列の対応するメンバーの最大長を指定します（つまり、 Y[0] は、 X[0] で見つかったインジケーター名の最大長を指定します）。

このアレイはECPGPlusでは使用されませんが、Pro*Cアプリケーションとの互換性のために提供されています。

Z - actual indicator name length

Z 構造体メンバーは、長さの配列を指します。この配列の各メンバーは、 X 配列の対応するメンバーの実際の長さを指定します（つまり、 Z[0] は、 X[0] で見つかったインジケーター名の実際の長さを指定します）。

このアレイはECPGPlusでは使用されませんが、Pro*Cアプリケーションとの互換性のために提供されています。

ECPGPlusステートメント

埋め込みSQLステートメントを使用すると、クライアント アプリケーションはサーバーと対話できます。埋め込み指示子は、ECPGPlusコンパイラーへの指示です。

CプログラムにEDB Postgres Advanced Server SQLステートメントを埋め込むことができます。各ステートメントは、キーワード EXEC SQL で始まり、セミコロン（;）で終了する必要があります。 Cプログラムでは、 SQLステートメントは次の形式を取ります。

EXEC SQL <sql_command_body>;

sql_command_body は、標準SQLステートメントを表します。ホスト変数は、 SQLステートメントが値式を必要とする場所であればどこでも使用できます。値式のホスト変数の置換の詳細については、

ホスト変数の宣言 を参照してください。

ECPGPlusは、一部のステートメントのPostgreSQLサーバー側の構文を拡張します。構文の違いは、以下のリファレンス情報に記載されています。他のSQLコマンドでサポートされている構文の完全なリファレンスについては、

PostgreSQL core documentation を参照してください。

割り当てディスクリプター

ALLOCATE DESCRIPTOR ステートメントを使用して、 SQL記述子領域を割り当てます。

EXEC SQL [FOR <array_size>] ALLOCATE DESCRIPTOR <descriptor_name>
    [WITH MAX <variable_count>];

そこで：

  • array_size は、記述子に割り当てる配列の要素数を指定する変数です。 array_size は、 INTEGER 値またはホスト変数です。

  • descriptor_name は、記述子の名前または記述子の名前を含むホスト変数です。この値は、識別子、引用符で囲まれた文字列リテラル、またはホスト変数の形式を取ることができます。

  • variable_count は、記述子内のホスト変数の最大数を指定します。 variable_count のデフォルト値は100 です。

次のコードフラグメントは、配列(emp_array) として処理できるemp_query という名前の記述子を割り当てます。

EXEC SQL FOR :emp_array ALLOCATE DESCRIPTOR emp_query;

コール

CALL ステートメントを使用して、サーバーでプロシージャまたはファンクションを呼び出します。 CALL ステートメントは、 EDB Postgres Advanced Serverでのみ機能します。 CALL ステートメントには2つの形式があります。最初のフォームは、関数を呼び出すために使用されます。

EXEC SQL CALL <program_name> ([<actual_arguments>])
  INTO [[:<ret_variable>][: <ret_indicator>]];

2番目の形式は、プロシージャを呼び出すために使用されます。

EXEC SQL CALL <program_name> ([<actual_arguments>]);

そこで：

  • program_name は、CALL ステートメントが呼び出すストアドプロシージャまたはファンクションの名前です。プログラム名は、スキーマ修飾、パッケージ修飾、またはその両方にすることができます。プログラムが存在するスキーマまたはパッケージを指定しない場合、ECPGPlusはsearch_path の値を使用してプログラムを見つけます。

  • actual_arguments は、プログラムが必要とする引数のコンマ区切りリストを指定します。各 actual_argument は、プログラムが期待する仮引数に対応します。各仮引数には、 IN パラメーター、 OUT パラメーター、またはINOUT パラメーターを指定できます。

  • :ret_variable は、プログラムがファンクションの場合に戻り値を受け取るホスト変数を指定します。

  • :ret_indicator は、プログラムがファンクションの場合に返されるインジケータ値を受け取るホスト変数を指定します。

たとえば、次のステートメントは、 :ename ホスト変数に含まれる値を使用してget_job_desc ファンクションを呼び出し、そのファンクションによって返された値を:job ホスト変数にキャプチャします。

EXEC SQL CALL get_job_desc(:ename)
  INTO :job;

閉じる

CLOSE ステートメントを使用して、カーソルを閉じ、カーソルが現在使用しているリソースを解放します。クライアント アプリケーションは、閉じたカーソルから行をフェッチできません。 CLOSE ステートメントの構文は次のとおりです。

EXEC SQL CLOSE [<cursor_name>];

cursor_name は、ステートメントによってクローズされたカーソルの名前です。カーソル名は、識別子またはホスト変数の形式を取ることができます。

OPEN ステートメントは、カーソルを初期化します。初期化されると、カーソルを再度オープンしない限り、カーソル結果セットは変更されません。カーソルを再度開く前にCLOSE する必要はありません。

emp_cursor という名前のカーソルを手動で閉じるには、次のコマンドを使用します。

EXEC SQL CLOSE emp_cursor;

アプリケーションが終了すると、カーソルは自動的にクローズされます。

コミット

COMMIT ステートメントを使用して、現在のトランザクションを完了し、すべての変更を永続的にし、他のユーザーが見えるようにします。構文は次のとおりです。

EXEC SQL [AT <database_name>] COMMIT [WORK]
         [COMMENT <text>] [COMMENT <text> RELEASE];

database_name は、作業が存在するデータベースの名前を含むデータベースまたはホスト変数の名前です。この値は、引用符なしの文字列リテラルまたはホスト変数の形式を取ることができます。

互換性のために、 ECPGPlusはエラーなしでCOMMENT 句を受け入れますが、 COMMENT 句に含まれるテキストは保存しません。

コミットの実行後に現在の接続を閉じるには、 RELEASE 句を含めます。

たとえば、次のコマンドは、 dept データベースで実行されたすべての作業をコミットし、現在の接続を閉じます。

EXEC SQL AT dept COMMIT RELEASE;

デフォルトでは、ステートメントはクライアントアプリケーションがCOMMIT ステートメントを実行する場合にのみコミットされます。 ECPGPlusを呼び出すときに-t オプションを含めて、クライアントアプリケーションがAUTOCOMMIT 機能を呼び出すように指定します。次のステートメントを使用して、クライアントアプリケーションのAUTOCOMMIT 機能を制御することもできます。

EXEC SQL SET AUTOCOMMIT TO ON

そして

EXEC SQL SET AUTOCOMMIT TO OFF

接続する

CONNECT ステートメントを使用して、データベースへの接続を確立します。 CONNECT ステートメントは2つの形式で使用できます。 1つはOracleデータベースと互換性があり、もう1つはそうではありません。

最初の形式はOracleデータベースと互換性があります。

EXEC SQL CONNECT
  {{:<user_name> IDENTIFIED BY :<password>}  | :<connection_id>}
  [AT <database_name>]
  [USING :database_string]
  [ALTER AUTHORIZATION :new_password];

そこで：

  • user_name は、クライアントアプリケーションがサーバーへの接続に使用するロールを含むホスト変数です。

  • password は、そのロールに関連付けられたパスワードを含むホスト変数です。

  • connection_id は、データベースへの接続に使用されるスラッシュ区切りのユーザー名とパスワードを含むホスト変数です。

AT 句を含めて、接続を確立するデータベースを指定します。 database_name は、クライアントが接続しているデータベースの名前です。値は変数または文字列リテラルで指定します。

USING 句を含めて、接続を確立するデータベースを識別するヌル終了文字列を含むホスト変数を指定します。

ALTER AUTHORIZATION 句は、構文の互換性のためにのみサポートされています。 ECPGPlusはALTER AUTHORIZATION 句を解析し、警告を報告します。

CONNECT ステートメントの最初の形式を使用して、クライアントアプリケーションは、次のコマンドを使用して、接続ロールのIDを含むuser という名前のホスト変数と、関連するパスワードを含むpassword という名前のホスト変数との接続を確立します。

EXEC SQL CONNECT :user IDENTIFIED BY :password;

クライアントアプリケーションは、 CONNECT ステートメントの最初の形式を使用して、 :connection_id という名前の単一のホスト変数を使用して接続を確立することもできます。次の例では、 connection_id には、ユーザーのスラッシュ区切りのロール名と関連するパスワードが含まれています。

EXEC SQL CONNECT :connection_id;

CONNECT ステートメントの2番目の形式の構文は次のとおりです。

EXEC SQL CONNECT TO <database_name>
[AS <connection_name>] [<credentials>];

credentials は次のいずれかです。

USER user_name password
USER user_name IDENTIFIED BY password
USER user_name USING password

2番目の形式では：

database_name は、クライアントが接続しているデータベースの名前またはIDです。 database_name を次のいずれかの形式で変数または文字列リテラルとして指定します。

<database_name>[@<hostname>][:<port>]

tcp:postgresql://<hostname>[:<port>][/<database_name>][options]

unix:postgresql://<hostname>[:<port>][/<database_name>][options]

そこで：

  • hostname は、データベースが存在するサーバーの名前またはIPアドレスです。

  • port は、サーバーがリッスンするポートです。

DEFAULT の値を指定して、デフォルトのロール名を使用してデフォルトのデータベースとの接続を確立することもできます。ターゲットデータベースとしてDEFAULT を指定する場合、 connection_name またはcredentials を含めないでください。

  • connection_name は、データベースへの接続の名前です。 connection_name は識別子の形式をとります（つまり、文字列リテラルまたは変数ではありません）。接続ごとに一意のconnection_name を提供することにより、複数の接続を開くことができます。

接続の名前を指定しない場合、 ecpglib は接続にDEFAULT の名前を割り当てます。任意のEXEC SQL ステートメントで名前（DEFAULT ）で接続を参照できます。

  • CURRENT は、最後に開かれたか、最新のSET CONNECTION TO ステートメントで言及されている接続です。 EXEC SQL ステートメントで接続を名前で参照しない場合、ECPGは接続の名前をCURRENT と想定します。

  • user_name は、 EDB Postgres Advanced Serverデータベースとの接続を確立するために使用されるロールです。指定されたロールの特権は、接続を介して実行されるすべてのコマンドに適用されます。

  • password は、指定されたuser_name に関連付けられたパスワードです。

次のコードフラグメントは、 CONNECT ステートメントの2番目の形式を使用して、ロールalice とそのロールに関連付けられたパスワード1safepwd を使用してedb という名前のデータベースへの接続を確立します。

EXEC SQL CONNECT TO edb AS acctg_conn
  USER alice IDENTIFIED BY 1safepwd;

接続の名前はacctg_conn です。 SET CONNECTION ステートメントを使用して接続名を変更するときに、接続名を使用できます。

割り当て解除ディスクリプター

DEALLOCATE DESCRIPTOR ステートメントを使用して、割り当てられた記述子が使用中のメモリーを解放します。ステートメントの構文は次のとおりです。

EXEC SQL DEALLOCATE DESCRIPTOR <descriptor_name>

descriptor_name は記述子の名前です。この値は、引用符で囲まれた文字列リテラルまたはホスト変数の形式を取ることができます。

次の例では、 emp_query という名前の記述子の割り当てを解除します。

EXEC SQL DEALLOCATE DESCRIPTOR emp_query;

カーソルを宣言

DECLARE CURSOR ステートメントを使用してカーソルを定義します。ステートメントの構文は次のとおりです。

EXEC SQL [AT <database_name>] DECLARE <cursor_name> CURSOR FOR
(<select_statement> | <statement_name>);

そこで：

  • database_name は、カーソルが操作するデータベースの名前です。この値は、ID またはホスト変数の形式を取ることができます。データベース名を指定しない場合、 database_name のデフォルト値がデフォルトのデータベースです。

  • cursor_name はカーソルの名前です。

  • select_statement は、カーソル結果セットを定義するSELECT ステートメントのテキストです。 SELECT ステートメントにINTO 句を含めることはできません。

  • statement_name は、カーソル結果セットを定義するSQLステートメントまたはブロックの名前です。

次の例では、 employees という名前のカーソルを宣言します。

EXEC SQL DECLARE employees CURSOR FOR
  SELECT
    empno, ename, sal, comm
  FROM
    emp;

カーソルは、 emp テーブルに格納されている各従業員レコードの従業員番号、従業員名、給与、および歩合を含む結果セットを生成します。

宣言データベース

DECLARE DATABASE ステートメントを使用して、後続のSQLステートメント（たとえば、 CONNECT ステートメント）で使用するデータベース識別子を宣言します。構文は次のとおりです。

EXEC SQL DECLARE <database_name> DATABASE;

database_name はデータベースの名前を指定します。

次の例は、 acctg データベースの識別子の宣言を示しています。

EXEC SQL DECLARE acctg DATABASE;

acctg をデータベース識別子として宣言するコマンドを呼び出した後、接続を確立するときに、またはAT 句でacctg データベースを参照できます。

このステートメントは効果がなく、Pro*Cとの互換性のためにのみ提供されています。

宣言文

DECLARE STATEMENT 指示子を使用して、 SQLステートメントの識別子を宣言します。 EDB Postgres Advanced Serverは、2つのバージョンのDECLARE STATEMENT 指示子をサポートしています。

EXEC SQL [<database_name>] DECLARE <statement_name> STATEMENT;

そして

EXEC SQL DECLARE STATEMENT <statement_name>;

そこで：

  • statement_name は、ステートメントに関連付けられた識別子を指定します。

  • database_name は、データベースの名前を指定します。この値は、ID または ID を含むホスト変数の形式を取ることができます。

DECLARE STATEMENT 指示子を含む一般的な使用シーケンスは次のとおりです。

EXEC SQL DECLARE give_raise STATEMENT;      // give_raise is now a statement
handle (not prepared)
EXEC SQL PREPARE give_raise FROM :stmtText; // give_raise is now associated
with a statement
EXEC SQL EXECUTE give_raise;

このステートメントは効果がなく、Pro*Cとの互換性のためにのみ提供されています。

削除

DELETE ステートメントを使用して、テーブルから1つ以上の行を削除します。 ECPGPlus DELETE ステートメントの構文はSQLステートメントの構文と同じですが、式が許可されている任意の場所でパラメーターマーカーとホスト変数を使用できます。構文は次のとおりです。

[FOR <exec_count>] DELETE FROM [ONLY] <table> [[AS] <alias>]
  [USING <using_list>]
  [WHERE <condition> | WHERE CURRENT OF <cursor_name>]
  [{RETURNING|RETURN} * | <output_expression> [[AS] <output_name>]
[, ...] INTO <host_variable_list> ]

  • FOR exec_count 句を含めて、ステートメントの実行回数を指定します。この句は、 VALUES 句が配列または配列へのポインターを参照する場合にのみ有効です。

  • table は、既存のテーブルの名前（オプションでスキーマ修飾）です。 ONLY 句を含めて、処理を指定されたテーブルに制限します。 ONLY 句を含めない場合、名前付けたテーブルを継承するテーブルも処理されます。

・ alias は、対象表の代用名です。

  • using_list はテーブル式のリストであり、他のテーブルの列をWHERE 条件に表示できます。

  • WHERE 句を含めて、削除する行を指定します。ステートメントに WHERE 句を含めない場合、 DELETE はテーブルからすべての行を削除し、テーブル定義はそのままにします。

  • condition は、BOOLEAN 型の値を返す式、ホスト変数、またはパラメーターマーカーです。 condition がtrueを返す行は削除されます。

  • cursor_name は、 WHERE CURRENT OF 句で使用するカーソルの名前です。削除される行は、このカーソルから最後にフェッチされた行です。カーソルは、 DELETE ステートメントのターゲットテーブルに対する非グループ化クエリである必要があります。ブール条件を含むDELETE ステートメントでWHERE CURRENT OF を指定することはできません。

RETURN/RETURNING 句は、各行が削除された後に DELETE コマンドによって返されるoutput_expression またはhost_variable_list を指定します。

  • output_expression は、各行が削除された後にDELETE コマンドによって計算されて返される式です。 output_name は、返される列の名前です。すべての列を返すには*を含めます。

  • host_variable_list は、ホスト変数とオプションの標識変数のコンマ区切りリストです。各ホスト変数は、 RETURNING 句から対応する値を受け取ります。

たとえば、次のステートメントは、 emp テーブルからすべての行を削除します。sal 列には、ホスト変数:max_sal: で指定された値より大きい値が含まれています

DELETE FROM emp WHERE sal > :max_sal;

DELETE ステートメントの使用の詳細については、 PostgreSQL core documentation を参照してください。

説明する

DESCRIBE ステートメントを使用して、準備されたステートメントに必要な入力値の数または準備されたステートメントによって返される出力値の数を見つけます。 DESCRIBE ステートメントは、アプリケーションの作成時に形状が不明なSQLステートメントを分析するために使用されます。

DESCRIBE ステートメントは、 SQLDA 記述子を設定します。 SQL記述子を設定するには、 ALLOCATE DESCRIPTOR およびDESCRIBE...DESCRIPTOR ステートメントを使用します。

EXEC SQL DESCRIBE BIND VARIABLES FOR <statement_name> INTO <descriptor>;

EXEC SQL DESCRIBE SELECT LIST FOR <statement_name> INTO <descriptor>;

そこで：

  • statement_name は、準備されたSQL文またはPL/ SQLブロックに関連付けられた識別子です。

  • descriptor は、SQLDA* 型のC変数の名前です。 sqlald() を呼び出して記述子用の領域を割り当て、 DESCRIBE ステートメントを実行する前に記述子を初期化する必要があります。

DESCRIBE ステートメントの最初の形式を実行すると、ECPGは指定された記述子にステートメントで_required_各入力変数の説明を入力します。たとえば、2つの記述子が与えられた場合：

SQLDA *query_values_in;
SQLDA *query_values_out;

emp テーブルから情報を返すクエリを準備できます。

EXEC SQL PREPARE get_emp FROM
  "SELECT ename, empno, sal FROM emp WHERE empno = ?";

このコマンドには、パラメーターマーカー（?）用に1つの入力変数が必要です。

EXEC SQL DESCRIBE BIND VARIABLES
  FOR get_emp INTO query_values_in;

この文のバインド変数を説明した後、記述子を調べて、必要な変数の数と各変数の型を確認できます。

2番目のフォームを実行すると、ECPGは指定された記述子にステートメントによって返された各値の説明を入力します。たとえば、次のステートメントは3つの値を返します。

EXEC SQL DESCRIBE SELECT LIST
  FOR get_emp INTO query_values_out;

このステートメントの選択リストを説明した後、記述子を調べて、返された値の数、および各値の名前と型を見つけることができます。

ステートメントを実行する前に、各入力値の変数と各出力値の変数をバインドする必要があります。入力値にバインドする変数は、ステートメントで使用される実際の値を指定します。出力値にバインドした変数は、ステートメントの実行時に値を配置する場所をECPGPlusに指示します。

これは、 DESCRIBE DESCRIPTOR ステートメントのPro*C互換の代替構文です。

詳細説明

DESCRIBE DESCRIPTOR ステートメントを使用して、 SQLステートメントに関する情報を取得し、その情報をSQL記述子に保存します。 DESCRIBE DESCRIPTOR を使用する前に、 ALLOCATE DESCRIPTOR ステートメントで記述子を割り当てる必要があります。構文は次のとおりです。

EXEC SQL DESCRIBE [INPUT | OUTPUT] <statement_identifier>
  USING [SQL] DESCRIPTOR <descriptor_name>;

そこで：

  • statement_name は、準備されたSQLステートメントの名前です。

  • descriptor_name は、記述子の名前です。 descriptor_name は、引用符で囲まれた文字列値または記述子の名前を含むホスト変数です。

INPUT 句を含めると、ECPGPlusは指定された記述子にステートメントで必要な各入力変数の説明を入力します。

たとえば、2つの記述子が与えられた場合：

EXEC SQL ALLOCATE DESCRIPTOR query_values_in;
EXEC SQL ALLOCATE DESCRIPTOR query_values_out;

emp テーブルから情報を返すクエリを準備できます。

EXEC SQL PREPARE get_emp FROM
  "SELECT ename, empno, sal FROM emp WHERE empno = ?";

このコマンドには、パラメーターマーカー（?）用に1つの入力変数が必要です。

EXEC SQL DESCRIBE INPUT get_emp USING query_values_in;

この文のバインド変数を説明した後、記述子を調べて、必要な変数の数と各変数の型を確認できます。

INPUT 句を指定しない場合、 DESCRIBE DESCRIPTOR は指定された記述子にステートメントによって返された値を設定します。

OUTPUT 句を含めると、ECPGPlusは指定された記述子にステートメントによって返される各値の説明を入力します。

たとえば、次のステートメントは3つの値を返します。

EXEC SQL DESCRIBE OUTPUT FOR get_emp USING query_values_out;

このステートメントの選択リストを説明した後、記述子を調べて、返された値の数、および各値の名前と型を見つけることができます。

切断する

DISCONNECT ステートメントを使用して、サーバーへの接続を閉じます。構文は次のとおりです。

EXEC SQL DISCONNECT [<connection_name>][CURRENT][DEFAULT][ALL];

connection_name は、接続の確立に使用されるCONNECT ステートメントで指定された接続名です。接続名を指定しない場合、現在の接続は閉じられます。

CURRENT キーワードを含めて、ECPGPlusが最後に使用した接続を閉じるように指定します。

DEFAULT キーワードを含めて、ECPGPlusがDEFAULT という名前の接続を閉じるように指定します。接続を開くときに名前を指定しない場合、ECPGPlusは名前 DEFAULT を接続に割り当てます。

すべてのアクティブな接続を閉じるには、 ALL キーワードを含めます。

次の例では、 hr データベースに接続してから切断するhr_connection という名前の接続を作成します。

/* client.pgc*/
int main()
{
    EXEC SQL CONNECT TO hr AS connection_name;
    EXEC SQL DISCONNECT connection_name;
    return(0);
}

実行する

EXECUTE ステートメントを使用して、 EXEC SQL PREPARE ステートメントを使用して以前に準備されたステートメントを実行します。構文は次のとおりです。

EXEC SQL [FOR <array_size>] EXECUTE <statement_name>
  [USING {DESCRIPTOR <SQLDA_descriptor>
  |: <host_variable> [[INDICATOR] :<indicator_variable>]}];

そこで：

・ array_size は、処理する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • statement_name は、EXEC SQL PREPARE ステートメントを使用してステートメントを作成したときにステートメントに割り当てられた名前を指定します。

USING 句を含めて、準備されたステートメントのパラメーターに値を指定します。

  • DESCRIPTOR SQLDA_descriptor 句を含めて、パラメーターにSQLDA記述子値を提供します。

  • host_variable （およびオプションのindicator_variable ）を使用して、パラメーターにユーザー指定の値を提供します。

次の例では、 emp テーブルにレコードを挿入する準備済みステートメントを作成します。

EXEC SQL PREPARE add_emp (numeric, text, text, numeric) AS
    INSERT INTO emp VALUES($1, $2, $3, $4);

準備されたステートメントを呼び出すたびに、ステートメントに新しいパラメーター値を指定します。

EXEC SQL EXECUTE add_emp USING 8000, DAWSON, CLERK, 7788;
EXEC SQL EXECUTE add_emp USING 8001, EDWARDS, ANALYST, 7698;

EXECUTE DESCRIPTOR

EXECUTE ステートメントを使用して、 SQL記述子を使用して、 EXEC SQL PREPARE ステートメントで事前に準備されたステートメントを実行します。構文は次のとおりです。

EXEC SQL [FOR <array_size>] EXECUTE <statement_identifier>
  [USING [SQL] DESCRIPTOR <descriptor_name>]
  [INTO [SQL] DESCRIPTOR <descriptor_name>];

そこで：

・ array_size は、処理する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • statement_identifier は、EXEC SQL PREPARE ステートメントでステートメントに割り当てられた識別子を指定します。

  • descriptor_name は、記述子の名前（一重引用符で囲まれた文字列リテラルとして）、または記述子の名前を含むホスト変数を指定します。

USING 句を含めて、準備されたステートメントで必要な入力パラメーターの値を指定します。

INTO 句を含めて、 EXECUTE ステートメントが準備されたステートメントによって返された結果を書き込む記述子を指定します。

次の例では、記述子 stmtText: に含まれる値を使用して、準備されたステートメント give_raise を実行します。

EXEC SQL PREPARE give_raise FROM :stmtText;
EXEC SQL EXECUTE give_raise USING DESCRIPTOR :stmtText;

EXECUTE…END EXEC

EXECUTE…END-EXEC ステートメントを使用して、匿名ブロックをクライアントアプリケーションに埋め込みます。構文は次のとおりです。

EXEC SQL [AT <database_name>] EXECUTE <anonymous_block> END-EXEC;

そこで：

・ database_name は、データベース識別子、またはデータベース識別子を格納するホスト変数です。 AT 句を省略すると、ステートメントは現在のデフォルトデータベースで実行されます。

  • anonymous_block は、PL / pgSQLまたはSPLのステートメントと宣言のインラインシーケンスです。ブロックにはホスト変数とオプションの標識変数を含めることができます。このような変数はそれぞれ IN/OUT 値として扱われます。

次の例では、無名ブロックを実行します。

EXEC SQL EXECUTE
  BEGIN
    IF (current_user = :admin_user_name) THEN
      DBMS_OUTPUT.PUT_LINE(You are an administrator);
    END IF;
END-EXEC;

注釈

EXECUTE…END EXEC ステートメントは、 EDB Postgres Advanced Serverでのみサポートされています。

すぐに実行

EXECUTE IMMEDIATE ステートメントを使用して、 SQLコマンドを含む文字列を実行します。構文は次のとおりです。

EXEC SQL [AT <database_name>] EXECUTE IMMEDIATE <command_text>;

そこで：

・ database_name は、データベース識別子、またはデータベース識別子を格納するホスト変数です。 AT 句を省略すると、ステートメントは現在のデフォルトデータベースで実行されます。

・ command_text は、EXECUTE IMMEDIATE ステートメントで実行されるコマンドです。

この動的SQLステートメントは、クライアントアプリケーションを作成するときにSQLステートメントのテキストがわからない場合に役立ちます。たとえば、クライアントアプリケーションは、実行するステートメントを信頼できるユーザーに求める場合があります。ユーザーがステートメントのテキストを文字列値として入力すると、ステートメントがEXECUTE IMMEDIATE コマンドで実行されます。

ステートメント テキストには、ホスト変数への参照を含めることはできません。ステートメントにパラメーターマーカーが含まれている場合、または1つ以上の値を返す場合は、 PREPARE および DESCRIBE ステートメントを使用します。

次の例では、 :command_text ホスト変数に含まれるコマンドを実行します。

EXEC SQL EXECUTE IMMEDIATE :command_text;

取得

FETCH ステートメントを使用して、カーソルからSQLDA記述子またはホスト変数のターゲットリストに行を戻します。 FETCH ステートメントを使用してカーソルから情報を取得する前に、 DECLARE およびOPEN ステートメントを使用してカーソルを準備する必要があります。ステートメントの構文は次のとおりです。

EXEC SQL [FOR <array_size>] FETCH <cursor>
  { USING DESCRIPTOR <SQLDA_descriptor> }|{ INTO <target_list> };

そこで：

・ array_size は、取得する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • cursor は、行がフェッチされるカーソルの名前、またはカーソルの名前を含むホスト変数です。

USING 句を含めると、 FETCH ステートメントは、指定されたSQLDA記述子にサーバーから返された値を設定します。

INTO 句を含めると、 FETCH ステートメントは、 target_list で指定されたホスト変数（およびオプションの標識変数）を設定します。

次のコードフラグメントは、 emp テーブルからemployee number 、name 、およびsalary を取得するemployees という名前のカーソルを宣言しています。

EXEC SQL DECLARE employees CURSOR FOR
    SELECT empno, ename, esal FROM emp;
EXEC SQL OPEN emp_cursor;
EXEC SQL FETCH emp_cursor INTO :emp_no, :emp_name, :emp_sal;

フェッチディスクリプタ

FETCH DESCRIPTOR ステートメントを使用して、カーソルから行をSQL記述子に取得します。構文は次のとおりです。

EXEC SQL [FOR <array_size>] FETCH <cursor>
  INTO [SQL] DESCRIPTOR <descriptor_name>;

そこで：

・ array_size は、取得する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • cursor は、行がフェッチされるカーソルの名前、またはカーソルの名前を含むホスト変数です。クライアントは、 FETCH DESCRIPTOR ステートメントを呼び出す前に、カーソルをDECLARE およびOPEN する必要があります。

  • descriptor_name は、記述子の名前（一重引用符で囲まれた文字列リテラルとして）または記述子の名前を含むホスト変数を指定します。使用する前に、 ALLOCATE DESCRIPTOR ステートメントを使用して記述子を割り当てる必要があります。

INTO 句を含めて、準備されたステートメントから返された結果をEXECUTE ステートメントが書き込むSQL記述子を指定します。

次の例では、結果セット内の特定の行の説明と値を保持する row_desc という名前の記述子を割り当てます。次に、 FETCH を使用して、結果セット内の行をループする前に、準備されたステートメント（my_cursor ）のカーソルを宣言して開きます。

EXEC SQL ALLOCATE DESCRIPTOR row_desc;
EXEC SQL DECLARE my_cursor CURSOR FOR query;
EXEC SQL OPEN my_cursor;

for( row = 0; ; row++ )
{
  EXEC SQL BEGIN DECLARE SECTION;
    int col;
EXEC SQL END DECLARE SECTION;
EXEC SQL FETCH my_cursor INTO SQL DESCRIPTOR row_desc;

記述子を取得する

GET DESCRIPTOR ステートメントを使用して、記述子から情報を取得します。 GET DESCRIPTOR ステートメントには2つの形式があります。最初の形式は、記述子の値（または列）の数を返します。

EXEC SQL GET DESCRIPTOR <descriptor_name>
  :<host_variable> = COUNT;

2番目の形式は、特定の値（ VALUE column_number 句で指定）に関する情報を返します。

EXEC SQL [FOR <array_size>] GET DESCRIPTOR <descriptor_name>
  VALUE <column_number> {:<host_variable> = <descriptor_item> {,…}};

そこで：

・ array_size は、処理する行数を指定する整数値またはホスト変数です。 array_size を指定する場合、 host_variable はそのサイズの配列である必要があります。たとえば、 array_size が10 の場合、 :host_variable はhost_variables の10メンバー配列でなければなりません。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • descriptor_name は、ディスクリプタ名を一重引用符で囲んだ文字列リテラルまたはディスクリプタ名を格納するホスト変数で指定します。

VALUE 句を含めて、記述子から取得した情報を指定します。

  • column_number は、記述子内の変数の位置を識別します。

・ host_variable は、項目の値を受け取るホスト変数名を指定します。

・ descriptor_item は、取得する記述子項目の種類を指定します。

ECPGPlusは、次のdescriptor_item タイプを実装します。

  • TYPE

  • LENGTH

  • OCTET_LENGTH

  • RETURNED_LENGTH

  • RETURNED_OCTET_LENGTH

  • PRECISION

  • SCALE

  • NULLABLE

  • INDICATOR

  • DATA

  • NAME

次のコードフラグメントは、 GET DESCRIPTOR ステートメントを使用して、ユーザー指定の文字列に入力された列の数を取得する方法を示しています。

EXEC SQL ALLOCATE DESCRIPTOR parse_desc;
EXEC SQL PREPARE query FROM :stmt;
EXEC SQL DESCRIBE query INTO SQL DESCRIPTOR parse_desc;
EXEC SQL GET DESCRIPTOR parse_desc :col_count = COUNT;

この例では、 PREPARE ステートメントを使用してユーザー:stmt が提供した文字列の構文を確認する前に、 parse_desc という名前のSQL記述子を割り当てます。 DESCRIBE ステートメントは、ユーザー指定の文字列を記述子parse_desc に移動します。 EXEC SQL GET DESCRIPTOR の呼び出しは、記述子を調べて、結果セット内の(:col_count) 列の数を検出します。

挿入

INSERT ステートメントを使用して、1つ以上の行をテーブルに追加します。 ECPGPlus INSERT ステートメントの構文はSQLステートメントの構文と同じですが、値が許可される任意の場所でパラメーターマーカーとホスト変数を使用できます。構文は次のとおりです。

[FOR <exec_count>] INSERT INTO <table> [(<column> [, ...])]
  {DEFAULT VALUES |
   VALUES ({<expression> | DEFAULT} [, ...])[, ...] | <query>}
  [RETURNING * | <output_expression> [[ AS ] <output_name>] [, ...]]

FOR exec_count 句を含めて、ステートメントの実行回数を指定します。この句は、 VALUES 句が配列または配列へのポインターを参照する場合にのみ有効です。

  • table は、既存のテーブルの（オプションでスキーマ修飾）名前を指定します。

  • column は、テーブルの列の名前です。列名は、サブフィールド名または配列の添字で修飾できます。すべての列にデフォルト値を使用するには、 DEFAULT VALUES 句を指定します。

  • expression は、対応する列に割り当てられた式、値、ホスト変数、またはパラメーターマーカーです。 DEFAULT を指定して、対応する列をデフォルト値で埋めます。

  • query は、挿入する行を提供するSELECT ステートメントを指定します。

  • output_expression は、各行が挿入された後にINSERT コマンドによって計算されて返される式です。式は、テーブル内の任意の列を参照できます。挿入された行のすべての列を返すには、*を指定します。

  • output_name は、返される列に使用する名前を指定します。

次の例では、 employees テーブルに行を追加します。

INSERT INTO emp (empno, ename, job, hiredate)
    VALUES (8400, :ename, CLERK, 2011-10-31);

注釈

INSERT ステートメントは、ホスト変数`:ename` を使用して`ename` 列の値を指定します。

INSERT ステートメントの使用の詳細については、 PostgreSQL core documentation を参照してください。

開く

OPEN ステートメントを使用して、カーソルを開きます。構文は次のとおりです。

EXEC SQL [FOR <array_size>] OPEN <cursor> [USING <parameters>];

parameters は次のいずれかです。

DESCRIPTOR <SQLDA_descriptor>

または

<host_variable> [ [ INDICATOR ] <indicator_variable>, … ]

そこで：

・ array_size は、取得する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • cursor は、オープンされるカーソルの名前です。

  • parameters は、 DESCRIPTOR SQLDA_descriptor またはカーソルを初期化するhost variables とオプションのindicator variables のコンマ区切りリストのいずれかです。 SQLDA_descriptor を指定する場合、記述子はDESCRIBE ステートメントで初期化する必要があります。

OPEN ステートメントは、 parameters で提供される値を使用してカーソルを初期化します。初期化されると、カーソルを閉じて再度開かない限り、カーソル結果セットは変更されません。アプリケーションが終了すると、カーソルは自動的にクローズされます。

次の例では、 emp テーブルを照会するemployees という名前のカーソルを宣言します。ホスト変数:emp_name に格納されているユーザー指定の値と名前が一致する従業員のemployee number 、name 、salary 、およびcommission を返します。

EXEC SQL DECLARE employees CURSOR FOR
  SELECT
    empno, ename, sal, comm
  FROM
    emp
  WHERE ename = :emp_name;
EXEC SQL OPEN employees;
...

この例では、カーソルを宣言した後、 OPEN ステートメントを使用して、カーソルの内容をクライアントアプリケーションで使用できるようにします。

オープンディスクリプター

OPEN DESCRIPTOR ステートメントを使用して、 SQL記述子でカーソルを開きます。構文は次のとおりです。

EXEC SQL [FOR <array_size>] OPEN <cursor>
  [USING [SQL] DESCRIPTOR <descriptor_name>]
  [INTO [SQL] DESCRIPTOR <descriptor_name>];

そこで：

・ array_size は、取得する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • cursor は、オープンされるカーソルの名前です。

・ descriptor_name は、 SQL記述子名をシングルクォーテーション文字列リテラル、またはカーソルを初期化するクエリーを含むSQL記述子名を含むホスト変数で指定します。

たとえば、次のステートメントは、ホスト変数:employees を使用してemp_cursor という名前のカーソルを開きます。

EXEC SQL OPEN emp_cursor USING DESCRIPTOR :employees;

準備する

準備されたステートメントは、クライアント アプリケーションがタスクを複数回実行する必要がある場合に役立ちます。ステートメントは、実行されるたびにではなく、1回だけ解析、書き込まれ、計画されます。このアプローチにより、反復処理時間が節約されます。

PREPARE ステートメントを使用して、実行するSQLステートメントまたはPL/pgSQLブロックを準備します。ステートメントは2つの形式で入手できます。最初のフォームは次のとおりです。

EXEC SQL [AT <database_name>] PREPARE <statement_name>
  FROM <sql_statement>;

2番目の形式は次のとおりです。

EXEC SQL [AT <database_name>] PREPARE <statement_name>
  AS <sql_statement>;

そこで：

  • database_name は、ステートメントが実行されるデータベース識別子を含むデータベース識別子またはホスト変数です。 AT 句を省略すると、ステートメントは現在のデフォルトデータベースに対して実行されます。

  • statement_name は、準備されたSQL文またはPL/ SQLブロックに関連付けられた識別子です。

  • sql_statement は、 SELECT ステートメント、一重引用符で囲まれた文字列リテラル、またはSQLステートメントのテキストを含むホスト変数の形式を取ることができます。

準備されたステートメントに変数を含めるには、ステートメントを PREPARE したときに変更される可能性のあるステートメント値をプレースホルダー（$1, $2, $3 など）に置き換えます。ステートメントをEXECUTE するときに、各パラメーターの値を指定します。プレースホルダーを置き換える順序で値を指定します。

次の例では、 emp テーブルにレコードを挿入するadd_emp という名前の準備済みステートメントを作成します。

EXEC SQL PREPARE add_emp (int, text, text, numeric) AS
    INSERT INTO emp VALUES($1, $2, $3, $4);

ステートメントを呼び出すたびに、ステートメントに新しいパラメーター値を指定します。

EXEC SQL EXECUTE add_emp(8003, Davis, CLERK, 2000.00);
EXEC SQL EXECUTE add_emp(8004, Myer, CLERK, 2000.00);

注釈

クライアントアプリケーションは、ステートメントが実行される各セッションで`PREPARE` ステートメントを発行する必要があります。準備されたステートメントは、現在のセッションの間のみ持続します。

ロールバック

ROLLBACK ステートメントを使用して、現在のトランザクションを中止し、トランザクションによる更新を破棄します。構文は次のとおりです。

EXEC SQL [AT <database_name>] ROLLBACK [WORK]
  [ { TO [SAVEPOINT] <savepoint> } | RELEASE ]

database_name は、ステートメントの実行対象となるデータベース識別子を含むホスト変数です。 AT 句を省略すると、ステートメントは現在のデフォルトデータベースに対して実行されます。

TO 句を含めて、指定したsavepoint の後に実行されたコマンドを中止します。 SAVEPOINT ステートメントを使用して、 savepoint を定義します。 TO 句を省略すると、 ROLLBACK ステートメントはトランザクションを中止し、すべての更新を破棄します。

RELEASE 句を含めて、アプリケーションにEXEC SQL COMMIT RELEASE を実行させ、接続を閉じます。

次のステートメントを使用して、完全なトランザクションをロールバックします。

EXEC SQL ROLLBACK;

このステートメントを呼び出すと、トランザクションが中止され、すべての変更が元に戻され、セーブポイントが消去され、すべてのトランザクションロックが解放されます。セーブポイント（次の例ではmy_savepoint ）を含めるとします。

EXEC SQL ROLLBACK TO SAVEPOINT my_savepoint;

my_savepoint の後に発生したトランザクションの部分のみがロールバックされます。 my_savepoint は保持されますが、 my_savepoint の後に作成されたセーブポイントは消去されます。

指定したセーブポイントにロールバックすると、そのセーブポイントの後に取得されたすべてのロックが解放されます。

セーブポイント

SAVEPOINT ステートメントを使用して、_savepoint_を定義します。セーブポイントは、トランザクションのマーカーです。 ROLLBACK ステートメントを使用して、現在のトランザクションを中止し、サーバーの状態を指定したセーブポイントの前の状態に戻すことができます。 SAVEPOINT ステートメントの構文は次のとおりです。

EXEC SQL [AT <database_name>] SAVEPOINT <savepoint_name>

そこで：

  • database_name は、セーブポイントが存在するデータベース識別子を含むデータベース識別子またはホスト変数です。 AT 句を省略すると、ステートメントは現在のデフォルトデータベースに対して実行されます。

  • savepoint_name はセーブポイントの名前です。 savepoint_name を再利用すると、元のセーブポイントは破棄されます。

セーブポイントはトランザクションブロックでのみ設定できます。トランザクションブロックには、複数のセーブポイントを含めることができます。

my_savepoint という名前のセーブポイントを作成するには、次のステートメントを含めます。

EXEC SQL SAVEPOINT my_savepoint;

選択

ECPGPlusは、 INTO host_variables 句を提供することにより、 SQL SELECT ステートメントのサポートを拡張します。この句を使用すると、 EDB Postgres Advanced Serverデータベースから指定した情報をホスト変数に選択できます。 SELECT ステートメントの構文は次のとおりです。

EXEC SQL [AT <database_name>]
SELECT
  [ <hint> ]
  [ ALL | DISTINCT [ ON( <expression>, ...) ]]
  select_list INTO <host_variables>

  [ FROM from_item [, from_item ]...]
  [ WHERE condition ]
  [ hierarchical_query_clause ]
  [ GROUP BY expression [, ...]]
  [ HAVING condition ]
  [ { UNION [ ALL ] | INTERSECT | MINUS } (subquery) ]
  [ ORDER BY expression [order_by_options]]
  [ LIMIT { count | ALL }]
  [ OFFSET start [ ROW | ROWS ] ]
  [ FETCH { FIRST | NEXT } [ count ] { ROW | ROWS } ONLY ]
  [ FOR { UPDATE | SHARE } [OF table_name [, ...]][NOWAIT ][...]]

そこで：

  • database_name は、テーブルが存在するデータベースの名前を含むデータベースまたはホスト変数の名前です。この値は、引用符なしの文字列リテラルまたはホスト変数の形式を取ることができます。

  • host_variables は、 SELECT ステートメントによって入力されたホスト変数のリストです。 SELECT ステートメントが複数の行を返す場合、 host_variables は配列でなければなりません。

ECPGPlusは、 PostgreSQL core documentation に記載されているSQL SELECT ステートメントの追加の句のサポートを提供します。

INTO host_variables 句を使用するには、 SELECT ステートメントを指定するときに定義されたホスト変数の名前を含めます。たとえば、次のSELECT ステートメントは、 :emp_name および:emp_sal ホスト変数に従業員の名前と給与のリストを設定します。

EXEC SQL SELECT ename, sal
  INTO :emp_name, :emp_sal
  FROM emp
  WHERE empno = 7988;

拡張されたSELECT ステートメントでは、値が許可される任意の句にパラメーターマーカー（疑問符）を含めることもできます。たとえば、次のクエリには、 WHERE 句にパラメーターマーカーが含まれています。

SELECT * FROM emp WHERE dept_no = ?;

このSELECT ステートメントを使用すると、実行時にdept_no パラメーターマーカーに値を指定できます。

接続を設定する

特定のクライアントアプリケーションで複数の接続が必要になる理由は少なくとも3つあります。

  • ステートメントごとに異なる特権が必要になる場合があります。

  • 同じクライアントで複数のデータベースと対話する必要がある場合。

  • クライアントアプリケーションでの複数の実行スレッドは、接続を同時に共有できません。

SET CONNECTION ステートメントの構文は次のとおりです。

EXEC SQL SET CONNECTION <connection_name>;

connection_name は、データベースへの接続の名前です。

SET CONNECTION ステートメントを使用するには、2番目の形式のCONNECT ステートメントを使用してデータベースへの接続を開きます。 connection_name を指定するには、 AS 句を含めます。

デフォルトでは、現在のスレッドは現在の接続を使用します。 SET CONNECTION ステートメントを使用して、現在のスレッドが使用するデフォルトの接続を指定します。デフォルトの接続は、接続名を明示的に指定しないEXEC SQL ステートメントを実行する場合にのみ使用されます。たとえば、次のステートメントでは AT connection_name 句が含まれていないため、デフォルトの接続を使用します。

EXEC SQL DELETE FROM emp;

このステートメントでは、 AT connection_name 句を使用して接続名を指定しているため、デフォルトの接続を使用しません。

EXEC SQL AT acctg_conn DELETE FROM emp;

たとえば、クライアントアプリケーションが次のいずれかのアプローチを使用して複数の接続を作成および維持するとします。

EXEC SQL CONNECT TO edb AS acctg_conn
  USER alice IDENTIFIED BY acctpwd;

EXEC SQL CONNECT TO edb AS hr_conn
  USER bob IDENTIFIED BY hrpwd;

SET CONNECTION ステートメントを使用して、接続間で変更できます。

SET CONNECTION acctg_conn;

または

SET CONNECTION hr_conn;

サーバーは、接続しているクライアントが使用できる特権を判断するときに、接続に関連付けられた特権を使用します。 acctg_conn 接続を使用する場合、クライアントにはロールalice に関連付けられた特権があります。 hr_conn を使用して接続すると、クライアントにはbob に関連付けられた特権があります。

セットディスクリプター

SET DESCRIPTOR ステートメントを使用して、クライアントアプリケーションがホスト変数または整数値の形式で提供する情報を使用して、記述子領域に値を割り当てます。ステートメントには2つの形式があります。最初のフォームは次のとおりです。

EXEC SQL [FOR <array_size>] SET DESCRIPTOR <descriptor_name>
  VALUE <column_number> <descriptor_item> = <host_variable>;

2番目の形式は次のとおりです。

EXEC SQL [FOR <array_size>] SET DESCRIPTOR <descriptor_name>
  COUNT = integer;

そこで：

・ array_size は、取得する行数を指定する整数値またはホスト変数です。 FOR 句を省略すると、ステートメントは配列のメンバーごとに1回実行されます。

  • descriptor_name は、ディスクリプタ名を一重引用符で囲んだ文字列リテラルまたはディスクリプタ名を格納するホスト変数で指定します。

VALUE 句を含めて、記述子に格納されている情報を説明します。

  • column_number は、記述子内の変数の位置を識別します。

  • descriptor_item は、記述子項目の種類を指定します。

・ host_variable は、項目の値を格納するホスト変数名を指定します。

ECPGPlusは、次のdescriptor_item タイプを実装します。

  • TYPE

  • LENGTH

  • [REF] INDICATOR

  • [REF] DATA

  • [REF] RETURNED LENGTH

たとえば、クライアントアプリケーションは、動的に作成されたクエリの入力をユーザーに求める場合があります。

query_text = promptUser("Enter a query");

動的に作成されたクエリを実行するには、最初にクエリを準備（クエリの構文を解析および検証）してから、 EXEC SQL DESCRIBE INPUT ステートメントを使用してクエリで見つかった入力パラメーターを説明する必要があります。

EXEC SQL ALLOCATE DESCRIPTOR query_params;
EXEC SQL PREPARE emp_query FROM :query_text;

EXEC SQL DESCRIBE INPUT emp_query
  USING SQL DESCRIPTOR query_params;

query_params 記述子には、クエリを記述した後、クエリに必要な各パラメーターに関する情報が含まれています。

この例では、ユーザーが次のように入力したとします。

SELECT ename FROM emp WHERE sal > ? AND job = ?;,

この場合、記述子には2つのパラメーターが記述されています。1つはsal > ? 用、もう1つはjob = ? 用です。

クエリ内のパラメーターマーカー（疑問符）の数、したがってクエリを実行する前に指定する必要がある値の数を確認するには、次を使用します。

EXEC SQL GET DESCRIPTOR … :host_variable = COUNT;

次に、 EXEC SQL GET DESCRIPTOR を使用して各パラメーターの名前を取得できます。 EXEC SQL GET DESCRIPTOR を使用して、パラメーターの数とともに記述子から各パラメーターの型を取得することもできます。または、各value を文字列の形式で指定すると、ECPGはその文字列を必要なデータ型に変換します。

最初のパラメーターのデータ型は numeric です。第2引数の型はvarchar です。最初のパラメーターの名前は sal です。 2番目のパラメーターの名前は job です。

次に、各パラメーターをループして、ユーザーに値の入力を求め、それらの値をホスト変数に保存します。 GET DESCRIPTOR … COUNT を使用して、クエリ内のパラメーターの数を見つけることができます。

EXEC SQL GET DESCRIPTOR query_params
  :param_count = COUNT;

for(param_number = 1;
    param_number <= param_count;
    param_number++)
{

GET DESCRIPTOR を使用して、パラメーターの名前をparam_name ホスト変数にコピーします。

EXEC SQL GET DESCRIPTOR query_params
  VALUE :param_number :param_name = NAME;

reply = promptUser(param_name);
if (reply == NULL)
 reply_ind = 1; /* NULL */
else
 reply_ind = 0; /* NOT NULL */

value を各パラメーターに関連付けるには、 EXEC SQL SET DESCRIPTOR ステートメントを使用します。例：

EXEC SQL SET DESCRIPTOR query_params
  VALUE :param_number DATA = :reply;
EXEC SQL SET DESCRIPTOR query_params
  VALUE :param_number INDICATOR = :reply_ind;
}

これで、 EXEC SQL EXECUTE DESCRIPTOR ステートメントを使用して、サーバーで準備されたステートメントを実行できます。

更新

UPDATE ステートメントを使用して、テーブルに格納されているデータを変更します。構文は次のとおりです。

EXEC SQL [AT <database_name>][FOR <exec_count>]
    UPDATE [ ONLY ] table [ [ AS ] alias ]
    SET {column = { expression | DEFAULT } |
        (column [, ...]) = ({ expression|DEFAULT } [, ...])} [, ...]
    [ FROM from_list ]
    [ WHERE condition | WHERE CURRENT OF cursor_name ]
    [ RETURNING * | output_expression [[ AS ] output_name] [, ...] ]

database_name は、テーブルが存在するデータベースの名前を含むデータベースまたはホスト変数の名前です。この値は、引用符なしの文字列リテラルまたはホスト変数の形式を取ることができます。

FOR exec_count 句を含めて、ステートメントの実行回数を指定します。この句は、 SET または WHERE 句に配列が含まれる場合にのみ有効です。

ECPGPlusは、 PostgreSQL core documentation に記載されているSQL UPDATE ステートメントの追加の句のサポートを提供します。

値を指定する句でホスト変数を使用できます。ホスト変数を使用するには、文書化された UPDATE 句に関連付けられた値を定義された変数に置き換えます。

次のUPDATE ステートメントは、従業員（ :ename ホスト変数で識別）の職務記述書を:new_job ホスト変数に含まれる値に変更します。現在の給与に:increase ホスト変数の値を掛けて、従業員の給与を増やします。

EXEC SQL UPDATE emp
  SET job = :new_job, sal = sal * :increase
  WHERE ename = :ename;

拡張されたUPDATE ステートメントでは、入力値が許可されている句にパラメーターマーカー（疑問符）を含めることもできます。たとえば、 WHERE 句にパラメーターマーカーを使用して、同じ更新ステートメントを書くことができます。

EXEC SQL UPDATE emp
  SET job = ?, sal = sal * ?
  WHERE ename = :ename;

このUPDATE ステートメントを使用すると、ユーザーにjob 列の新しい値の入力を求め、:ename で指定された従業員のsal 列のインクリメント量を提供できます。

いつでも

WHENEVER ステートメントを使用して、 SQLエラーまたは警告が発生したときにクライアントアプリケーションが実行するアクションを指定します。構文は次のとおりです。

EXEC SQL WHENEVER <condition> <action>;

次の表で、 action をトリガーする可能性のあるさまざまな条件について説明します。

Condition

Description

NOT FOUND

サーバーは、行を返さない`SELECT`を検出した場合、または`FETCH`が結果セットの最後に到達した場合、`NOT FOUND`条件を返します。

SQLERROR

サーバーは、 SQLステートメントによって返される重大なエラーを検出すると、 `SQLERROR`条件を返します。

SQLWARNING

サーバーは、 SQLステートメントによって返される致命的でない警告を検出すると、 `SQLWARNING`条件を返します。

次の表では、クライアントがcondition に遭遇した結果として発生するアクションについて説明します。

Action

Description

CALL function [([args])]

Call the named function.

CONTINUE

Proceed to the next statement.

DO BREAK

Emit a C break statement. A break statement can appear in a loop or a switch statement. If executed, the break statement terminates the loop or the switch statement.

DO CONTINUE

Emit a C continue statement. A continue statement can exist only in a loop. If executed, it causes the flow of control to return to the top of the loop.

DO function ([args])

Call the named function.

GOTO label`または`GO TO label

Proceed to the statement that contains the label.

SQLPRINT

Print a message to standard error.

STOP

Stop executing.

次のコードフラグメントは、クライアントアプリケーションで警告が発生した場合にメッセージを出力し、エラーが発生した場合にアプリケーションを中止します。

EXEC SQL WHENEVER SQLWARNING SQLPRINT;
EXEC SQL WHENEVER SQLERROR STOP;

次のコードを含めて、クライアントが問題を警告した後に処理を続行するように指定します。

EXEC SQL WHENEVER SQLWARNING SQLPRINT;

クエリが行を返さない場合、またはカーソルが結果セットの最後に到達した場合に関数を呼び出すには、次のコードを含めます。

EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__);