DBOPEN
Section: C Library Functions (3)
Updated: 2 Enero 1994
Index Return to Main
Contents
NOMBRE
dbopen - métodos de acceso a bases de datos
SINOPSIS
#include <sys/types.h>
#include <limits.h>
#include <db.h>
DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
DESCRIPCIÓN
Dbopen es la interfaz de biblioteca para los ficheros de
bases de datos. Los formatos de fichero soportados son árbolB,
dispersión y ficheros orientados a UNIX. El formato árbolB es una
representación de una estructura de árbol balanceada y ordenada. El
formato disperso es un esquema de dispersión dinámico y extensible.
El formato fichero plano es un fichero de flujo de bytes con
registros de longitud fija o variable. Los formatos y la
información específica de los formatos de los ficheros se describen
en detalle en sus páginas de manual respectivas btree(3),
hash(3)
y recno(3).
Dbopen abre el fichero file para lectura y/o escritura.
Los ficheros destinados a ser conservados en disco nunca pueden
crearse con un parámetro file con valor NULL.
Las opciones, flags, y los argumentos de modo,
mode, son los mismos que los indicados para la rutina open(2),
aunque sólo las opciones O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK,
O_RDONLY, O_RDWR, O_SHLOCK y O_TRUNC tienen sentido. (Dese cuenta
que no es posible abrir un fichero de base de datos con la opción
O_WRONLY).
El argumento type es de tipo DBTYPE (tal y como se define
en el fichero cabecera <db.h>) y puede tener el valor
DB_BTREE, DB_HASH o DB_RECNO.
El argumento openinfo es un puntero a una estructura
específica del método de acceso y descrita en la página de manual
del método de acceso. Si openinfo es NULL, cada método de
acceso usará valor por defecto apropiados para el sistema y para el
método de acceso.
Dbopen devuelve un puntero a una estructura DB en caso de
éxito y NULL en caso de error. La estructura DB se define en el
fichero cabecera <db.h>
y contiene, al menos, los siguientes campos:
typedef struct {
<dl><dt><dd>DBTYPE type;
int (*close)(const DB *db);
int (*del)(const DB *db, const DBT *key, u_int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
</dl>
} DB;
Estos elementos describen un tipo de base de datos y un conjunto
de funciones que realizan diversas acciones. Estas funciones toman
un puntero a una estructura como las devueltas por dbopen, y
algunas veces uno o más punteros a estructuras clave/datos y a un
valor de opción.
- type
- El tipo del método de acceso subyacente (y del formato de
fichero).
- close
- Un puntero a una rutina para vaciar a disco cualquier
información en caché, liberar cualquier recurso reservado y cerrar
el(los) fichero(s) subyacentes. Puesto que los pares clave/datos
pueden estar en la memoria caché, el dejar de sincronizar el
fichero con las funciones close o sync puede producir
inconsistencias o pérdida de información. Las rutinas close
devuelve -1 en caso de error (asignando un valor a errno) y
0 en caso de éxito.
- del
- Un puntero a una rutina para eliminar pares clave/datos de la
base de datos.
- Al parámetro flag se le pueden asignar el siguiente
valor:
-
- R_CURSOR
- Borra el registro referenciado por el cursor. El cursor debe
haber sido inicializado previamente.
- La rutina delete devuelve -1 en caso de error (asignando
un valor a errno), 0 en caso de éxito y 1 si la clave
key no estaba en el fichero.
- fd
- Un puntero a una rutina que devuelve un descriptor de fichero
representante de la base de datos subyacente. A todos los procesos
que llamen a dbopen con el mismo nombre fichero file,
se les devolverá un descriptor de fichero referenciando al mismo
fichero. El descriptor de fichero se puede usar de forma segura
como argumento de las funciones de bloqueo fcntl(2)
y flock(2).
El descriptor de fichero no está asociado necesariamente con
ninguno de los ficheros subyacentes usados por el método de acceso.
No se dispone de ningún descriptor de fichero para las bases de
datos residentes en memoria. Las rutinas fd devuelven -1 en
caso de error (asignando un valor a errno), y el descriptor
de fichero en caso de éxito.
- get
- Un puntero a una rutina que es la interfaz para la recuperación
por clave de la base de datos. La dirección y longitud de los datos
asociados con la clave especificada, key, se devuelven en la
estructura referenciada por data. Las rutinas get
devuelven -1 en caso de error (asignando un valor a errno),
0 e caso de éxito y 1 si la clave key no estaba en el
fichero.
- put
- Un puntero a una rutina para almacenar pares clave/datos en la
base de datos.
- Al parámetro flag se le puede asignar uno de los
siguientes valores:
-
- R_CURSOR
- Reemplazar el par clave/datos referenciado por el cursos. El
cursor debe haber sido inicializado previamente.
- R_IAFTER
- Añadir los datos inmediatamente después de los datos
referenciados por key, creando un nuevo par clave/datos. El
número de registro del par clave/datos añadido se devuelve en la
estructura key. (Aplicable sólo al método de acceso
DB_RECNO).
- R_IBEFORE
- Insertar los datos inmediatamente antes de los datos
referenciados por key, creando un nuevo par clave/datos. El
número de registro del par clave/datos insertado se devuelve en la
estructura key. (Aplicable sólo al método de acceso
DB_RECNO).
- R_NOOVERWRITE
- Introducir el nuevo par clave/datos sólo si la clave no existe
ya.
- R_SETCURSOR
- Almacenar el par clave/datos, poniendo o inicializando la
posición del cursor para que lo referencie. (Aplicable sólo a los
métodos de acceso DB_BTREE y DB_RECNO).
- R_SETCURSOR sólo está disponible para los métodos de acceso
DB_BTREE y DB_RECNO porque implica que las claves tienen un orden
inherente que no cambia.
- R_IAFTER y R_IBEFORE sólo están disponibles para el método de
acceso DB_RECNO porque cada una de ellas implica que el método de
acceso es capaz de crear nuevas claves. Esto sólo es cierto si las
claves están ordenadas y son independientes, por ejemplo, los
números de registro.
- El comportamiento por defecto de las rutinas put es
introducir el nuevo par clave/datos, reemplazando cualquier clave
ya existente.
- Las rutinas put devuelven -1 en caso de error (asignando
un valor a errno), 0 en caso de éxito y 1 si se especificó
la opción R_NOOVERWRITE en flag y la clave ya existía en el
fichero.
- seq
- Un puntero a una rutina que es la interfaz para la recuperación
secuencial de la base de datos. La dirección y longitud de la clave
se devuelven en la estructura referenciada por key, y la
dirección y la longitud de los datos se devuelven en la esctructura
referenciada por data.
- La recuperación secuencial de pares clave/datos pueden empezar
en cualquier momento y la posición del ``cursor'' no se ve afectada
por las llamadas a las rutinas del, get, put o
sync. Las modificaciones a la base de datos durante el
recorrido secuencial se reflejarán en el recorrido, es decir, no se
devolverán los registros insertados detrás del cursos mientras que
los registros insertados delante del cursor sí se devolverán.
- El valor de la opción debe ser uno de los siguientes
valores:
-
- R_CURSOR
- Se devolverán los datos asociados con la clave especificada.
Esto difiere de las rutinas get en las que también se
posiciona o inicializa el cursor a las posición de la clave. (Dése
cuenta que para el método de acceso DB_BTREE la clave devuelta no
es necesariamente una coincidencia exacta de la clave especificada.
La clave devuelta es la clave más pequeña mayor o igual que la
clave especificada, permitiendo así las coincidencias parciales de
claves y las búsquedas dentro de un intervalo).
- R_FIRST
- Se devuelve el primer par clave/datos de la base de datos y el
cursor se posiciona o inicializa para referenciarlo.
- R_LAST
- Se devuelve el último par clave/datos de la base de datos y el
cursor se posiciona o inicializa para referenciarlo. (Aplicable
sólo en los métodos de acceso DB_BTREE y DB_RECNO).
- R_NEXT
- Recupera el par clave/datos inmediatamente después del cursor.
Si el cursor todavía no está colocado, ésta opción es la misma que
R_FIRST.
- R_PREV
- Recupera el par clave/datos inmediatamente antes del cursor. Si
el cursor todavía no está colocado, ésta opción es la misma que
R_LAST. (Aplicable sólo en los métodos de acceso DB_BTREE y
DB_RECNO).
- R_LAST y R_PREV sólo están disponibles para los métodos
DB_BTREE y DB_RECNO yaque cada una de ellas implica que las claves
tienen un orden inherente que no cambia.
- Las rutinas seq devuelven -1 en caso de error (asignando
un valor a errno), 0 en caso de éxito y 1 si no existen
pares clave/datos menores o mayores que la clave especificada o
actual. Si se usa el método de acceso DB_RECNO y si el fichero de
la base de datos es un fichero especial de caracteres y no se
dispone actualmente de pares clave/datos completos, la rutina
seq devuelve 2.
- sync
- Un puntero a una rutina para vaciar a disco cualquier
información en caché. Si la base de datos está sólo en memoria, la
rutina sync no hace nada y siempre tendrá éxito.
- Al valor de la opción se le debe asignar el siguiente valor:
-
- R_RECNOSYNC
- Si se usa el método de acceso DB_RECNO, esta opción hace que la
rutina de sincronización se aplique al fichero árbolB que subyace
al fichero de registros numerados, no al propio fichero de
registros numerados. (Véase el campo bfname de la página de
manual de recno(3)
para más información.)
- Las rutinas sync devuelven -1 en caso de error
(asignando un valor a errno) y 0 en caso de éxito.
PARES CLAVE/DATOS
El acceso a todos los tipos de fichero se basa en los pares
clave/datos. Tanto las claves como los datos se representan
mediante la siguiente estructura de datos:
typedef struct {
- void *data;
size_t size;
} DBT;
Los elementos de la estructura DBT se definen como sigue:
- data
- Un puntero a un cadena de bytes.
- size
- La longitud de la cadena de bytes.
Las cadenas de bytes de claves y datos pueden referenciar a
cadenas de, esencialmente, longitudes ilimitadas aunque
cualesquiera dos de ellas deben caber en memoria al mismo tiempo.
Debe darse cuenta que los métodos de acceso no garantizan la
alineación de las cadenas de bytes.
ERRORES
La rutina dbopen puede fallar y asignar a errno
cualquiera de los errores especificados para las rutinas de
biblioteca open(2)
y malloc(3)
o uno de los siguientes:
- [EFTYPE]
- Un fichero está incorrectamente formateado.
- [EINVAL]
- Se ha especificado un parámetro (función de dispersión, byte de
relleno, etc.) que es incompatible con la especificación actual del
fichero o que no tiene sentido para la función (por ejemplo, el uso
del cursor sin una inicialización previa) o lo números de versión
del fichero y del software no coinciden.
Las rutinas close pueden fallar y asignar a errno
cualquiera de los errores especificados para las rutinas de
biblioteca close(2),
read(2),
write(2),
free(3)
o fsync(2).
Las rutinas del, get, put y seq
pueden fallar y asignar a errno cualquiera de los errores
especificados para las rutinas de biblioteca read(2),
write(2),
free(3)
o malloc(3).
Las rutinas fd pueden fallar y asignar a errno el
valor ENOENT para las bases de datos residentes en memoria.
Las rutinas sync pueden fallar y asignar a errno
cualquiera de los errores especificados para la rutina de
biblioteca fsync(2).
VÉASE TAMBIÉN
btree(3),
hash(3),
mpool(3),
recno(3)
LIBTP: Portable, Modular Transactions for UNIX, Margo
Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
FALLOS
El typedef DBT es un nemónico para ``base de datos thung'' (data
base thung), y se usó porque nadie pudo pensar en un nombre
razonable que no exisitiera ya.
La interfaz de descriptores de fichero es un latazo y se
eliminará en una futura versión de la interfaz.
Ninguno de los métodos de acceso proporciona ninguna forma de
acceso concurrente, bloqueo o transacción.
Index
- NOMBRE
- SINOPSIS
- DESCRIPCIÓN
- PARES CLAVE/DATOS
- ERRORES
- VÉASE TAMBIÉN
- FALLOS
This document was created by man2html, using
the manual pages.
Time: 06:16:25 GMT, January 22, 2005