Description

db2_pconnect(
    string $database,
    ?string $username,
    ?string $password,
    array $options = []
): resource|false

Retourne une connexion persistante à une base de données IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

Pour plus d'informations sur les connexions persistantes, voir Connexions persistantes aux bases de données.

En appelant db2_close() sur une connexion persistante, une erreur sera affichée toujours true, mais les connexions des clients DB2 demeureront ouvertes et attendront de servir la prochaine demande de la fonction db2_pconnect().

Les utilisateurs de versions 1.9.0 ou plus d'ibm_db2 doivent savoir que l'extension exécutera un rollback sur une transaction dans une connexion persistante à la fin de la requête, terminant ainsi la transaction. Ceci évite un blocage transactionnel vers la requête suivante sur la même connexion si l'exécution du script se termine avant la transaction.

Liste de paramètres

database

Pour une connexion cataloguée à une base de données, database représente l'alias de la base de données dans le catalogue du client DB2.

Pour une connexion non cataloguée à une base de données, database représente une chaîne de connexion complète au format suivant :

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

Note:
Lors de la connexion à Db2 sur IBM i, les appels système sous-jacents » SQLDriverConnect, n'acceptent que DSN, UID et PWD pour la » chaîne de connexion. Comme suit :
DSN=database;UID=username;PWD=password;

où les paramètres représentent les valeurs suivantes :

database: Le nom de la base de données.
hostname: Le nom d'hôte ou l'adresse IP du serveur de la base de données.
port: Le port TCP/IP sur lequel la base de données écoute les requêtes.
username: Le nom d'utilisateur utilisé pour la connexion à la base de données.
password: Le mot de passe utilisé pour la connexion à la base de données.

username

Le nom d'utilisateur utilisé pour la connexion à la base de données.

password

Le mot de passe utilisé pour la connexion à la base de données.

options

Un tableau associatif des options de connexion qui affecteront le comportement de la connexion, où les valeurs des clés incluent :

autocommit: La valeur DB2_AUTOCOMMIT_ON active l'autocommit sur cette connexion. La valeur DB2_AUTOCOMMIT_OFF désactive l'autocommit pour cette connexion.
DB2_ATTR_CASE: Passer la valeur DB2_CASE_NATURAL spécifie que les noms de colonnes seront retournés dans leurs casses naturelles. Passer la valeur DB2_CASE_LOWER spécifie que les noms de colonnes seront retournés en minuscule. Passer la valeur DB2_CASE_UPPER spécifie que les noms de colonnes seront retournés en majuscule.
CURSOR: Passer la valeur DB2_FORWARD_ONLY spécifie un curseur uniquement suivant pour une ressource de requête. C'est le type de curseur par défaut et est supporté sur tous les serveurs de base de données. Passer la valeur DB2_SCROLLABLE spécifie un curseur scrollable pour une ressource de requête. Ce mode permet un accès aléatoire aux lignes dans un jeu de résultats, mais actuellement, n'est supporté que par la base de données IBM DB2 Universal.

Les options suivantes sont disponibles depuis ibm_db2 version 1.7.0.

trustedcontext

En passant la valeur DB2_TRUSTED_CONTEXT_ENABLE, le contexte de confiance est activé pour cette connexion. Ce paramètre ne peut pas être activé avec db2_set_option(). Cette option ne fonctionne que si la base est cataloguée, même si la base est locale, ou si l'on spécifie un DSN complet lors de la création de la connexion. Pour cataloguer la base, utiliser la commande suivante :

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

Les options i5/OS suivantes sont disponibles depuis ibm_db2 version 1.5.1.

Astuce

Des attributs de connexion contradictoires, en conjonction avec une connexion persistante peut produire des résultats indéterminés sur i5/OS. La politique du site doit être établie pour toutes les applications qui utilisent une connexion persistante. La valeur par défaut de DB2_AUTOCOMMIT_ON est recommandée avec les connexions persistantes.

i5_lib

Une caractère qui indique la bibliothèque par défaut qui sera utilisée pour résoudre les références de fichiers non qualifiées. Cette option n'est pas valide si la connexion utilise le mode de nommage système.

i5_naming

DB2_I5_NAMING_ON active le mode de nommage système de DB2 UDB CLI iSeries. Les fichiers sont alors qualifiés avec le délimiteur slash (/). Les fichiers non qualifiés sont résolus en utilisant la liste de bibliothèque de la tâche. DB2_I5_NAMING_OFF active le mode de nommage par défaut, qui est le nommage SQL. Les fichiers sont alors qualifiés avec le point (.) . Les fichiers non qualifiés sont résolus avec la bibliothèque par défaut, ou bien l'identifiant de l'utilisateur courant.

i5_commit

L'attribut i5_commit doit être configuré avant l'appel à db2_pconnect(). Si la valeur est changée après la connexion, et que la connexion s'effectue sur des données distantes, alors ce changement n'aura pas d'effets, jusqu'au prochain appel réussi à db2_pconnect().

Note: La directive du php.ini ibm_db2.i5_allow_commit==0 ou DB2_I5_TXN_NO_COMMIT est la valeur par défaut, mais peut être remplacé par l'option i5_commit.

DB2_I5_TXN_NO_COMMIT : le contrôle de validation n'est pas utilisé. DB2_I5_TXN_READ_UNCOMMITTED : les lectures incohérentes, ou non répétables et les fantômes sont possibles. DB2_I5_TXN_READ_COMMITTED : les lectures sont cohérentes. Les lecteurs non répétables et les fantômes sont possibles. DB2_I5_TXN_REPEATABLE_READ : les lectures cohérentes et répétables, mais les fantômes sont possibles. DB2_I5_TXN_SERIALIZABLE : les transactions sont activées. les lectures incohérentes, ou non répétables et les fantômes sont impossibles.

i5_query_optimize

DB2_FIRST_IO : toutes les requêtes sont optimisées dans le but de retourner la première page le plus rapidement possible. Cet objectif fonctionne bien lorsque le résultat est contrôlé par un utilisateur qui a de bonnes chances d'annuler la requête après avoir vu les premières réponses. Les requêtes codées avec une clause OPTIMIZE FOR nnn ROWS respectent aussi cet objectif. DB2_ALL_IO : toutes les requêtes sont optimisées dans le but de traiter la requête complète le plus rapidement possible. C'est une bonne option lorsque le résultat de la requête doit être écrit dans un fichier ou un rapport, ou que l'interface accumule toutes les données avant des exporter. Les requêtes codées avec la clause OPTIMIZE FOR nnn ROWS respectent aussi cet objectif. C'est le comportement par défaut.

i5_dbcs_alloc

DB2_I5_DBCS_ALLOC_ON active le schéma d'allocation DB2 6X pour la croissance des tailles de colonnes de translation DBCS.

DB2_I5_DBCS_ALLOC_OFF désactive le schéma d'allocation DB2 6X pour la croissance des tailles de colonnes de translation DBCS.

Note: La directive du php.ini ibm_db2.i5_dbcs_alloc==0 ou DB2_I5_DBCS_ALLOC_OFF est la valeur par défaut, mais peut être remplacé par l'option i5_dbcs_alloc.

i5_date_fmt

DB2_I5_FMT_ISO : le format de date ISO (International Organization for Standardization) est utilisé : yyyy-mm-dd. C'est le format par défaut. DB2_I5_FMT_USA : le format des États Unis d'Amérique est utilisé : mm/dd/yyyy. DB2_I5_FMT_EUR : le format de date européen dd.mm.yyyy est utilisé. DB2_I5_FMT_JIS : le format standard industriel japonais yyyy-mm-dd est utilisé. DB2_I5_FMT_MDY : le format de date mm/dd/yyyy est utilisé. DB2_I5_FMT_DMY : le format de date dd/mm/yyyy est utilisé. DB2_I5_FMT_YMD : le format de date yy/mm/dd est utilisé. DB2_I5_FMT_JUL : Le format de date julien yy/ddd est utilisé. DB2_I5_FMT_JOB : le format de date par défaut est utilisé.

i5_date_sep

DB2_I5_SEP_SLASH : un slash ( / ) est utilisé comme séparateur de date. C'est le format par défaut. DB2_I5_SEP_DASH : un tiret ( - ) est utilisé comme séparateur de date. DB2_I5_SEP_PERIOD : un point ( . ) est utilisé comme séparateur de date. DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée comme séparateur de date. DB2_I5_SEP_BLANK : un espace est utilisé comme séparateur de date. DB2_I5_SEP_JOB : la configuration par défaut est utilisée

i5_time_fmt

DB2_I5_FMT_ISO : le format d'heure ISO (International Organization for Standardization) est utilisé : hh.mm.ss. C'est le format par défaut. DB2_I5_FMT_USA : le format des États-Unis d'Amérique est utilisé : hh:mmxx est utilisé, où xx vaut AM ou PM. DB2_I5_FMT_EUR : le format d'heure européen hh.mm.ss est utilisé. DB2_I5_FMT_JIS : le format standard industriel japonais est utilisé hh:mm:ss. DB2_I5_FMT_HMS : le format hh:mm:ss est utilisé.

i5_time_sep

DB2_I5_SEP_COLON : un deux-point ( : ) est utilisé comme séparateur d'heure. C'est le défaut. DB2_I5_SEP_PERIOD : un point ( . ) est utilisé comme séparateur d'heure. DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée comme séparateur d'heure. DB2_I5_SEP_BLANK : un espace est utilisé comme séparateur d'heure. DB2_I5_SEP_JOB : le séparateur par défaut est utilisé.

i5_decimal_sep

DB2_I5_SEP_PERIOD : un point ( . ) est utilisé comme séparateur décimal. C'est le séparateur par défaut. DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée comme séparateur décimal. DB2_I5_SEP_JOB : le séparateur par défaut est utilisé.

Les options suivantes i5/OS sont disponibles depuis ibm_db2 version 1.8.0.

i5_libl

Un caractère qui indique la bibliothèque qui sera utilisée pour résoudre les références de fichiers non qualifiées. Spécifier la liste de bibliothèque sous la forme d'éléments séparés par des espaces : 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

Note: i5_libl appelle qsys2/qcmdexc('cmd',cmdlen), qui est disponible depuis i5/OS V5R4.

Valeurs de retour

Retourne la ressource de connexion si la tentative de connexion réussit. db2_pconnect() essaie de réutiliser une ressource de connexion existante qui correspond parfaitement aux paramètres tels que la base de données database, l'utilisateur username et le mot de passe password. Si la tentative de connexion échoue, db2_pconnect() retourne false

Historique

Version	Description
PECL ibm_db2 1.9.0	Les transactions actives sur des connexions persistantes seront annulées à la fin de chaque requête.
PECL ibm_db2 1.8.0	L'option `i5_libl` est disponible pour les utilisateurs d'i5/OS.
PECL ibm_db2 1.7.0	L'option `trustedcontext` est disponible.
PECL ibm_db2 1.5.1	Les options `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` et `i5_decimal_sep` sont disponibles pour les utilisateurs d'i5/OS.

Exemples

Exemple #1 Exemple d'utilisation de db2_pconnect()

Dans l'exemple suivant, le premier appel à db2_pconnect() retourne une nouvelle ressource de connexion persistante. Le second appel à la fonction db2_pconnect() retourne une ressource de connexion persistante qui réutilise la première ressource de connexion.

<?php
$database = 'EXEMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$pconn = db2_pconnect($database, $user, $password);

if ($pconn) {
    echo "Connexion persistante réussie.";
}
else {
    echo "Connexion persistante échouée.";
}

$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
    echo "Deuxième connexion persistante réussie.";
}
else {
    echo "Deuxième connexion persistante échouée.";
}
?>

L'exemple ci-dessus va afficher :

Connexion persistante réussie.
Deuxième connexion persistante réussie.

Exemple #2 Utilisation de contextes de confiance DB2

L'exemple suivant montre comment activer un utilisateur de confiance, basculer dessus, et obtenir un identifiant d'utilisateur.

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
  PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

$tc_conn = db2_pconnect($dsn, "", "", $options);
if($tc_conn) {
    echo "Connexion de confiance réussie.\n";

    if(db2_get_option($tc_conn, "trustedcontext")) {
        $userBefore = db2_get_option($tc_conn, "trusted_user");

        //Travail par l'utilisateur 1.

        //Bascule sur l'utilisateur de confiance.
        $parameters = array("trusted_user" => $tc_user,
          "trusted_password" => $tcuser_pass);
        $res = db2_set_option ($tc_conn, $parameters, 1);

        $userAfter = db2_get_option($tc_conn, "trusted_user");
        //Do more work as trusted user.

        if($userBefore != $userAfter) {
            echo "Utilisateur changé." . "\n";
        }
    }

    db2_close($tc_conn);
}
else {
    echo "Connexion de confiance échouée.\n";
}
?>

L'exemple ci-dessus va afficher :

Connexion de confiance réussie.
Utilisateur changé

Voir aussi

db2_connect() - Retourne une connexion à une base de données