バージョンごとのドキュメント一覧

32.11. 制御関数 #

<title>Control Functions</title>

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はエラーメッセージには含まれますが、注意や警告では含まれません。 (しかしながら、冗長設定がTERSESQLSTATEの場合は、コンテキストの表示モードに関わらず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には、トレースの動作モードを記述するフラグビットが含まれています。 flagsPQTRACE_SUPPRESS_TIMESTAMPSが含まれている場合、各メッセージを出力するときにタイムスタンプは含まれません。 flagsPQTRACE_REGRESS_MODEが含まれている場合、各メッセージを出力するときにオブジェクトOIDなどの一部のフィールドが編集され、テストフレームワークで使用しやすくなります。 この関数は、PQtraceを呼び出した後に呼び出す必要があります。

PQuntrace #

Disables tracing started by <xref linkend="libpq-PQtrace"/>. PQtraceによって起動されたトレース処理を無効にします。

void PQuntrace(PGconn *conn);