Documentation PostgreSQL 15.15 » Interfaces client » libpq -- Bibliothèque C » Fonctions de contrôle

Précédent | Niveau supérieur | Suivant
34.10. Fonctions associées à la commande `COPY` | Sommaire | 34.12. Fonctions diverses

## 34.11. Fonctions de contrôle

Ces fonctions contrôlent divers détails du comportement de libpq.

`PQclientEncoding`

  Renvoie l'encodage client.

            int PQclientEncoding(const PGconn *conn);

  Notez qu'il renvoie l'ID de l'encodage, pas une chaîne symbolique telle que `EUC_JP`. Renvoie -1 en cas d'échec. Pour convertir un ID d'encodage en nom, vous pouvez utiliser :

             char *pg_encoding_to_char(int encoding_id);

`PQsetClientEncoding`

  Configure l'encodage client.

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

  `conn` est la connexion au serveur, et `encoding` est l'encodage que vous voulez utiliser. Si la fonction initialise l'encodage avec succès, elle renvoie 0, sinon -1. L'encodage en cours pour cette connexion peut être déterminé en utilisant `PQclientEncoding` .

`PQsetErrorVerbosity`

  Détermine la verbosité des messages renvoyés par `PQerrorMessage` et `PQresultErrorMessage`.

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

             PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);

  `PQsetErrorVerbosity` initialise le mode de verbosité, renvoyant le paramétrage précédant de cette connexion. Dans le mode TERSE, les messages renvoyés incluent seulement la sévérité, le texte principal et la position ; ceci tiendra normalement sur une seule ligne. Le mode DEFAULT produit des messages qui incluent ces champs ainsi que les champs détail, astuce ou contexte (ils pourraient être sur plusieurs lignes). Le mode VERBOSE inclut tous les champs disponibles. Le mode SQLSTATE inclut seulement la sévérité de l'erreur et le code d'erreur `SQLSTATE`, s'il est disponible (dans le cas contraire, la sortie est identique au mode TERSE).

  Modifier la verbosité n'affecte pas les messages disponibles à partir d'objets `PGresult` déjà existants, seulement ceux créés après. (Mais voyez `PQresultVerboseErrorMessage` si vous voulez afficher une erreur précédente avec une verbosité différente).

`PQsetErrorContextVisibility`

  Détermine la gestion des champs `CONTEXT` dans les messages renvoyées par `PQerrorMessage` et `PQresultErrorMessage`.

      typedef enum
      {
          PQSHOW_CONTEXT_NEVER,
          PQSHOW_CONTEXT_ERRORS,
          PQSHOW_CONTEXT_ALWAYS
      } PGContextVisibility;

      PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);

  `PQsetErrorContextVisibility` configure le mode d'affichage du contexte, renvoyant la précédente configuration de la connexion. Ce mode contrôle si le champ `CONTEXT` est inclus dans les messages. Le mode NEVER n'inclut jamais `CONTEXT`, alors que ALWAYS l'inclut en permanence s'il est disponible. Dans le mode par défaut, ERRORS, les champs `CONTEXT` sont inclus seulement pour les messages d'erreur, et non pas pour les messages d'informations et d'avertissements. (Cependant, si le paramètre verbosity est TERSE ou SQLSTATE, les champs `CONTEXT` sont omis quelque soit le contexte de mode d'affichage.)

  La modification de ce mode n'affecte pas les messages disponibles à partir des objets `PGresult` déjà existants, seulement ceux créés après. (Cependant, voyez `PQresultVerboseErrorMessage` si vous voulez afficher une erreur précédente avec un mode d'affichage différent.)

`PQtrace`

  Active la trace de la communication entre client et serveur vers un fichier de débogage.

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

  Chaque ligne consiste en : un horodatage optionnel, un indicateur de direction(`F` pour les messages du client au serveur ou `B` pour les messages du serveur au client), la longueur du message, le type du message et le contenu du message. Les champs autre que le contenu du message (horodatage, direction, longueur et type) sont séparés par une tabulation. Le contenu du message est séparé par un espace. Les chaînes du protocole sont entourées de guillemets doubles alors que les chaînes utilisées comme valeurs de données sont entourées de guillemets simples. Les caractères non affichables sont affichés sous la forme d'échappement hexadécimaux. Plus d'informations spécifique au type de message sont disponibles dans Section 55.7.

  ### Note

  Sur Windows, si la bibliothèque libpq et une application sont compilées avec des options différentes, cet appel de fonction fera planter l'application car la représentation interne des pointeurs `FILE` diffère. Spécifiquement, les options multi-threaded/single-threaded, release/debug et static/dynamic devraient être identiques pour la bibliothèque et les applications qui l'utilisent.

`PQsetTraceFlags`

  Contrôle le comportement des traces sur la communication client/serveur.

      void PQsetTraceFlags(PGconn *conn, int flags);

  `flags` contient des bits décrivant le mode opérationnel des traces. Si `flags` contient `PQTRACE_SUPPRESS_TIMESTAMPS`, alors l'horodatage n'est pas inclus lors de l'affichage de chaque message. Si `flags` contient `PQTRACE_REGRESS_MODE`, alors certains champs sont modifiés lors de la sortie de chaque message, comme par exemple l'OID de l'objet, pour rendre la sortie plus agréable à utiliser dans des environnements de tests. Cette fonction doit être appelée après l'appel à `PQtrace`.

`PQuntrace`

  Désactive les traces commencées avec `PQtrace`.

      void PQuntrace(PGconn *conn);