db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Retourne une connexion persistante à une base de données

Description

function 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.

Appeler db2_close() sur une connexion persistante retourne toujours true, mais la connexion sous-jacente du client DB2 demeure ouverte et attend de servir la prochaine requête correspondante 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 à partir d'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 à partir d'ibm_db2 version 1.5.1.

Astuce

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

i5_lib

Une valeur de type 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ée 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 incohérentes ne sont pas possibles. Les lectures non répétables et les fantômes sont possibles. DB2_I5_TXN_REPEATABLE_READ : les lectures incohérentes et les lectures non répétables ne sont pas possibles. Les fantômes sont possibles. DB2_I5_TXN_SERIALIZABLE : les transactions sont sérialisables. Les lectures incohérentes, les lectures non répétables et les fantômes ne sont pas possibles.

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 de sortie. 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ée 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-points ( : ) est utilisé comme séparateur d'heure. C'est la valeur par 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é.

L'option i5/OS suivante est disponible à partir d'ibm_db2 version 1.8.0.

i5_libl

Une valeur de type caractère qui indique la liste de bibliothèques qui sera utilisée pour résoudre les références de fichiers non qualifiées. Spécifier la liste de bibliothèques 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 n'est disponible qu'à partir d'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 le contexte de confiance, changer d'utilisateur et obtenir l'identifiant de l'utilisateur courant.

<?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");
        //Travail supplémentaire en tant qu'utilisateur de confiance.

        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

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 2 notes

down

satoruyoshida at php dot net ¶

14 years ago

If You will create db2 connection on IBMi , QSQSRVR job will be created under QSYSWRK subsystem with specified user.
You can ensure it with using db2_pconnect() function.

For example, db2_pconnect('*LOCAL', 'TESTUSR', 'PASSWORD') will bring us QSQSRVR job with TESTUSR user.

If You omit the user, IHS default user is used in the job.

down

php at redlagoon dot net ¶

8 years ago

The ibm_db2.ini file controls many properties related to to pconnect.   For example, stale connection handling is configurable.

＋add a note