Devolver una conexión persistente a la base de datos

Descripción

db2_pconnect ( string $database , string $username , string $password [, array $options ] ) : resource

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

Más información acerca de conexiones persistentes se puede encontrar en: Conexiones persistentes a bases de datos.

Si se llama a db2_close() en una conexión persistente, siempre se devolverá TRUE, sin embargo la conexión permenecerá abierta en modo de espera para utilizarse en la siguiente solicitud de db2_pconnect().

Para las versiones 1.9.0 y superiores de ibm_db2, hay que considerar que al final de la solicitud siempre se ejecutará una cancelación ("rollback") de la transacción en la conexión persistente para terminar la transacción. Lo anterior evita que el bloqueo de información permanezca en la siguiente solicitud que utilice esa conexión.

Parámetros

database

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

username

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

password

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

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.

Sugerencia

Si se utilizan atributos de conexión conflictivos en conexiones persistentes se pueden provocar resultados indeterminados en i5/OS. Las políticas de sitio deberían establecer el uso de perfiles con conexiones persistentes para todas las aplicacioneses. Se sugiere el uso de DB2_AUTOCOMMIT_ON en conexiones persistentes.

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. db2_pconnect() intenta reutilizar recursos de conexión existentes que coinciden exactamente con los parámetros database, username, y password. Si el intento de conexión falla db2_pconnect() devuelve FALSE.

Historial de cambios

Versión	Descripción
ibm_db2 1.9.0	Las transacciones activas en una conexión persistente serán canceladas al final de cada solicitud.
ibm_db2 1.8.0	La opción `i5_libl` está disponible para los usuarios de i5/OS.
ibm_db2 1.7.0	La opción `trustedcontext` está disponible.
ibm_db2 1.5.1	Las opciones `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` y `i5_decimal_sep` están disponibles para los usuarios de i5/OS.

Ejemplos

Ejemplo #1 Ejemplo de db2_pconnect()

En el siguiente ejemplo, la primera llamada a db2_pconnect() devuelve un nuevo recurso de conexión persistente. La segunda llamada a db2_pconnect() devuelve un recurso de conexión persistente que reutiliza el primer recurso.


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

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

if ($pconn) {
    echo "Persistent connection succeeded.";
}
else {
    echo "Persistent connection failed.";
}

$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
    echo "Second persistent connection succeeded.";
}
else {
    echo "Second persistent connection failed.";
}
?>

El resultado del ejemplo sería:

Persistent connection succeeded.
Second persistent connection succeeded.

Ejemplo #2 Utilizando 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_pconnect($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

db2_connect() - Devolver una conexión a la base de datos