PHP 8.4.0 RC4 available for testing

    db2_connect

    (PECL ibm_db2 >= 1.0.0)

    db2_connect — Devolver una conexión a la base de datos

    Descripción

    db2_connect(
        string $database,
        string $username,
        string $password,
        array $options = ?
    ): resource

    Devuelve una conexión a una base de datos IBM DB2 Universal Database, IBM Cloudscape o Apache Derby.

    Parámetros

    database

    El alias de la base de datos en al catálogo del cliente DB2.

    Para una conexión sin catalogar a una base de datos, se puede representar database con una cadena de conexión completa en el siguiente formato: 

    DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;
    donde los parámetros representan los siguientes valores:
    database

    El nombre de la base de datos.

    hostname

    El Host o la IP del servidor de la base de datos.

    port

    El puerto TCP/IP sobre el cual la base de datos está escuchando solicitudes.

    username

    El usuario con el que se conecta a la base de datos.

    password

    La contraseña con la que se conecta a la base de datos.

    username

    El usuario con el que se conecta a la base de datos.

    Para conexiones sin catalogar se debe pasar null o una cadena vacia.

    password

    La contraseña con la que se conecta a la base de datos.

    Para conexiones sin catalogar se debe pasar null o una cadena vacia.

    options

    Un arreglo asociativo de opciones que afectan el comportamiento de la conexión, entre las claves válidas están:

    autocommit

    Si se pasa el valor DB2_AUTOCOMMIT_ON se confirmarán automáticamente las transacciones de la conexión.

    Si se pasa el valor DB2_AUTOCOMMIT_OFF no se confirmarán automáticamente las transacciones de la conexión.

    DB2_ATTR_CASE

    Si se pasa el valor DB2_CASE_NATURAL los nombres de las columnas serán devueltos con sus mayúsculas y minúsculas originales.

    Si se pasa el valor DB2_CASE_LOWER los nombres de las columnas serán devueltos en minúsculas.

    Si se pasa el valor DB2_CASE_UPPER los nombres de las columnas serán devueltos en mayúsculas.

    CURSOR

    Si se pasa el valor DB2_FORWARD_ONLY se establece un cursor de no-recorrido (sólo hacia adelante). Este cursor es predeterminado y soportado por todos los servidores de base de datos.

    Si se pasa el valor DB2_SCROLLABLE se establece un cursor de recorrido. Con este modo es posible acceder de manera aleatoria a las filas del resultado pero actualmente sólo es soportado por IBM DB2 Universal Database.

    Las siguientes opciones están disponibles en las versiones 1.7.0 y superiores de ibm_db2.

    trustedcontext

    Si se pasa el valor DB2_TRUSTED_CONTEXT_ENABLE se establece una conexión de confianza. Este parámetro no puede ser establecido mediante db2_set_option().

    Esta clave solo funciona si la base de datos está catalogada (aún cuando la base de datos sea local), o si se especifica un DSN completo cuando se crea la conexión.

    Para catalogar la base de datos se usan los siguientes comandos: 

    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

    Las siguientes opciones i5/OS están disponibles en las versiones 1.5.1 y superiores de ibm_db2.

    i5_lib

    Una cadena que indica la lista de bibliotecas que se utilizará por default para resolver referencias no evaluadas a archivos. Este parámetro no es válido si en la conexión se utiliza el modo de nombrado de sistema.

    i5_naming

    DB2_I5_NAMING_ON habilita el modo de nombrado de sistema DB2 UDB CLI iSeries. Los archivos son evaluados utilizando una diagonal (/) como delimitador. Los archivos que no pueden ser evaluados son resueltos utilizando la lista de bibliotecas.

    DB2_I5_NAMING_OFF esta valor predeterminado habilita el modo de nombrado DB2 UDB CLI, que es el sistema de nombrado de SQL. Los archivos son evaluados utilizando un punto (.) como delimitador. Los archivos que no se pueden evaluar son resueltos utilizando tanto la biblioteca predeterminada como el identificador del usuario actual.

    i5_commit

    Se recomienda establecer el parámetro i5_commit antes que db2_pconnect(). Si el valor es modificado después de que la conexión ha sido establecida y la conexión es hacia una fuente remota, el cambio no tendrá efecto hasta la siguiente llamada exitosa a db2_pconnect() para el manejo de conexión.

    Nota:

    El parámetro ibm_db2.i5_allow_commit==0 en php.ini o DB2_I5_TXN_NO_COMMIT son opciones predeterminadas pero pueden ser remplazadas con la opción i5_commit.

    DB2_I5_TXN_NO_COMMIT - No se utiliza ningún control de transacciones.

    DB2_I5_TXN_READ_UNCOMMITTED - Se permiten lecturas sucias, lecturas no repetibles, y lecturas fantasma.

    DB2_I5_TXN_READ_COMMITTED - No se permiten lecturas sucias. Se permiten lecturas no repetibles y lecturas fantasma.

    DB2_I5_TXN_REPEATABLE_READ - No se permiten lecturas sucias ni lecturas no repetibles. Se permiten lecturas fantasma.

    DB2_I5_TXN_SERIALIZABLE - Las transacciones son serializables. No se permiten lecturas sucias, lecturas no repetibles ni lecturas fantasma.

    i5_query_optimize

    DB2_FIRST_IO - Todas las consultas son optimazadas con el objetivo de devolver la primera página de resultados lo más rápido posible. Esta opción se recomienda cuando el resultado es controlado por un usuario que puede cancelar la consulta después de visualizar la primera página de resultados. Esta funcionalidad también se puede lograr utilizando OPTIMIZE FOR nnn ROWS en una consulta.

    DB2_ALL_IO - Todas las consultas son optimizadas con el objetivo de ejecutar la consulta completa en el menor tiempo posible. Esta opción predeterminada se recomienda cuando el resultado de una consulta es escrito en un archivo o reporte. Esta funcionalidad tambien se puede lograr utilizando OPTIMIZE FOR nnn ROWS en una consulta.

    i5_dbcs_alloc

    DB2_I5_DBCS_ALLOC_ON habilita el esquema de alojamiento DB2 6X para incremento de tamaño en columnas de traducción DBCS.

    DB2_I5_DBCS_ALLOC_OFF deshabilita el esquema de alojamiento DB2 6X para incremento de tamaño en columnas de traducción DBCS.

    Nota: El parámetro ibm_db2.i5_dbcs_alloc==0 en php.ini o DB2_I5_DBCS_ALLOC_OFF son opciones predeterminadas pero pueden ser remplazadas con la opción i5_dbcs_alloc.

    i5_date_fmt

    DB2_I5_FMT_ISO - Se utiliza el formato de fechas estandar (ISO) yyyy-mm-dd. Esta opción es predeterminada.

    DB2_I5_FMT_USA - Se utiliza el formato de fechas de Estados Unidos mm/dd/yyyy.

    DB2_I5_FMT_EUR - Se utiliza el formato de fechas Europeo dd.mm.yyyy.

    DB2_I5_FMT_JIS - Se utiliza el formato de fechas Japonés yyyy-mm-dd.

    DB2_I5_FMT_MDY - Se utiliza el formato de fechas mm/dd/yyyy.

    DB2_I5_FMT_DMY - Se utiliza el formato de fechas dd/mm/yyyy.

    DB2_I5_FMT_YMD - Se utiliza el formato de fechas yy/mm/dd.

    DB2_I5_FMT_JUL - Se utiliza el formato de fechas Juliano yy/ddd.

    DB2_I5_FMT_JOB - El formato de trabajo es utilizado.

    i5_date_sep

    DB2_I5_SEP_SLASH - Se utiliza una diagonal ( / ) como separador de fechas. Esta opción es predeterminada.

    DB2_I5_SEP_DASH - Se utiliza un guión medio ( - ) como separador de fechas.

    DB2_I5_SEP_PERIOD - Se utiliza un punto ( . ) como separador de fechas.

    DB2_I5_SEP_COMMA - Se utiliza una coma ( , ) como separador de fechas.

    DB2_I5_SEP_BLANK - Se utiliza un espacio como separador de fechas.

    DB2_I5_SEP_JOB - Se utiliza el separador de fechas de trabajo.

    i5_time_fmt

    DB2_I5_FMT_ISO - Se utiliza el formato de tiempo estandar (ISO) hh.mm.ss. Esta opción es predeterminada.

    DB2_I5_FMT_USA - Se utiliza el formato de tiempo de Estados Unidos hh:mmxx, donde xx es AM o PM.

    DB2_I5_FMT_EUR - Se utiliza el formato de tiempo Europeo hh.mm.ss.

    DB2_I5_FMT_JIS - Se utiliza el formato de tiempo Japonés hh:mm:ss.

    DB2_I5_FMT_HMS - Se utiliza el formato de tiempo hh:mm:ss.

    i5_time_sep

    DB2_I5_SEP_COLON - Se utiliza el signo de dos puntos ( : ) como separador de tiempo. Esta opción es predeterminada.

    DB2_I5_SEP_PERIOD - Se utiliza un punto ( . ) como separador de tiempo.

    DB2_I5_SEP_COMMA - Se utiliza una coma ( , ) como separador de tiempo.

    DB2_I5_SEP_BLANK - Se utiliza un espacio como separador de tiempo.

    DB2_I5_SEP_JOB - Se utiliza el separador de tiempo de trabajo.

    i5_decimal_sep

    DB2_I5_SEP_PERIOD - Se utiliza un punto ( . ) como separador decimal. Esta opción es predeterminada.

    DB2_I5_SEP_COMMA - Se utiliza una coma ( , ) como separador decimal.

    DB2_I5_SEP_JOB - Se utiliza el separador decimal de trabajo.

    La siguiente opción i5/OS está disponible en las versiones 1.8.0 y superiores de ibm_db2.

    i5_libl

    Un cadena que indica la lista de bibliotecas que se utilizará para resolver referencias no evaluadas a archivos. Se especifican los elementos de la lista separados por espacios 'i5_libl'=>"LIBRERIA1 LIBRERIA2 LIBRERIA3".

    Nota:

    i5_libl llama a qsys2/qcmdexc('cmd',cmdlen), que sólo está disponible en i5/OS V5R4 y versiones superiores.

    Valores devueltos

    Devuelve un recurso de conexión si el intento de conexión es exitoso. Si el intento de conexión falla db2_connect() devuelve false.

    Ejemplos

    Ejemplo #1 Creando una conexión catalogada

    Las conexiones catalogadas requieren que previamente se haya guardado la configuración mediante la consola DB2 Command Line Processor (CLP) o el asistente DB2 Configuration Assistant.

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

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

    if (    $conn) {
    echo     "Connection succeeded.";
    db2_close($conn);
    }
    else {
    echo     "Connection failed.";
    }
    ?>

    El resultado del ejemplo sería:

    Connection succeeded.

    Ejemplo #2 Creando una conexión no catalogada

    Con una conexión no catalogada es posible conectarse de manera dinámica a la base de datos.

    <?php
    $database     = 'SAMPLE';
    $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     "Connection succeeded.";
    db2_close($conn);
    }
    else {
    echo     "Connection failed.";
    }
    ?>

    El resultado del ejemplo sería:

    Connection succeeded.

    Ejemplo #3 Creando una conexión con confirmaciones automáticas de transacciones deshabilitadas

    Si se pasa un arreglo de opciones a db2_connect() se puede modificar el conportamiento predeterminado de la conexión.

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

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

    if (    $conn) {
    echo     "Connection succeeded.\n";
    if (    db2_autocommit($conn)) {
    echo     "Autocommit is on.\n";
    }
    else {
    echo     "Autocommit is off.\n";
    }
    db2_close($conn);
    }
    else {
    echo     "Connection failed.";
    }
    ?>

    El resultado del ejemplo sería:

    Connection succeeded.
Autocommit is off.

    Ejemplo #4 Optimizando en i5/OS

    Para lograr un mejor rendimiento en las aplicaciones de i5/OS ibm_db2 1.5.1 se puede usar el Host, usuario y contraseña predeterminados en 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);
    ?>

    El resultado del ejemplo sería:

    ANIMALS
NAMES
PICTURES

    Ejemplo #5 Usando contexto de confianza

    El siguiente ejemplo muestra como habilitar el contexto de confianza, cambia usuarios y obtiene el identificador del usuario actual.

    <?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     "Explicit trusted connection succeeded.\n";

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

    //Do some work as user 1.

    //Switching to trusted user.
    $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     "User has been switched." . "\n";
    }
    }

    db2_close($tc_conn);
    }
    else {
    echo     "Explicit trusted connection failed.\n";
    }
    ?>

    El resultado del ejemplo sería:

    Explicit trusted connection succeeded.
User has been switched.

    Ver también

    Improve This Page

    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
    9 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