これらの関数は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
PQerrorMessage
とPQresultErrorMessage
で返されるメッセージの冗長度を決定します。
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
はエラーメッセージには含まれますが、注意や警告では含まれません。
(しかしながら、冗長設定がTERSEやSQLSTATEの場合は、コンテキストの表示モードに関わらず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
には、トレースの動作モードを記述するフラグビットが含まれています。
flags
にPQTRACE_SUPPRESS_TIMESTAMPS
が含まれている場合、各メッセージを出力するときにタイムスタンプは含まれません。
flags
にPQTRACE_REGRESS_MODE
が含まれている場合、各メッセージを出力するときにオブジェクトOIDなどの一部のフィールドが編集され、テストフレームワークで使用しやすくなります。
この関数は、PQtrace
を呼び出した後に呼び出す必要があります。
PQuntrace
PQtrace
によって起動されたトレース処理を無効にします。
void PQuntrace(PGconn *conn);