接続状態関数

PostgreSQL 8.0.0 文書
前のページ | 巻戻し | 第 27章libpq - C ライブラリ | 早送り | 次のページ

# 27.2. 接続状態関数

これらの関数は、既存のデータベース接続オブジェクトの状態を調べるために役立ちます。

> ティップ: libpqアプリケーションプログラマは`PGconn`による抽象化に注意を払うべきです。 `PGconn`の内容は以下に挙げるアクセッサ関数を使って取り出してください。 `PGconn`構造体中のフィールドは将来予告なく変更されることがありますので、直接フィールドを参照することは避けてください。 （PostgreSQLリリース6.4から、`PGconn構造体`の定義を `libpq-fe.h`の中から外しました。 以前作成したプログラムが`PGconn`のフィールドを直接操作している場合、`libpq-int.h`をインクルードすれば使い続けることができます。 しかし、そのプログラムは是非とも修正してください。）

以下の関数は、接続で確立したパラメータの値を返します。 これらの値は`PGconn`の存続期間中で固定されています。

`PQdb`

  接続したデータベース名を返します。

      char *PQdb(const PGconn *conn);

`PQuser`

  接続したユーザ名を返します。

      char *PQuser(const PGconn *conn);

`PQpass`

  接続したパスワードを返します。

      char *PQpass(const PGconn *conn);

`PQhost`

  接続したサーバホスト名を返します。

      char *PQhost(const PGconn *conn);

`PQport`

  接続したポートを返します。

      char *PQport(const PGconn *conn);

`PQtty`

  接続のデバッグ用TTY を返します。 (これは廃れたものです。サーバはもはやTTY設定を参照しません。 後方互換性のためにこの関数が残っています。)

      char *PQtty(const PGconn *conn);

`PQoptions`

  接続要求時に渡されたコマンドラインオプションを返します。

      char *PQoptions(const PGconn *conn);

以下の関数は、`PGconn`に対して操作を行うことで変更可能な状態データを返します。

`PQstatus`

  接続の状態を返します。

      ConnStatusType PQstatus(const PGconn *conn);

  この状態は、多くの値の中の一つとなります。 しかし、その内`CONNECTION_OK` と `CONNECTION_BAD`の2つのみが非同期接続手順以外で見られます。 データベースへの接続に問題がなければ、`CONNECTION_OK`状態になります。 接続に失敗している場合は`CONNECTION_BAD`状態となります。 通常、OK状態は`PQfinish`まで維持されますが、通信失敗により早まって`CONNECTION_BAD`になる場合もあります。 その場合、アプリケーションは`PQreset`を呼び出して修復を試みることができます。

  その他の起こり得る状態コードについては`PQconnectStart` と `PQconnectPoll`の項目を参照してください。

`PQtransactionStatus`

  サーバの現在のトランザクション内部状態を返します。

      PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

  この状態は、`PQTRANS_IDLE` (現在待機中)、`PQTRANS_ACTIVE` (コマンド実行中)、`PQTRANS_INTRANS` (有効なトランザクションブロック内で待機中)、`PQTRANS_INERROR` (無効なトランザクションブロック内で待機中)となり得ます。 接続に問題がある場合のみ`PQTRANS_UNKNOWN`が報告されます。 サーバへの問い合わせの送信が完了したが、まだ完了していない場合のみ`PQTRANS_ACTIVE`が報告されます。

  注意
  `autocommit`パラメータを無効にしたPostgreSQL 7.3 サーバを使用する場合、`PQtransactionStatus`は間違った結果を返します。 サーバサイドでの自動コミットは廃止され、その後のバージョンのサーバでは存在しません。

`PQparameterStatus`

  サーバの現在のパラメータ設定を検索します。

      const char *PQparameterStatus(const PGconn *conn, const char *paramName);

  あるパラメータ値は、接続開始時にサーバによって自動的に、もしくは、その値が変更された時は常に報告されます。 `PQparameterStatus`は、それらの設定の調査に役立ちます。 パラメータの現在値がわかればその値を、わからない場合は`NULL`を返します。

  現在のリリースで報告されるパラメータには、`server_version`、`server_encoding`、`client_encoding`、`is_superuser`、`session_authorization`、`DateStyle`、`TimeZone`、および`integer_datetimes`があります。 （8.0より前までのリリースでは`server_encoding`、`TimeZone`、および`integer_datetimes`は報告されませんでした。 ） `server_version`、`server_encoding`、および、`integer_datetimes`は起動後変更することができないことに注意してください。

  プロトコル3.0より前のサーバはパラメータ設定を報告しません。 しかし、libpqには、`server_version`と`client_encoding`の値を取り出す仕組みがとりあえずあります。 アプリケーションは、付け焼き刃なコードでこれらの値を決定するのではなく、`PQparameterStatus`を使用することが求められています。 (しかし、3.0より前の接続では、接続開始後に`SET`による`client_encoding`の変更は`PQparameterStatus`に反映されないことに注意してください。) `server_version`については`PQserverVersion`も参照してください。 この関数は、より比較し易いこの情報を数値形式で返します。

  返されるポインタは`const`と宣言されていますが、実際には`PGconn`構造体に関連付けされた変化する領域を指し示します。 このポインタが問い合わせに渡って有効なままであるとは考えないでください。

`PQprotocolVersion`

  使用されるフロントエンド/バックエンドプロトコルを調査します。

      int PQprotocolVersion(const PGconn *conn);

  ある機能がサポートされているかどうかを決定するために、この関数を使用することができます。 現在、取り得る値は2(2.0プロトコル)、3(3.0プロトコル)、あるいは0(接続不良)です。 これは、接続の開始が完了した後で変更することはできません。 しかし、理論的には接続のリセット時に変更可能です。 PostgreSQL 7.4以降での通信時、通常3.0プロトコルが使用されます。 7.4より前のサーバでは2.0プロトコルのみをサポートします。 (1.0プロトコルは廃止され、libpqではサポートされていません。)

`PQserverVersion`

  バックエンドのバージョンの整数表現を返します。

      int PQserverVersion(const PGconn *conn);

  これを使用してアプリケーションは接続したデータベースサーバをバージョンを決定することができます。 この数値の形式は、メジャー、マイナー、リビジョン番号を2桁の10進数に変換し、連結させたものです。 例えば、バージョン7.4.2では70402を返し、バージョン8.1では80100を返します。 （先頭の0は現れません。） 接続不良の場合は0が返されます。

`PQerrorMessage`

  接続における操作において、最も最近に生成されたエラーメッセージを返します。

      char *PQerrorMessage(const PGconn *conn);

  ほとんど全てのlibpq関数は、失敗時に`PQerrorMessage`用のメッセージを設定します。 libpqでの決まりとして、空文字でなければ改行が含まれることに注意してください。 呼び出し元はこの結果を直接解放してはいけません。 関連する`PGconn`ハンドルが`PQfinish`に渡された時にこれは解放されます。 `PGconn`構造体への操作を跨って、この結果文字列が同一であると想定してはいけません。

`PQsocket`

  サーバとの接続ソケットに対するファイル記述子番号を得ます。 有効な記述子なら値は 0 以上です。 -1 の場合は、サーバとの接続がまだ開いていないことを示します。 (これは通常の操作では変更することはできません。接続設定中やリセット中に変更されます。)

      int PQsocket(const PGconn *conn);

`PQbackendPID`

  接続を処理するバックエンドサーバのプロセスID(PID)を返します。

      int PQbackendPID(const PGconn *conn);

  バックエンドの PID は、デバッグする場合や`NOTIFY`メッセージ （これは通知を発行したバックエンドプロセスの PID を含んでいます） の比較に便利です。 この PID はデータベースサーバホスト上で実行されているプロセスのものであり、ローカルホスト側のものではありません！ 注意してください。

`PQgetssl`

  接続で使用されている SSL 構造体を返します。 SSL が使用されていない場合は、ヌルを返します。

      SSL *PQgetssl(const PGconn *conn);

  この構造体は、暗号化レベルの検証やサーバ証明書のチェックなどに役立ちます。 この構造体については、OpenSSLの文書を参照してください。

  この関数の正しいプロトタイプを得るには、`USE_SSL` を定義する必要があります。 こうすると、OpenSSL の `ssl.h` も自動的にインクルードされます。

前のページ | ホーム | 次のページ
libpq - C ライブラリ | 上に戻る | コマンド実行関数