• Métodos de la Clase DBI 

  ---

• connect (conectar)
$dbh = DBI->connect("DBI:mysql:$database", undef, undef);
$dbh = DBI->connect("DBI:mysql:$database", $username, $password);
$dbh=DBI->connect("DBI:mysql:$database:$hostname",$username, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
$username, $password);

Se usa el método connect para crear una conexión con la base de datos a la fuente de datos. La variable $data_source debe empezar con 'DBI:nombre_del_driver:'.  Si el username (nombre de usuario) y/o el password están indefinidos, entonces DBI usrá los valores de la variables de entorno DBI_USER, DBI_PASS respectivamente. Si no se especifica un nombre de host (hostname), se utilizará por defecto "localhost".
Aqui tenemos un pequeño ejemplo de un script para realizar una conexión con una base de datos MySql:

#!/usr/bin/perl -w
use DBI;
use strict;
my $database = "ContactDB";
my $data_source = "DBI:mysql:$database;"
my $username = "fty";
my $password = "password";
my $dbh = DBI->connect( $data_source, $username, $password)
or die "No puedo conectarme a $data_source: $dbh->errstr\n";
$dbh->disconnect;
exit(0);
__END__


---

• available_drivers (drivers disponibles)
@drivers = DBI->available_drivers;
@drivers = DBI->available_drivers($quiet);

Este método devuelve un array con los drivers disponibles, buscándolos en los directorios DBD::* . Se muestra un mensaje de aviso si algún driver está oculto por drivers de igual nombre en directorio previo. Para inhabilitar este mensaje de aviso se pone la variable $quiet a 1 (a true) como un parámetro del método. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $quiet = 1;
my @drivers = DBI->available_drivers($quiet);
print "Drivers disponibles:\n";
for(@drivers) {
    print "$_\n";
}
exit;
__END__


---

• data_sources (fuentes de datos)
@databases = DBI->data_sources($driver);

Este método devuelve un array de bases de datos disponibles para el driver dado (varieble $driver). Si dicha variable $driver se omite, se utiliza la variable de entorno DBI_DRIVER. Por ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $quiet = 1;
my ($driver,$database);
my @drivers = DBI->available_drivers($quiet);
print "Bases de DAtos Disponibles:\n";
foreach $driver(@drivers) {
    print "_____________________\n";
    print "$driver:\n";
    print "_____________________\n";
    @databases = DBI->data_sources($driver);
    foreach $database(@databases) {
        print "$database\n";
    }
print "\n";
}
exit;
__END__


---

• trace (seguimiento)
DBI->trace($trace_level);
DBI->trace($trace_level, $trace_file);

La información en DBI puede seguirse (trace) para todos los manejadores que usen éste método. Para habilitarlo para un majeador específico hay que usar el método $dbh->trace similar para el manejador. La información que devuelve trace estar´ disponible para todos los manejadores que usen este método. Poniendo la variable $trace_level a 2 se pude ver información más detallada, si se pone a 0 desaparece la información de seguimiento (trace). Si el fichero $trace_file está especificado, entonces toda la información se añade a dicho fichero. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $trace_level = 2;
$DBI->trace($trace_level);
my $dbh = DBI->connect("DBI:mysql:contact",undef,undef)
or die "No se puede conectar a la BD: $dbh->errstr\n";
my $sth = $dbh->prepare("SELECT * FROM contact");
$sth->execute or die "No se puede ejecutar consulta: $dbh->errstr\n";
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• Funciones de utilidades de DBI
• neat
$str = DBI::neat($value, $maxlen);

Devuelve una representación limpia (neat) de la variable ($value) que se le pasa, es decir, formateada para uso humano. Esta función se usa internamente por el DBI para el seguimiento (trace). No debe ser usada para formatear valores para usarlos en la base de datos.


---

• neat_list
$str = DBI::neat_list(\@listref, $maxlen, $field_sep);

Llama a DBI::neat para cada elemento de @listref y devuelve una cadena con los resultados unidos por $field_sep. No debe ser usada para formatear valores para usarlos en la base de datos.


---

• dump_results
$rows = DBI::dump_results($sth, maxlen, $lsep, $fsep, $fh);

Esta función extrae todas las tuplas de una manjeador de sentencia ($sth), llama a la función DBI::neat_list para cada tupla y escribe el resultado en el descriptor de fichero ($fh), que por defecto es STDOUT. El separador de línea ($lsep) es por defecto '\n', el separador de campos ($fsep) es por defecto ',' y la máxima longitud ($maxlen) es 35. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contact",undef,undef)
or die "No se puede conectar a la BD: $dbh->errstr\n";
my $sth = $dbh->prepare("SELECT * FROM contacts");
DBI::dump_results($sth) or die "$DBI::errstr\n";
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• Atributos dinámicos de DBI

Todos los atributos dinámicos descritos a continuación son volátiles (volitile), es decir, tienen un vida corta debido a que siempre están asociados al último manejador usado. El motivo es que tiene que ser usados inmediatamente despueés de llamar el método que los activa. También se han encontrado problemas con multi-hebras en Perl 5.005. Es mejor usar los atributos equivalentes que se menciona a continuación
 
• $DBI::err
Equivalente a $dbh->err
• $DBI::errstr
Equivalente a $dbh->errstr
• $DBI::state
Equivalente a $dbh->state
• $DBI::rows
Equivalente a $dbh->rows


---

• Métodos Comunes a Todos los Manejadores

• err (error de la BD)
$err = $dbh->err;

Este método devuelve el código de error nativo de la base de datos, provocado a la última función del driver llamada.


---

• errstr (cadena de error de la BD)
$errstr = $dbh->errstr;

Este método devuelve el mensaje de error nativo de la base de datos, debido a la última función del driver llamada.


---

• state(estado)
$state = $dbh->state;

?No soportado por mySQL?


---

• trace (seguimiento)
$dbh->trace($trace_level);

Muy similiar a DBI::trace con una expeción. El seguimiento (trace) sólo está asociado con el manejador específico con el que est´ siendo usado.


---

• func
$dbh->func(@func_arguments, $func_name);

Este método se usa para llamar a métodos privados que están implementados por el driver (DBD::*)


---


 

Ejemplo que usa los métodos anteriores:

#!/usr/bin/perl -w
use DBI;
use strict;
my $trace_level = 2;
my $dbh = DBI->connect("DBI:mysql:contact",undef,undef)
$dbh->trace($trace_level);
or die "No se puede conectar a la BD: $dbh->errstr\n";
my $sth = $dbh->prepare("SELECT * FROM contact");
$sth->execute or die "Imposible ejecutar consulta:$dbh->err, $dbh->errstr\n";
$sth->finish;
@tables = $dbh->func('_ListTables')
or die "No se puede listar las tablas: $dbh->errstr\n";
foreach $table(@tables) {
    print "$table\n";
}
$dbh->disconnect;
exit;
__END__


---

• Atributos Comunes a Todos los Manejadores

$dbh->{AttributeName} = 1;
$value = $dbh->{AttributeName};
 

• Warn (booleano, heredado)
 Activa mensajes de aviso útiles. Activado por defecto.


---

• CompatMode (booleano, heredado)
Usado para emulación de capas para activar el modo compatible en el drivers. No aplicables al driver de mySQL.


---

• InactiveDestroy (booleano)
Este atributo es usado para inhabilitar los efectos de destruir un manejador. Está especificamente diseñado para aplicaiones en Unix que tienen procesos hijos creados con fork. EL padre o el hijo deben poner este atributo en todos sus manejadores, pero no los dos.


---

• PrintError (booleano, heredado)
Este atributo se usa para forzar a los errores a generar mensajes de aviso además de los códigos de error. Por defecto DBI->connect tiene activado PrintError.


---

• RaiseError (booleano, heredado)
Este atributo es usado para obligar a los errores a crear excepciones justo antes de devolver un código de error. Por defecto, no está activado.


---

• ChopBlanks (booleano, heredado)
Este atrobuto se usa para controlar los espacios en los campos de anchura fijos. (the trimming of trailing spaces from fixed width fields). Por defecto es falso.


---

• LongReadLen (entero, heredado)
 Este atributo se usa para controlar la máxima longitud del los campos blob (binarios). Una valor de 9 significa que automaticamente no se extraen datos largos (la extracción debe devolver undef para el blob cuando está a 0. Por defecto es, normalmente, 0, pero puede haber diferencias entre drivers. Este atributo debe ser activado antes que la sentencia esté en la etapa de preparación.


---

• LongTruncOk (booleano, heredado)
Este atributo se usa para controlar como se extrae (fecht) manjeadores con campos blob (binarios) que han sido truncados (debido a ser el valor del campo más largo que el atributo LongReadLen). Por defecto es falso y provocar´ que la extracción (fetch) falle. Muchos drivers permiten continuar extrayendo más tuplas cuando este aributo esta puesto a false.


---

• Métodos de los Manejadores de BD
• prepare (preparación)
$sth = $dbh->prepare($statement);
$sth = $dbh->prepare($statement, \%attr);

Este método prepara una sentencia simple de SQL para su ejecución y devuelve una referencia al manejador de la sentencia ($sth) para usarlo con el objetivo de coger los atributos de la sentencia cuando se ejecute la sentencias. Algunos drivers sólo guardan la sentencia en el manejador y sólo puede dar información útil depués de que el método execute haya sido llamado.


---

• do
$rc = $dbh->do($statement);
$rc = $dbh->do($statement, \%attr);
$rc = $dbh->do($statement, \%attr, @bind_values);

Este método prepara y ejecuta una sentencia. Devuelve el número de tupas afectadas o -1 si no es conocido, o undef si hay un error.Este método es usualmente usado para sentencias no-select (que no son consultas), las cuales no necesitan ser preparadas o ejecutadas por separado.


---

• commit
$dbh->commit; Este método hace persistente una operación realizada en la BD.(No soportado por mySQL)


---

• rollback
$dbh->rollback; Deshace un commit.(No soportado por mySQL)


---

• disconnect
$dbh->disconnect;

Este método cierra la conexión entre la BD y el manejador de la base de datos. Normalmente se suele usar justo antes de terminar la aplicación. Si se llama a este método mientras hay manejadores de sentencias activos se obtendrá un mensaje de aviso. Hay que usar el método finish para cada manejador de sentencia definida.


---

• ping
$result = $dbh->ping;

Este método mira si el servidor de BD sigue funcionando y la conexión sigue funcionando. No se suele usar. En Apache::DBI se pude ver un ejemplo de uso.


---

• quote
$sql = $dbh->quote($string);

Este método escapa caracteres especiales (comillas, etc.) en las cadenas y a¤ade las comillas externas. No es aplicable a todos los tipos de entrada (ej, datos binarios).


---


 

Ejemplo que utiliza los métodos anteriores:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se puede conecatar a la BD: $dbh->errstr\n";
my $sth = $dbh->prepare("SELECT uid FROM contact WHERE last_name = 'Flaherty'");
$sth->execute or die "No se puede ejecutar consulta: $dbh->errstr\n";
my $row = $sth->fetchrow_arrayref;
my $uid = $row->[0];
$sth->finish;
my $newname = $dbh->quote("The Flahertys'");
my $statement =qq(UPDATE contact SET last_name = '$newname'
                  WHERE uid = $uid);
my $rc = $dbh->do($statement) or die "No se puede preparar/ejecutar la sentencia: $dbh->errstr\n";
print "$rc tuplas han sido actualizadas\n";
$dbh->disconnect;
exit;
__END__


---

• Atributos de los Manejadores de Bases de DAtos
• AutoCommit
$dbh->{AutoCommit} = 1;
$value = $dbh->{AutoCommit}; (Not supported by mySQL)


---

• Métodos de los Manejadores de Sentencias
• bind_param
$sth->bind_param($param_num, $bind_value);
$sth->bind_param($param_num, $bind_value, \%attr);
$sth->bind_param($param_num, $bind_value, $bind_type);

Este método se usa para asignar valores a un placeholder (indicated with a question mark) en un sentencia preparada. %attr puede ser usado para especificar el tipo de dato del placeholder. por ejemplo:

$sth->bind_param(1, $value, { TYPE => SQL_INTEGER });

Se usa un atajo para unir un tipo directamente en el lugar de una referencia de una memoria sociativa(hash). por ejemplo:

$sth->bind_param(1, $value, SQL_INTEGER);

Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la base de datos: $dbh->errstr\n";
my @letters = [A..Z];
my $i;
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name
                         FROM contact
                         WHERE last_name LIKE ?");
for($i = 1; $i <= 26, $i++) {
    $sth->bind_param($i, "@letters[$i]%");
    $sth->execute;
    print qq(
    Last Name beginning with @letters[$i]:\n
    FIRST                    LAST\n
    -----                    ----\n
    while(my $row = $sth->fetchrow_arrayref) {
        my($first,$last) = @$row;
        print qq(
        $first                   $last\n
    }
    print "\n";
    $sth->finish;
}
$dbh->disconnect;
exit;
__END__


---

• bind_param_inout
$sth->bind_param_inout($param_num, \$bind_value, $max_len);
$sth->bind_param_inout($param_num, \$bind_value, $max_len, \%attr);
$sth->bind_param_inout($param_num, \$bind_value, $max_len, $bind_type); (no soportado por mySQL)


---

• execute
$rc = $sth->execute;
$rc = $sth->execute(@bind_values);

Este método ejecuta una sentencia preparada y devuelve true si hay éxito y undef si ocurre un error. Para las sentencias que no son SELECT (UPDATE, INSERT, etc.) el valor de retorno es el número de tuplas afectadas. Cero tuplas son devueltas como '0E0' que Perl trata como '0' pero que es tratado como true. Para sentencias SELECT la ejecución comienza la maquinaria de consulta. Se necesitan usar uno de los métodos de extracción (fetch), explicados a continuación, para obtener datos. Si se omite algún argumento entonces el método execute llama a bind_param para cada valor, y pone el tipo a SQL_VARCHAR. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se puede conectar con la BD: $dbh->errstr\n";
my @names = ['Flaherty', 'Jones', 'Smith'];
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("UPDATE contact
                         SET phone = '555-1212'
                         WHERE last_name = ?");
$sth->execute(@names);
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• fetchrow_arrayref
$row = $sth->fetchrow_arrayref;

Este método extrae la siguiente tupla con datos y devuelve una referencia a un araray con los valores de los campos. Si no hay más tuplas que obtener, devuelve undef. Cuando es usado con el método bind_columns, es el modo más rápido de extraer datos. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la BD: $dbh->errstr\n";
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name
                         FROM contact");
$sth->execute or
die "No se puede ejecutar consulta: $dbh->errstr\n";
my $row;
while($row = $sth->fetchrow_arrayref) {
    print "$row->[0] $row->[1]\n";
}
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• fetchrow_array
@row = $sth->fetchrow_array;

Es igual a fetchrow_arrayref excepto que devuelve un array con los valores de los campos, en lugar de una referencia a un array.
Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la BD: $dbh->errstr\n";
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name
                         FROM contact");
$sth->execute or
die "No se puede ejecutar la consulta: $dbh->errstr\n";
my @row;
while(@row = $sth->fetchrow_array) {
    print "$row[0] $row[1]\n";
}
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• fetchrow_hashref
$row_hash = $sth->fetchrow_hashref;

Otro método alternativo para extraer tuplas de datos. Este método devuelve una referencia a una memoria asociativa (hash) conteniendo para cada campo el nombre y el valor. Las claves de la memoria asocitiva (hash) son los mismos que los nombres de los campos devueltos por el método $sth->{NAME}. Este método es menos eficiente que el anterior. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se puede conectar con la BD: $dbh->errstr\n";
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name
                         FROM contact");
$sth->execute or
die "No se pude ejecutar la consulta: $dbh->errstr\n";
my $row_hash;
while($row_hash = $sth->fetchrow_hashref) {
    print "$row_hash->{first_name} $row_hash->{last_name}\n";
}
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• fetchall_arrayref
$table = $sth->fetchall_arrayref;

Este método es usado para obtener todos los datos (tuplas) devueltos por la sentencia SQL. Devuelve una referencia a un array de arrays de referencias. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la BD: $dbh->errstr\n";
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name
                         FROM contact");
$sth->execute or
die "No se puede ejecutar la consulta: $dbh->errstr\n";
my $table = $sth->fetchall_arrayref;
my($i, $j);
for $i ( 0 .. $#{$table} ) {
    for $j ( 0 .. $#{$table->[$i]} ) {
        print "$table->[$i][$j]\t";
    }
print "\n";
}
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• finish
$sth->finish;

Este método es usado cuando no se va a extraer más datos de un manejedor de sentencia, antes de que sea preparado de nuevo o destruido. Este método es el más usado para housekeeping interno (liberar recursos como cuando se bloquea la lectura). No hace falta llamar a este método si vas a destruirlo reusar el manejador de sentencia. De todos modos es bueno tomar el hábito de usarlo.


---

• rows
$rc = $sth->rows;

Este método devuelve el número de tuplas afectadas por la última sentencia no-Select ejecutada. Ejemplo:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la BD: $dbh->errstr\n";
my @names = ['Flaherty', 'Jones', 'Smith'];
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("UPDATE contact
                         SET phone = '555-1212'
                         WHERE last_name = ?");
$sth->execute(@names);
my $rc = $sth->rows;
print "Nuumero de registros actualizados: $rc\n";
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• bind_col
$sth->bind_col($column_number, \$var_to_bind);
$sth->bind_col($column_number, \$var_to_bind, \%attr);

Este método asigna una columna (campo) a una variable. Cuando una columna es captada (fetched) la correspondiente variable es automaticamente actualizada. Este hace que la extracción se muy eficiente.


---

• bind_columns
$sth->bind_columns(\%attr, @list_of_refs_to_vars_to_bind);

Este método llama a bind_col para cada columna de la sentecia SELECT. Example:

#!/usr/bin/perl -w
use DBI;
use strict;
my $dbh = DBI->connect("DBI:mysql:contacts",undef,undef)
or die "No se pude conectar con la BD: $dbh->errstr\n";
$dbh->{RaiseError} = 1;
my $sth = $dbh->prepare("SELECT first_name, last_name FROM contact");
my($first, $last);
$sth->bind_columns(undef, \$first, \$last);
$sth->execute;
while($sth->fetchrow_arrayref) {
    print "$first $last\n";
}
$sth->finish;
$dbh->disconnect;
exit;
__END__


---

• Atributos para Manejadores de Sentencias

• NUM_OF_FIELDS
$num_fields = $sth->{NUM_OF_FIELDS};

Este atributo guarda el número de campos que la sentencia ya preparada devolverá


---

• NUM_OF_PARAMS
$num_params = $sth->{NUM_OF_PARAMS};

Este atributo almacena el número de paraámetros (placeholders) que están preparados en la sentencia.


---

• NAME
$names = $sth->{NAME};

Este atributo devuelve una referencia a un array de nombres de campos para cada columna.


---

• NULLABLE
$nulls = $sth->{NULLABLE};

Este atributo devuelve una referencia a un array indicando cual es devuelto como NULL (true/false).


---

• CursorName
$cursor_name = $sth->{CursorName}; (not supported in mySQL)

Devuelve el nomdre del cursor asociado con el manejador de sentencia.


---

• Depuración (Debugging)
• DBI_TRACE

Además del método de seguimiento (trace) se puede activar infromación de seguimiento (trace) activando la variable de entorno DBI_TRACE antes de ejecutar el script. Si se activa DBI_TRACE a un valor no númerico se asume que es el nombre de un fichero donde se añade toda ls información de seguimiento (trace).


---