These functions control miscellaneous details of <application>libpq</application>'s behavior. これらの関数はlibpqの動作の各種詳細を制御します。
PQclientEncoding
#Returns the client encoding. クライアント符号化方式を返します。
int PQclientEncoding(const PGconn *conn
);
Note that it returns the encoding ID, not a symbolic string
such as <literal>EUC_JP</literal>. If unsuccessful, it returns -1.
To convert an encoding ID to an encoding name, you
can use:
これがEUC_JP
などのシンボル文字列ではなく符号化方式IDを返すことに注意してください。
成功しなかった場合には、-1が返ります。
符号化方式IDを符号化方式名に変換するためには以下を使用してください。
char *pg_encoding_to_char(int encoding_id
);
PQsetClientEncoding
#Sets the client encoding. クライアント符号化方式を設定します。
int PQsetClientEncoding(PGconn *conn
, const char *encoding
);
<replaceable>conn</replaceable> is a connection to the server,
and <replaceable>encoding</replaceable> is the encoding you want to
use. If the function successfully sets the encoding, it returns 0,
otherwise -1. The current encoding for this connection can be
determined by using <xref linkend="libpq-PQclientEncoding"/>.
conn
はサーバへの接続、encoding
は使用したい符号化方式です。
この関数は符号化方式の設定に成功すると、ゼロを返します。
さもなくば-1を返します。
この接続における現在の符号化方式はPQclientEncoding
を使用して決定することができます。
PQsetErrorVerbosity
#
Determines the verbosity of messages returned by
<xref linkend="libpq-PQerrorMessage"/> and <xref linkend="libpq-PQresultErrorMessage"/>.
PQerrorMessage
とPQresultErrorMessage
で返されるメッセージの冗長度を決定します。
typedef enum { PQERRORS_TERSE, PQERRORS_DEFAULT, PQERRORS_VERBOSE, PQERRORS_SQLSTATE } PGVerbosity; PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
<xref linkend="libpq-PQsetErrorVerbosity"/> sets the verbosity mode,
returning the connection's previous setting.
In <firstterm>TERSE</firstterm> mode, returned messages include
severity, primary text, and position only; this will normally fit on a
single line. The <firstterm>DEFAULT</firstterm> mode produces messages
that include the above plus any detail, hint, or context fields (these
might span multiple lines). The <firstterm>VERBOSE</firstterm> mode
includes all available fields. The <firstterm>SQLSTATE</firstterm>
mode includes only the error severity and the <symbol>SQLSTATE</symbol>
error code, if one is available (if not, the output is like
<firstterm>TERSE</firstterm> mode).
PQsetErrorVerbosity
は冗長度モードを設定し、接続における以前の状態を返します。
TERSEモードでは、返されるメッセージには深刻度、主テキスト、位置のみが含まれます。
これは通常単一行に収まります。
DEFAULTモードでは、上に加え、詳細、ヒント、文脈フィールドが含まれるメッセージが生成されます(これは複数行に跨るかもしれません。)
VERBOSEモードでは、すべての利用可能なフィールドが含まれます。
SQLSTATEモードでは、エラーの深刻度と、利用可能であればSQLSTATE
エラーコードだけが含まれます(利用できなければ、出力はTERSEモードのようになります)。
Changing the verbosity setting does not affect the messages available
from already-existing <structname>PGresult</structname> objects, only
subsequently-created ones.
(But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you
want to print a previous error with a different verbosity.)
冗長度の変更は、既に存在するPGresult
オブジェクト内から取り出せるメッセージには影響を与えません。
その後に作成されたオブジェクトにのみ影響を与えます。
(ただし、以前のエラーを異なる冗長さで表示したい場合はPQresultVerboseErrorMessage
を参照してください。)
PQsetErrorContextVisibility
#
Determines the handling of <literal>CONTEXT</literal> fields in messages
returned by <xref linkend="libpq-PQerrorMessage"/>
and <xref linkend="libpq-PQresultErrorMessage"/>.
PQerrorMessage
およびPQresultErrorMessage
から返されるメッセージ内のCONTEXT
フィールドの扱いについて決定します。
typedef enum { PQSHOW_CONTEXT_NEVER, PQSHOW_CONTEXT_ERRORS, PQSHOW_CONTEXT_ALWAYS } PGContextVisibility; PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);
<xref linkend="libpq-PQsetErrorContextVisibility"/> sets the context display mode,
returning the connection's previous setting. This mode controls
whether the <literal>CONTEXT</literal> field is included in messages.
The <firstterm>NEVER</firstterm> mode
never includes <literal>CONTEXT</literal>, while <firstterm>ALWAYS</firstterm> always
includes it if available. In <firstterm>ERRORS</firstterm> mode (the
default), <literal>CONTEXT</literal> fields are included only in error
messages, not in notices and warnings.
(However, if the verbosity setting is <firstterm>TERSE</firstterm>
or <firstterm>SQLSTATE</firstterm>, <literal>CONTEXT</literal> fields
are omitted regardless of the context display mode.)
PQsetErrorContextVisibility
はコンテキストの表示モードを設定し、その接続での以前の設定を返します。
このモードはメッセージにCONTEXT
フィールドが含まれるかどうかを制御します。
NEVERモードでは、決してCONTEXT
を含みませんが、ALWAYSではCONTEXT
が利用可能であれば常に含まれます。
ERRORSモード(デフォルト)では、CONTEXT
はエラーメッセージには含まれますが、注意や警告では含まれません。
(しかしながら、冗長設定がTERSEやSQLSTATEの場合は、コンテキストの表示モードに関わらずCONTEXT
フィールドは省略されます。)
Changing this mode does not
affect the messages available from
already-existing <structname>PGresult</structname> objects, only
subsequently-created ones.
(But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you
want to print a previous error with a different display mode.)
このモードを変更しても、既存のPGresult
から取得可能なメッセージには影響を与えず、その後で作成されるものにのみ影響します。
(ただし、以前のエラーについて異なる表示モードで表示したい場合は、PQresultVerboseErrorMessage
を参照してください。)
PQtrace
#Enables tracing of the client/server communication to a debugging file stream. クライアント/サーバ間の通信トレースを有効にし、デバッグ用のファイルストリームに書き出します。
void PQtrace(PGconn *conn, FILE *stream);
Each line consists of: an optional timestamp, a direction indicator
(<literal>F</literal> for messages from client to server
or <literal>B</literal> for messages from server to client),
message length, message type, and message contents.
Non-message contents fields (timestamp, direction, length and message type)
are separated by a tab. Message contents are separated by a space.
Protocol strings are enclosed in double quotes, while strings used as data
values are enclosed in single quotes. Non-printable chars are printed as
hexadecimal escapes.
Further message-type-specific detail can be found in
<xref linkend="protocol-message-formats"/>.
各行は、オプションのタイムスタンプ、方向インジケータ(クライアントからサーバへのメッセージの場合はF
、サーバからクライアントへのメッセージの場合はB
)、メッセージ長、メッセージタイプ、およびメッセージ内容で構成されます。
メッセージ内容以外のフィールド(タイムスタンプ、方向、長さ、メッセージタイプ)はタブで区切られます。
メッセージ内容はスペースで区切られます。
プロトコル文字列は二重引用符で囲まれますが、データ値として使用される文字列は単一引用符で囲まれます。
表示できない文字は16進エスケープとして出力されます。
メッセージタイプ固有の詳細については、53.7を参照してください。
On Windows, if the <application>libpq</application> library and an application are
compiled with different flags, this function call will crash the
application because the internal representation of the <literal>FILE</literal>
pointers differ. Specifically, multithreaded/single-threaded,
release/debug, and static/dynamic flags should be the same for the
library and all applications using that library.
Windowsにおいて、libpqライブラリとアプリケーションを異なるフラグでコンパイルすると、この関数呼び出しでFILE
ポインタの内部表現の違いによりアプリケーションはクラッシュするでしょう。
特に、このライブラリを使用するアプリケーションでは、マルチスレッド/シングルスレッド、リリース/デバッグ、静的リンク/動的リンクに関して、ライブラリと同じフラグを使わなければなりません。
PQsetTraceFlags
#Controls the tracing behavior of client/server communication. クライアント/サーバ通信のトレース動作を制御します。
void PQsetTraceFlags(PGconn *conn, int flags);
<literal>flags</literal> contains flag bits describing the operating mode
of tracing.
If <literal>flags</literal> contains <literal>PQTRACE_SUPPRESS_TIMESTAMPS</literal>,
then the timestamp is not included when printing each message.
If <literal>flags</literal> contains <literal>PQTRACE_REGRESS_MODE</literal>,
then some fields are redacted when printing each message, such as object
OIDs, to make the output more convenient to use in testing frameworks.
This function must be called after calling <function>PQtrace</function>.
flags
には、トレースの動作モードを記述するフラグビットが含まれています。
flags
にPQTRACE_SUPPRESS_TIMESTAMPS
が含まれている場合、各メッセージを出力するときにタイムスタンプは含まれません。
flags
にPQTRACE_REGRESS_MODE
が含まれている場合、各メッセージを出力するときにオブジェクトOIDなどの一部のフィールドが編集され、テストフレームワークで使用しやすくなります。
この関数は、PQtrace
を呼び出した後に呼び出す必要があります。
PQuntrace
#
Disables tracing started by <xref linkend="libpq-PQtrace"/>.
PQtrace
によって起動されたトレース処理を無効にします。
void PQuntrace(PGconn *conn);