Reference¶

</ div>

以下のセクションでは、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;

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

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

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

SELECT_ERROR={YES|NO}

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

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

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

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

Cプリプロセッサ指示子は、変更せずに出力ファイルにコピーされます。
EXEC SQL BEGIN/END DECLAREセクション内でホスト変数として使用する各C変数のタイプと名前を宣言する必要があります。

非PROCモードで呼び出されると、ECPGはPostgreSQL Core文書で説明されている動作を実装します。

</ div>

サポートされている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	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

</ div>

SQLDA構造¶

オラクル Dynamic 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-リストディスクリプタの場合、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構造体のメンバは、ディスクリプタされた各列（またはパラメータ）に1つずつ、データ型の配列を指します。

バインドディスクリプタの場合、T配列の各メンバを設定して、ECPGPlusに各パラメータのデータタイプを通知する必要があります。
SELECT-リストディスクリプタの場合、DESCRIBE SELECT LISTステートメントは、T配列の各メンバを、対応する列にあるデータのタイプを反映するように設定します。

FETCHステートメントを実行する前にT配列のメンバを変更して、ECPGPlusが対応する値を特定のデータタイプに変換するように強制できます。例、特定の列がDATE型であることをDESCRIBE SELECT LISTステートメントが示す場合、対応するTメンバを変更して、次のFETCHステートメントがNULLで終わる文字列のフォームでその値を結果ように要求できます。 T配列の各メンバは、数値型コード（型コードのリストを参照）。 DESCRIBE SELECT LISTステートメントによって返されるタイプコードは、FETCHステートメントによって予期されるタイプコードとは異なります。 DESCRIBE SELECT LISTステートメントの実行後、Tの各メンバは、対応する列がNULL可能かどうかを示すデータタイプおよびフラグをエンコードします。このファンクションを使用して、T配列のメンバから型コードとNULL可能フラグを抽出できます。ファンクションのシグネチャは次のとおりです。

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コンパイラへの命令です。

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

EXEC SQL <sql_command_body>;

ここで、sql_command_bodyは標準SQLステートメントを表します。ホスト変数は、 SQLステートメントが評価式を予期する任意の場所で使用できます。値式のホスト変数の置換の詳細については、Declaring Host Variablesを参照してください。

ECPGPlusは、一部のステートメントのPostgreSQLサーバサイドの構文を拡張します。これらのステートメントの構文の違いについては、次のリファレンスセクションで説明します。他のSQLコマンドのサポートされている構文の完全なリファレンスについては、次の場所にある* PostgreSQL Core Documentation *を参照してください。

< https://www.postgresql.org/docs/current/ 静的/sql-commands.html >

記述子の割り当て¶

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ステートメントは、 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つはオラクルデータベースと互換性があり、もう1つは互換性がありません。

最初のフォームは、オラクルデータベースと互換性があります。

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

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

次のコードは、フラグメントステートメントの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ステートメント（例ステートメントなど）で使用するデータベース識別子を宣言します。構文は次のとおりです。

EXEC SQL DECLARE <database_name> DATABASE;

どこで：

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

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

EXEC SQL DECLARE acctg DATABASE;

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

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

宣言文¶

DECLARE STATEMENTディレクティブを使用して、 SQLステートメントの識別子を宣言します。 Advanced Serverは、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ステートメントの使用の詳細については、次の場所にあるPostgreSQL Core文書を参照してください。

< https://www.postgresql.org/docs/current/ 静的/sql-delete.html >

記述¶

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互換構文です。

DESCRIBE DESCRIPTOR¶

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句を含めます。

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ステートメントを使用して、 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 … 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;

!!! Note * EXECUTE…END EXECステートメントは、 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¶

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で指定されたホスト変数（およびオプショナルのインジケーター変数）を設定します。

次のコードは、フラグメントというテーブルから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¶

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という名前付けのディスクリプタを割り当てます。次に、結果セットの行をループする前に、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

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

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');

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

INSERTステートメントの使用の詳細については、次の場所にあるPostgreSQL Core文書を参照してください。

< https://www.postgresql.org/docs/current/ 静的/sql-insert.html >

開く¶

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テーブルを照会して、ユーザーが指定した値（ホスト変数:emp_nameに格納されている）と一致する従業員の名前、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ステートメントを使用しmake、カーソルの内容をクライアントアプリケーションで使用できるようにします。

記述子を開く¶

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);

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

ロールバック¶

ROLLBACKステートメントを使用して、現在のトランザクションをアボートし、トランザクションによって行われた更新を破棄します。構文は次のとおりです。

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

どこで：

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

指定されたsavepointの後に実行されたコマンドをアボートするには、TO句を含めます。 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ステートメントのサポートを拡張します。この句により、指定された情報を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は、次のURLで入手可能なPostgreSQL Core文書に記載されているSQL SELECTステートメントの追加句のサポートを提供します。

< https://www.postgresql.org/docs/current/ 静的/sql-select.html >

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¶

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ステートメントを使用してクエリーで見つかった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 = ?;,

この場合、ディスクリプタは、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は、次のURLで入手可能なPostgreSQL Core文書に記載されているSQL UPDATEステートメントの追加句のサポートを提供します。

< https://www.postgresql.org/docs/current/ 静的/sql-update.html >

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

次のUPDATEステートメントは、従業員のジョブ記述（:enameホスト変数に含まれる値に変更し、現在の給与に: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ステートメントを使用すると、プロンプト列の新しい値をユーザに求め、:enameで指定された従業員のsal列の増分量を提供できます。

いつでも¶

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

EXEC SQL WHENEVER <condition> <action>;

次の表に、actionをトリガーする可能性のあるさまざまな条件を示します。

Condition	Description
NOT FOUND	サーバーは、行を返さない`SELECT`に遭遇したとき、または`FETCH`が結果セットの最後に到達したときに、`NOT FOUND`条件を返します。
SQLERROR	サーバーは、 SQLステートメントによって返された重大なエラーを検出すると、`SQLERROR`条件を返します。
SQLWARNING	サーバーは、 SQLステートメントによって返される致命的でないワーニングを検出すると、`SQLWARNING`条件を返します。
	NA

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

Action	Description
CALL function [([args])]	名前付けた`function`を呼び出すようにクライアントアプリケーションに指示します。
CONTINUE	次のステートメントに進むようにクライアントアプリケーションに指示します。
DO BREAK	クライアントアプリケーションにCbreakステートメントを指示します。 breakステートメントは、`loop`または`switch`ステートメントに表示される場合があります。実行されると、breakステートメントは`loop`または`switch`ステートメントを終了します。
DO CONTINUE	C`continue`ステートメントを発行するようにクライアントアプリケーションに指示します。 `continue`ステートメントはループ内にのみ存在でき、実行されると、制御フローがループの先頭に結果ます。
DO function ([args])	名前付けた`function`を呼び出すようにクライアントアプリケーションに指示します。
GOTO label or GO TO label	`label`を含むステートメントに進むようにクライアントアプリケーションに指示します。
SQLPRINT	標準エラーにメッセージをプリントするようにクライアントアプリケーションに指示します。
STOP	実行を停止するようにクライアントアプリケーションに指示します。
	NA

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

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

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

EXEC SQL WHENEVER SQLWARNING SQLPRINT;

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

EXEC SQL WHENEVER NOT FOUND CALL error_handler(__LINE__);

Reference¶

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

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

型コード¶

SQLDA構造¶

ECPGPlusステートメント¶

記述子の割り当て¶

電話¶

閉じる¶

コミット¶

接続¶

記述子の割り当て解除¶

宣言カーソル¶

データベースの宣言¶

宣言文¶

削除¶

記述¶

DESCRIBE DESCRIPTOR¶

切断¶

実行¶

記述子の実行¶

EXECUTE … END EXEC¶

即時実行¶

FETCH¶

FETCH DESCRIPTOR¶

記述子を取得する¶

挿入¶

開く¶

記述子を開く¶

準備する¶

ロールバック¶

セーブポイント¶

選択¶

接続を設定¶

SET DESCRIPTOR¶

更新¶

いつでも¶

前のトピックへ

目次