PHP 8.5.10 Released!

    db2_connect

    (PECL ibm_db2 >= 1.0.0)

    db2_connect — Retourne une connexion à une base de données

    Description

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

    Crée une nouvelle connexion à une base de données IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

    Liste de paramètres

    database

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

    Pour une connexion non cataloguée de la base de données, database représente une chaîne complète de connexion qui est dans le 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

    L'adresse Internet ou IP du serveur de base de données.

    port

    Le port TCP/IP sur lequel la base de données écoute les connexions.

    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.

    Pour les connexions non cataloguées, il faut passer une valeur null ou une chaîne vide.

    password

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

    Pour les connexions non cataloguées, il faut passer une valeur null ou une chaîne vide.

    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 défilant 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.

    La nouvelle option suivante est disponible pour les versions ibm_db2 1.7.0 et suivantes.

    trustedcontext

    Le fait de passer la valeur DB2_TRUSTED_CONTEXT_ENABLE active le contexte de confiance pour ce gestionnaire de connexion. Ce paramètre ne peut être défini avec la fonction db2_set_option().

    Cette clé fonctionne uniquement si la base de données est cataloguée (même si la base de données est locale), ou si l'on spécifie le DSN complet lors de la création de la connexion.

    Pour cataloguer la base de données, utiliser les commandes suivantes : 

    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 nouvelles options i5/OS suivantes sont disponibles dans les versions ibm_db2 1.5.1 et suivantes.

    i5_lib

    Un caractère qui indique la bibliothèque par défaut qui sera utilisée pour résoudre les références aux fichiers non qualifiées. Ceci n'est pas valide si la connexion utilise un mode de système de nom.

    i5_naming

    La valeur DB2_I5_NAMING_ON active le mode de nommage système iSeries de DB2 UDB CLI. Les fichiers sont qualifiés en utilisant le délimiteur slash (/). Les fichiers non qualifiés sont résolus en utilisant la liste de bibliothèque pour le travail.

    La valeur DB2_I5_NAMING_OFF désactive le mode de nommage par défaut de DB2 UDB CLI, qui est le nommage SQL. Les fichiers sont qualifiés en utilisant le délimiteur point (.). Les fichiers non qualifiés sont résolus en utilisant soit la bibliothèque par défaut, soit l'ID de l'utilisateur courant.

    i5_commit

    L'attribut i5_commit devrait être fixé avant l'appel à db2_connect(). Si la valeur est changée après que la connexion a été établie et que la connexion est à une source de données distante, le changement ne prendra effet qu'au prochain appel réussi de db2_connect() pour le gestionnaire de connexion.

    Note:

    La configuration php.ini ibm_db2.i5_allow_commit==0 ou DB2_I5_TXN_NO_COMMIT est par défaut, mais peut être remplacée avec 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 sales, non répétables et fantômes sont possibles.

    DB2_I5_TXN_READ_COMMITTED : Les lectures sales ne sont pas possibles. Les lectures non répétables et fantômes sont possibles.

    DB2_I5_TXN_REPEATABLE_READ : Les lectures sales et non répétables ne sont pas possibles. Les lectures fantômes sont possibles.

    DB2_I5_TXN_SERIALIZABLE : les transactions sont sérialisées. Les lectures sales, non répétables et fantômes ne sont pas possibles.

    i5_query_optimize

    DB2_FIRST_IO Toutes les requêtes sont optimisées avec le but de retourner la première page aussi vite que possible. Ce but fonctionne bien lorsque les données de sortie sont contrôlées par un utilisateur qui est le plus susceptible d'annuler une requête après avoir vu la première page des données. Les requêtes sont codées avec une clause "OPTIMIZE FOR nnn ROWS" afin de honorer le but spécifié par la clause.

    DB2_ALL_IO Toutes les requêtes sont optimisées avec le but d'exécuter la requête entière jusqu'à la fin dans le plus petit intervalle de temps. C'est une bonne option lorsque les données de sortie d'une requête sont en train d'être écrites vers un fichier ou un rapport ou encore lorsque l'interface met en file d'attente les données. Les requêtes sont codées avec une clause "OPTIMIZE FOR nnn ROWS" afin de honorer le but spécifié par la clause. C'est la valeur par défaut.

    i5_dbcs_alloc

    La valeur DB2_I5_DBCS_ALLOC_ON active le canevas d'allocation DB2 6X pour l'accroissement des tailles des colonnes en traduction DBCS.

    La valeur DB2_I5_DBCS_ALLOC_OFF désactive le canevas d'allocation DB2 6X pour l'accroissement des tailles des colonnes en traduction DBCS.

    Note : la configuration php.ini ibm_db2.i5_dbcs_alloc==0 ou DB2_I5_DBCS_ALLOC_OFF est par défaut mais peut être remplacée avec l'option i5_dbcs_alloc.

    i5_date_fmt

    DB2_I5_FMT_ISO : le format de date de l'organisation internationale de normalisation (ISO) "yyyy-mm-dd" est utilisé. Ceci est la valeur par défaut.

    DB2_I5_FMT_USA : le format de date des États-Unis "mm/dd/yyyy" est utilisé.

    DB2_I5_FMT_EUR : le format de date européen "dd.mm.yyyy" est utilisé.

    DB2_I5_FMT_JIS : le format de date de la norme industrielle japonaise (JIS) "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 : la valeur par défaut est utilisée.

    i5_date_sep

    DB2_I5_SEP_SLASH : un slash ( / ) est utilisé en tant que séparateur de date. Ceci est la valeur par défaut.

    DB2_I5_SEP_DASH : un tiret ( - ) est utilisé en tant que séparateur de date.

    DB2_I5_SEP_PERIOD : un point ( . ) est utilisé en tant que séparateur de date.

    DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée en tant que séparateur de date.

    DB2_I5_SEP_BLANK : un espace blanc est utilisé en tant que séparateur de date.

    DB2_I5_SEP_JOB : la valeur par défaut est utilisée.

    i5_time_fmt

    DB2_I5_FMT_ISO : le format de l'heure de l'organisation internationale de normalisation (ISO) "hh.mm.ss" est utilisé. Ceci est la valeur par défaut.

    DB2_I5_FMT_USA : le format de l'heure des États-Unis "hh:mmxx" est utilisé, où "xx" vaut "AM" ou "PM".

    DB2_I5_FMT_EUR : le format de l'heure européen "hh.mm.ss" est utilisé.

    DB2_I5_FMT_JIS : le format de l'heure de la norme industrielle japonaise "hh:mm:ss" est utilisé.

    DB2_I5_FMT_HMS : le format "hh:mm:ss" est utilisé.

    i5_time_sep

    DB2_I5_SEP_COLON : un deux-points ( : ) est utilisé en tant que séparateur d'heure. Ceci est la valeur par défaut.

    DB2_I5_SEP_PERIOD : un point ( . ) est utilisé en tant que séparateur d'heure.

    DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée en tant que séparateur d'heure.

    DB2_I5_SEP_BLANK : un espace blanc est utilisé en tant que séparateur d'heure.

    DB2_I5_SEP_JOB : la valeur par défaut est utilisée.

    i5_decimal_sep

    DB2_I5_SEP_PERIOD : un point ( . ) est utilisé en tant que séparateur de décimale. Ceci est la valeur par défaut.

    DB2_I5_SEP_COMMA : une virgule ( , ) est utilisée en tant que séparateur de décimale.

    DB2_I5_SEP_JOB : la valeur par défaut est utilisée.

    La nouvelle option i5/OS suivante est disponible à partir de la version ibm_db2 1.8.0.

    i5_libl

    Une chaîne indiquant la liste de bibliothèques à utiliser pour résoudre les références de fichiers non qualifiés. Spécifier la liste en séparant les valeurs par un espace, comme ceci : 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    Note:

    i5_libl appelle qsys2/qcmdexc('cmd',cmdlen), qui n'est disponible qu'à partir de i5/OS V5R4.

    Valeurs de retour

    Retourne la ressource de connexion si la tentative de connexion réussit. Si la tentative de connexion échoue, db2_connect() retourne false.

    Exemples

    Exemple #1 Création d'une connexion cataloguée

    Les connexions cataloguées nécessitent que l'on ait préalablement catalogué la base de données spécifiée à l'aide du processeur de ligne de commandes DB2 ("Command Line Processor" : CLP) ou avec l'assistant de configuration de DB2. 

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

$conn = db2_connect($database, $user, $password);

if ($conn) {
    echo "Connexion réussie.";
    db2_close($conn);
}
else {
    echo "Connexion échouée.";
}
?>

    L'exemple ci-dessus va afficher :

    Connexion réussie.

    Exemple #2 Création d'une connexion non cataloguée

    Une connexion non cataloguée permet de se connecter dynamiquement à une base de données. 

    <?php
$database = 'EXEMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$hostname = 'localhost';
$port = 50000;

$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
  "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
$conn = db2_connect($conn_string, '', '');

if ($conn) {
    echo "Connexion réussie.";
    db2_close($conn);
}
else {
    echo "Connexion échouée.";
}
?>

    L'exemple ci-dessus va afficher :

    Connexion réussie.

    Exemple #3 Création d'une connexion avec autocommit désactivé par défaut

    Le fait de passer un tableau d'option à db2_connect() permet de modifier le comportement par défaut de la connexion. 

    <?php
$database = 'EXEMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

$conn = db2_connect($database, $user, $password, $options);

if ($conn) {
    echo "Connexion réussie.\n";
    if (db2_autocommit($conn)) {
         echo "Autocommit est activé.\n";
    }
    else {
         echo "Autocommit est désactivé.\n";
    }
    db2_close($conn);
}
else {
    echo "Connexion échouée.";
}
?>

    L'exemple ci-dessus va afficher :

    Connexion réussie.
Autocommit est désactivé.

    Exemple #4 Meilleure performance i5/OS

    Pour obtenir les meilleures performances de l'application PHP i5/OS ibm_db2 1.5.1, utiliser l'hôte par défaut, l'identifiant utilisateur et le mot de passe pour l'appel à db2_connect(). 

    <?php
  $library = "ADC";
  $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
  $result = db2_exec($i5,
       "select * from systables where table_schema = '$library'");
  while ($row = db2_fetch_both($result)) {
     echo $row['TABLE_NAME']."</br>";
  }
  db2_close($i5);
?>

    L'exemple ci-dessus va afficher :

    ANIMALS
NAMES
PICTURES

    Exemple #5 Utilisation du contexte de confiance

    L'exemple suivant montre comment activer le contexte de confiance, changer d'utilisateur et récupérer l'ID 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_connect($dsn, "", "", $options);
if($tc_conn) {
    echo "Connexion explicite de confiance réussie.\n";

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

        //Code en tant qu'utilisateur 1.

        //Passage à 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");
        //Code en tant qu'utilisateur de confiance.

        if($userBefore != $userAfter) {
            echo "L'utilisateur a changé." . "\n";
        }
    }

    db2_close($tc_conn);
}
else {
    echo "La connexion explicite de confiance a échoué.\n";
}
?>

    L'exemple ci-dessus va afficher :

    Connexion explicite de confiance réussie.
L'utilisateur a changé.

    Voir aussi

    • db2_close() - Ferme une connexion de base de données
    • db2_pconnect() - Retourne une connexion persistante à 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 1 note

    up
    2
    d dot lanza38 at gmail dot com
    10 years ago
    As of 09/29/2015 when using the ibm_db2 driver and specifying an invalid library list with the 'i5_libl' option, the connection will be successfully created but with a default library list.  What happens is the connection is made and THEN the library list is attempted to be changed.  The connection will be a success but the library list change will fail without "db2_conn_error()" or "db2_conn_errormsg()" reporting anything and a default library list will be used.  However, "db2_stmt_error()" and "db2_stmt_errormsg()" will register with a value.  Also if error reporting is enable, the warning will be output to the screen.  This is not a bug, rather intended behavior according to Zend (I opened a ticked) and depending on which library list is used/swapped could lead to major problems (development VS production).  I stumbled upon this behavior when an anomaly (which I still can't explain) was imploding my library list with the character 'Z'.  I realized I was in my development environment but accessing production data as a result.  Going forward I will make sure to add this additional check for good measure.

See below to recreate behavior:

<?php
ini_set("display_errors", 1);

$systemName = 'systemName';
$userID = 'userName';
$password = 'password';

$options['i5_libl'] = implode('Z', array(
        'INVALID',        
    'LIB',       
    'LIST',   
    'IMPLODED',  
    'WITH',   
    'THE',      
    'LETTER',       
    'Z'
    ));

$options['i5_naming'] = DB2_I5_NAMING_ON;

$conn = db2_connect($systemName, $userID, $password, $options);
//This line causes "ini_set("display_errors", 1)" to dislay this warning on the screen:
//Warning: db2_connect(): Statement Execute Failed in /PATH/TO/FILE/test.php on line 58

if (db2_stmt_error()) { //Evaluates to true
    echo "error ID: " . (db2_stmt_error()); //Displays error code: 38501
    echo "<br>error message: " . (db2_stmt_errormsg()); //Displays: Trigger program or external routine detected an error. SQLCODE=-443
}

echo "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; //Only "| ||| |" is displayed
print_r($conn); //A resource ID is displayed
echo "<br />";

if(isset($conn) && $conn === true){
    echo "Boolean true<br />";
    //never executes, but not expected since either false or a resource ID should be returned.
    //Plus it is clear $conn contains a resource ID from above.
}
if(isset($conn) && $conn == true){
    echo "Non-Boolean true 2<br />"; 
    //This always executes regardless of an accurate library list or not
    //I suppose "if($conn)" would evaluate to non-boolean true so this makes sense.
}
if(isset($conn) && $conn == "true"){
    echo "String true";
    //Never executes, but not expected.
}
if(isset($conn) && $conn === false){
    echo "Boolean false<br />";
    //never executes because the connection itself was a success.
    //If invalid credentials were provided this executes.
}
if(isset($conn) && $conn == false){
    echo "Non-Boolean false 2<br />";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a boolean false would be returned or not.
    //If invalid credentials were provided this executes as well.
}
if(isset($conn) && $conn == "false"){
    echo "String false";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a String "false" would be returned
}
?>
    ＋add a note
    To Top