(PECL ibm_db2 >= 1.0.0)
db2_pconnect — Devolver una conexión persistente a la base de datos
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.
databaseEl álias de la base de datos en al catálogo del cliente DB2.
usernameEl usuario con el se conecta a la base de datos.
passwordLa contraseña con la que se conecta a la base de datos.
optionsUn 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.
trustedcontextSi 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.
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_libUna 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 oDB2_I5_TXN_NO_COMMITson opciones predeterminadas pero pueden ser remplazadas con la opcióni5_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 oDB2_I5_DBCS_ALLOC_OFFson opciones predeterminadas pero pueden ser remplazadas con la opcióni5_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_liblUn 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.
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.
| 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.
|
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.
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.The ibm_db2.ini file controls many properties related to to pconnect. For example, stale connection handling is configurable.