参照先

以下のセクションでは、ecpgPlus言語要素について説明します。

  • Cプリプロセッサディレクティブ

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

  • タイプコード

  • SQLDA構造

  • ECPGPlusステートメント

Cプリプロセッサディレクティブ

ECPGPlusCプリプロセッサは、ECPGPlusを呼び出すモードに依存する2つの動作を強制します。

  • PROC モード

  • 非 PROC モード

Compiling in PROC Mode

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 を指定した場合にのみ機能します。

Using the SELECT_ERROR Precompiler Option

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

SELECT_ERROR={YES|NO}

デフォルト値は YES です。結果セットがホスト変数の容量を超える場合、 SELECT ステートメントはエラーメッセージを返します。 NO を指定すると、 SELECT ステートメントがホスト変数が対応できる数を超える行を返す場合にエラーメッセージを抑制するようにプログラムに指示します。

EXEC ORACLE OPTION ディレクティブとともに SELECT_ERROR を使用します。

Compiling in non-PROC Mode

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

  • Cプリプロセッサディレクティブは、変更せずに出力ファイルにコピーされます。

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

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

サポートされている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 リスト項目にバインドする場合、対応する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

浮く

5、6

ヌル終了文字列（char[length+1]）

9

varchar

22

ダブル

68

符号なし整数

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

Internal Type Code

Server Type

1

VARCHAR2

2

NUMBER

8

長い

11

ROWID

12

DATE

23

RAW

24

ロングロウ

96

CHAR

100

バイナリフロート

101

バイナリダブル

104

ウルイド

187

タイムスタンプ

188

タイムスタンプW/タイムゾーン

189

間隔月

190

2日目から2日目

232

TIMESTAMPLOCAL_TZ

SQLDA構造

OracleDynamicSQLメソッド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         */
};

Parameters

N - maximum number of entries

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

V - data values

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

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

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

アプリケーションは、各値を保持するために必要なスペースを割り当てる必要があります。 SELECT リスト値にスペースを割り当てる方法の例については、 displayResultSet 関数を参照してください。

L - length of each data value

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

T - data types

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

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

  • SELECT リスト記述子の場合、 DESCRIBE SELECT LIST ステートメントは T 配列の各メンバーを設定して、対応する列にあるデータのタイプを反映します。

FETCH ステートメントを実行する前に「10」配列のメンバーを変更して、ECPGPlusに対応する値を特定のデータ型に変換させることができます。たとえば、 DESCRIBE SELECT LIST ステートメントが特定の列のタイプが DATE であることを示している場合、対応する「10」メンバーを変更して、次の FETCH ステートメントがNULLで終わる形式でその値を返すように要求できます文字列。「10」配列の各メンバーは、数値タイプコードです（タイプコードのリストについては、「タイプコード<＃type-codes>`__」を参照してください）。 DESCRIBE SELECT LIST ステートメントで返されるタイプコードは、 FETCH ステートメントで予期されるタイプコードとは異なります。 DESCRIBE SELECT LIST ステートメントの実行後、「10」の各メンバーは、対応する列がNULL可能かどうかを示すデータ型*および* フラグをエンコードします。「12」関数を使用して、T配列のメンバーから型コードとNULL可能フラグを抽出できます。「12」関数のシグネチャは次のとおりです。

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

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

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

I - indicator variables

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

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

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

F - number of entries

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

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

  • バインド記述子の場合、ステートメントで見つかったパラメーターの数が記述子で許可されている値の最大数（ N 構造体メンバーによって決定される）以下の場合、 F には正の数が含まれます。ステートメントにパラメーターマーカーが含まれていない場合は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コンパイラへの命令です。

AdvancedServerSQLステートメントをCプログラムに埋め込むことができます。各ステートメントはキーワード 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 ステートメントは、AdvancedServerでのみ機能します。 CALL ステートメントには2つの形式があります。最初の形式は*関数* を呼び出すために使用されます:

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

2番目の形式は、procedure を呼び出すために使用されます。

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 は、AdvancedServerデータベースとの接続を確立するために使用されるロールです。指定されたロールの特権は、接続を介して実行されるすべてのコマンドに適用されます。

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 は、カーソルが動作するデータベースの名前です。この値は、識別子またはホスト変数の形式を取る場合があります。データベース名を指定しない場合、 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 を宣言するコマンドを呼び出した後、 acctg データベースは、接続の確立時または AT 句で名前で参照できます。

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

宣言文

DECLARE STATEMENT ディレクティブを使用して、SQLステートメントの識別子を宣言します。AdvancedServerは、 DECLARE STATEMENT ディレクティブの2つのバージョンをサポートしています。

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

そして

EXEC SQL DECLARE STATEMENT <statement_name>;

どこで:

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

database_name はデータベースの名前を指定します。この値は、識別子または識別子を含むホスト変数の形式をとることがあります。

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 句から対応する値を受け取ります。

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

DELETE FROM emp WHERE sal > :max_sal;

DELETE ステートメントの使用の詳細については、次の場所にあるPostgreSQLCoreドキュメントを参照してください。

DESCRIBE

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変数の名前です。 DESCRIBE ステートメントを実行する前に sqlald() を呼び出して（および記述子を初期化して）記述子のスペースを割り当てる必要があります。

DESCRIBE ステートメントの最初の形式を実行すると、ECPGは、指定された記述子に、ステートメントで*必要* になっている各入力変数の説明を入力します。たとえば、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互換の代替構文です。

DESCRIBEDESCRIPTOR

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 キーワードを含めて、すべてのアクティブな接続を閉じるようにECPGPlusに指示します。

次の例では、 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 句を含めます。

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

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 ステートメントを使用して、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 ステートメントとともにステートメントに割り当てられた識別子を指定します。

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

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

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

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

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

EXECUTE...ENDEXEC

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 ステートメントはAdvancedServerでのみサポートされています。

即時実行

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

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
    SELECT empno, ename, esal FROM emp
EXEC SQL OPEN emp_cursor
EXEC SQL FETCH emp_cursor INTO :emp_no, :emp_name, :emp_sal;

FETCHDESCRIPTOR

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

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

どこで:

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

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

INTO 句を含めて、 EXECUTE ステートメントが準備されたステートメントによって返された結果を書き込むSQL記述子を指定します。 descriptor_name は、記述子の名前（単一引用符で囲まれた文字列リテラルとして）、または記述子の名前を含むホスト変数を指定します。使用する前に、 ALLOCATE DESCRIPTOR ステートメントを使用して記述子を割り当てる必要があります。

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

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) から提供された文字列を構文チェックする前に、SQL記述子（ parse_desc という名前）を割り当てます。 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 ステートメントの使用の詳細については、次の場所にあるPostgreSQLCoreドキュメントを参照してください。

開く

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 で指定された値を使用してカーソルを初期化します。初期化されると、カーソルを閉じて再度開かない限り、カーソル結果セットは変更されません。アプリケーションが終了すると、カーソルは自動的に閉じられます。

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

  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 句を省略すると、ステートメントは現在のデフォルトデータベースに対して実行されます。

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

アプリケーションに EXEC SQL COMMIT RELEASE を実行させ、接続を閉じるには、 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 ステートメントのサポートを拡張します。この句を使用すると、指定された情報をAdvancedServerデータベースからホスト変数に選択できます。 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は、次の場所にあるPostgreSQLCoreドキュメントに記載されているSQL SELECT ステートメントの追加句のサポートを提供します。

INTO host_variables 句を使用するには、 SELECT ステートメントを指定するときに定義済みのホスト変数の名前を含めます。たとえば、次の SELECT ステートメントは、 :emp_name および :emp_sal ホスト変数に employee names および salaries のリストを取り込みます。

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 ステートメントを使用するには、 CONNECT ステートメントの2番目の形式を使用してデータベースへの接続を開く必要があります。AS句を含めて connection_name を指定します。

デフォルトでは、現在のスレッドは現在の接続を使用します。 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");

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

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 = ?;,

この場合、記述子には sal > ? と job = ? の2つのパラメーターが記述されます。

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

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は、次の場所にあるPostgreSQLCoreドキュメントに記載されている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

見つかりません

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

SQLERROR

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

SQL警告

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

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

Action

Description

CALL関数[（[args]）]

指定された関数を呼び出すようにクライアントアプリケーションに指示します。

続ける

次のステートメントに進むようにクライアントアプリケーションに指示します。

休憩する

クライアントアプリケーションにCbreakステートメントを指示します。breakステートメントは、ループまたはswitchステートメントに現れる場合があります。実行されると、breakステートメントはループまたはswitchステートメントを終了します。

続ける

クライアントアプリケーションにCcontinueステートメントを発行するよう指示します。continueステートメントはループ内にのみ存在でき、実行された場合、制御フローがループの先頭に戻ります。

DO関数（[args]）

指定された関数を呼び出すようにクライアントアプリケーションに指示します。

GOTOラベルまたはGOTOラベル

ラベルを含むステートメントに進むようにクライアントアプリケーションに指示します。

SQLPRINT

クライアントアプリケーションにメッセージを標準エラーに出力するよう指示します。

止まる

実行を停止するようにクライアントアプリケーションに指示します。

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

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

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

EXEC SQL WHENEVER SQLWARNING SQLPRINT;

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

EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__);