oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Conectar a una base de datos de Oracle usando una conexión persistente

Descripción

oci_pconnect(
    string $username,
    string $password,
    string $connection_string = ?,
    string $character_set = ?,
    int $session_mode = ?
): resource

Crea una conexión persistente al servidor de Oracle y se identifica.

Las conexiones persistentes son almacenadas en caché y reutilizadas entre peticiones, resultando en la reducción de carga adicional en cada página; una aplicación típica de PHP tendrá una única conexión persistente abierta a un servidor de Oracle por cada proceso hijo de Apache (o proceso FastCGI/CGI de PHP). Véase la sección Conexiones persistentes a bases de datos para más información.

Parámetros

username

El nombre de usuario de Oracle.

password

La contraseña de username.

connection_string

Contiene la instancia de Oracle a la que conectarse. Puede ser una » cadena de Conexión Sencilla (Easy Connect), o un Nombre de Conexión del fichero tnsnames.ora, o el nombre de una instancia local de Oracle.

Si no se especifica, PHP utiliza variables de entorno como TWO_TASK (en Linux) o LOCAL (en Windows) y ORACLE_SID para determinar la instancia de Oracle a la que conectarse.

Para utilizar el método de nomenclatura de Conexión Sencila, PHP debe estar vinculado con las bibliotecas cliente de Oracle 10g o superiores. La cadena de Conexión Sencilla para Oracle 10g se utiliza de la siguiente forma: [//]nombre_host[:puerto][/nombre_servicio]. Desde Oracle 11g, la sintaxis es: [//]nombre_host[:puerto][/nombre_servicio][:tipo_servicio][/nombre_instancia]. Los nombres de servicio pueden encontrarse ejecuntado la utilidad de Oracle lsnrctl status en el servidor donde se encuentra la base de datos.

El fichero tnsnames.ora puede estar en la ruta de búsqueda de Oracle Net, la cual incluye $ORACLE_HOME/network/admin y /etc. De forma alternativa, establezca TNS_ADMIN para que $TNS_ADMIN/tnsnames.ora sea leído. Asegúrse que el demonio web tiene acceso de lectura al fichero.

character_set

Determina el juego de caracteres usado por las bibliotecas cliente de Oracle. El juego de caracteres no tiene por que coinicidir con el utilizado en la base de datos. Si no coinicide, Oracle intentará hacer lo posible para convertir los datos entre los dos juegos de caracteres. Dependiendo del juego de caracteres que se esté usando, podría no proporcionarse resultados útiles. La conversión también añade algo de carga extra de tiempo.

Si no se especifica, las bibliotacas cliente de Oracle determinarán el juego de caracteres desde la variable de entorno NLS_LANG.

Pasar este parámetro puede reducir el tiempo que toma en conectarse.

session_mode

Este parámetro está disponible desde la versión 5 de PHP (PECL OCI8 1.1) y acepta los siguientes valores: OCI_DEFAULT, OCI_SYSOPER y OCI_SYSDBA. Si se especifica OCI_SYSOPER o OCI_SYSDBA, esta función intentará establecer una conexión privilegiada con las credenciales externas. Las conexiones privilegiadas están desactivadas por omisión. Para activarlas hay que establecer oci8.privileged_connect a On.

En PHP 5.3 (PECL OCI8 1.3.4) se introdujo el valor de modo OCI_CRED_EXT. Esto indica a Oracle que utilice la autenticación Externa o del SO, la cual debe estar configurada en la base de datos. La bandera OCI_CRED_EXT sólo puede usarse con el nombre de usuario "/" y la contraseña en blanco. oci8.privileged_connect podría ser On o Off.

OCI_CRED_EXT podría estar en combinación con los modos OCI_SYSOPER o OCI_SYSDBA.

OCI_CRED_EXT no se admite en Windows por razones de seguridad.

Valores devueltos

Devuelve un identificador de conexión, o false en caso de error.

Ejemplos

Ejemplo #1 Ejemplo básico de oci_pconnect() usando la sintaxis de Easy Connect

<?php

// Conecta al servicio XE (esto es, una base de datos) en la máquina "localhost"
$conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
    echo "<tr>\n";
    foreach ($row as $item) {
        echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

Véase oci_connect() para más ejemplos de uso de parámetros.

Notas

Nota: Desde PHP 5.1.2 y PECL OCI8 1.1, el tiempo de vida y el número máximo de conexiones persistentes a Oracle por proceso de PHP se puede ajustar estableciendo los siguientes valores de configuración: oci8.persistent_timeout, oci8.ping_interval y oci8.max_persistent.

Ver también

oci_connect() - Conecta a una base de datos de Oracle
oci_new_connect() - Conectar al servidor de Oracle usando una conexión única

add a note

User Contributed Notes 2 notes

down

php at jaggard dot org dot uk ¶

16 years ago


[Editor's note: OCI8 1.3 should not experience the problem described in this user comment. The first use of such a connection will return an Oracle error which will trigger a cleanup in PHP.  Subsequent persistent connection calls will then succeed.  For high availability you might consider doing consecutive oci_pconnect calls in your script.]



If you connect using oci_pconnect and the connection has logged you off but is still valid, there seems to be no way to re-use that connection. The next time I try oci_pconnect and then perform an oci_execute operation, I get a "ORA-01012: not logged on" warning. This problem remains, even if I close the connection using oci_close. I ended up with the following (rather annoying) code.



<?php

    function getOracleConnection()

    {

      if (!function_exists('oci_pconnect'))

        return false;

      $toReturn = oci_pconnect('user', 'pass', 'db');

      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))

        if (@oci_execute($testRes))

          if (@oci_fetch_array($testRes))

            return $toReturn;

      oci_close($toReturn);

      if (!function_exists('oci_connect'))

        return false;

      $toReturn = oci_connect('user', 'pass', 'db');

      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))

        if (@oci_execute($testRes))

          if (@oci_fetch_array($testRes))

            return $toReturn;

      oci_close($toReturn);

      if (!function_exists('oci_new_connect'))

        return false;

      $toReturn = oci_new_connect('user', 'pass', 'db');

      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))

        if (@oci_execute($testRes))

          if (@oci_fetch_array($testRes))

            return $toReturn;

      oci_close($toReturn);

      return false;

    }

?>

down

-1

gotankersley at NOSPAM dot com ¶

12 years ago


Installed on CentOS 6.2, and had lots of trouble getting it to recognize tnsnames.ora.  The fix for me was:

1. Make sure apache is getting the TNS_ADMIN env variable by putting it in the /etc/init.d/httpd file:
 TNS_ADMIN=/usr/lib/oracle/11.2/client64/network/admin
 export PATH TNS_ADMIN

This can be debugging in PHP by <?php echo system('env'); ?> and by verifying that TNS_ADMIN is there.

2. Make sure to use the name at the beginning of the tnsnames.ora file - not the SID (although ideally they should match.  However, if the name at the beginning is XXXX.world then pconnect will expect this - not the SID)

add a note