他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

34.11. 制御関数

これらの関数はlibpqの動作の各種詳細を制御します。

PQclientEncoding

クライアント符号化方式を返します。

int PQclientEncoding(const PGconn *conn);

これがEUC_JPなどのシンボル文字列ではなく符号化方式IDを返すことに注意してください。 成功しなかった場合には、-1が返ります。 符号化方式IDを符号化方式名に変換するためには以下を使用してください。

char *pg_encoding_to_char(int encoding_id);

PQsetClientEncoding

クライアント符号化方式を設定します。

int PQsetClientEncoding(PGconn *conn, const char *encoding);

connはサーバへの接続、encodingは使用したい符号化方式です。 この関数は符号化方式の設定に成功すると、ゼロを返します。 さもなくば-1を返します。 この接続における現在の符号化方式はPQclientEncodingを使用して決定することができます。

PQsetErrorVerbosity

PQerrorMessagePQresultErrorMessageで返されるメッセージの冗長度を決定します。

typedef enum
{
    PQERRORS_TERSE,
    PQERRORS_DEFAULT,
    PQERRORS_VERBOSE,
    PQERRORS_SQLSTATE
} PGVerbosity;

PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);

PQsetErrorVerbosityは冗長度モードを設定し、接続における以前の状態を返します。 TERSEモードでは、返されるメッセージには深刻度、主テキスト、位置のみが含まれます。 これは通常単一行に収まります。 DEFAULTモードでは、上に加え、詳細、ヒント、文脈フィールドが含まれるメッセージが生成されます(これは複数行に跨るかもしれません。) VERBOSEモードでは、すべての利用可能なフィールドが含まれます。 SQLSTATEモードでは、エラーの深刻度と、利用可能であればSQLSTATEエラーコードだけが含まれます(利用できなければ、出力はTERSEモードのようになります)。

冗長度の変更は、既に存在するPGresultオブジェクト内から取り出せるメッセージには影響を与えません。 その後に作成されたオブジェクトにのみ影響を与えます。 (ただし、以前のエラーを異なる冗長さで表示したい場合はPQresultVerboseErrorMessageを参照してください。)

PQsetErrorContextVisibility

PQerrorMessageおよびPQresultErrorMessageから返されるメッセージ内のCONTEXTフィールドの扱いについて決定します。

typedef enum
{
    PQSHOW_CONTEXT_NEVER,
    PQSHOW_CONTEXT_ERRORS,
    PQSHOW_CONTEXT_ALWAYS
} PGContextVisibility;

PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);

PQsetErrorContextVisibilityはコンテキストの表示モードを設定し、その接続での以前の設定を返します。 このモードはメッセージにCONTEXTフィールドが含まれるかどうかを制御します。 NEVERモードでは、決してCONTEXTを含みませんが、ALWAYSではCONTEXTが利用可能であれば常に含まれます。 ERRORSモード(デフォルト)では、CONTEXTはエラーメッセージには含まれますが、注意や警告では含まれません。 (しかしながら、冗長設定がTERSESQLSTATEの場合は、コンテキストの表示モードに関わらずCONTEXTフィールドは省略されます。)

このモードを変更しても、既存のPGresultから取得可能なメッセージには影響を与えず、その後で作成されるものにのみ影響します。 (ただし、以前のエラーについて異なる表示モードで表示したい場合は、PQresultVerboseErrorMessageを参照してください。)

PQtrace

クライアント/サーバ間の通信トレースを有効にし、デバッグ用のファイルストリームに書き出します。

void PQtrace(PGconn *conn, FILE *stream);

各行は、オプションのタイムスタンプ、方向インジケータ(クライアントからサーバへのメッセージの場合はF、サーバからクライアントへのメッセージの場合はB)、メッセージ長、メッセージタイプ、およびメッセージ内容で構成されます。 メッセージ内容以外のフィールド(タイムスタンプ、方向、長さ、メッセージタイプ)はタブで区切られます。 メッセージ内容はスペースで区切られます。 プロトコル文字列は二重引用符で囲まれますが、データ値として使用される文字列は単一引用符で囲まれます。 表示できない文字は16進エスケープとして出力されます。 メッセージタイプ固有の詳細については、53.7を参照してください。

注記

Windowsにおいて、libpqライブラリとアプリケーションを異なるフラグでコンパイルすると、この関数呼び出しでFILEポインタの内部表現の違いによりアプリケーションはクラッシュするでしょう。 特に、このライブラリを使用するアプリケーションでは、マルチスレッド/シングルスレッド、リリース/デバッグ、静的リンク/動的リンクに関して、ライブラリと同じフラグを使わなければなりません。

PQsetTraceFlags

クライアント/サーバ通信のトレース動作を制御します。

void PQsetTraceFlags(PGconn *conn, int flags);

flagsには、トレースの動作モードを記述するフラグビットが含まれています。 flagsPQTRACE_SUPPRESS_TIMESTAMPSが含まれている場合、各メッセージを出力するときにタイムスタンプは含まれません。 flagsPQTRACE_REGRESS_MODEが含まれている場合、各メッセージを出力するときにオブジェクトOIDなどの一部のフィールドが編集され、テストフレームワークで使用しやすくなります。 この関数は、PQtraceを呼び出した後に呼び出す必要があります。

PQuntrace

PQtraceによって起動されたトレース処理を無効にします。

void PQuntrace(PGconn *conn);