Busca en el archivo ODBC.INI el nombre del origen de los datos especificado y usa la información contenida en dicho archivo para activar el controlador ODBC adecuado. A continuación, el controlador localiza el DBMS (del inglés Database Management System, sistema de gestión de bases de datos), la tabla y la columna que se han especificado, y da como resultado únicamente los valores contenidos en dicha columna que pertenecen a aquellos registros que, en la columna clave, contienen la clave especificada. Opcionalmente, puede indicar si desea que la lista de valores esté ordenada, si los valores repetidos deben suprimirse y el modo en que deben tratarse los valores nulos.

Nota @DbLookup sólo puede recuperar datos; no puede añadirlos, suprimirlos ni modificarlos.

Sintaxis

@DbLookup( "ODBC" : caché ; "origen-datos" ; "ID1-usuario" : "ID2-usuario" ; "contraseña1" : "contraseña2" ; "tabla" ; "columna" : "valores-nulos" ; "columna-clave" ; "clave" ; "Distinct" : "ordenar" )

Parámetros

"ODBC"

Argumento de cadena. Use ODBC para indicar que desea acceder a un origen de datos ODBC.

Argumento de cadena. Opcional. En la búsqueda inicial, especifique "" o "NoCache". En el primer caso, para las siguientes búsquedas en el mismo origen de datos, especifique "ReCache".
• "" (cadena vacía) guarda en el caché los resultados de una búsqueda. La próxima vez que se vuelvan a consultar datos en la misma ubicación (dentro de la misma sesión de Domino, y siempre y cuando la base de datos que ejecuta la búsqueda permanezca abierta), se usarán los mismos datos hasta que se especifique "ReCache". El que los datos se mantengan en el caché mejora el rendimiento y puede ser una buena elección si se trabaja con datos estables.
• "ReCache" actualiza el caché con los datos más recientes de la base de datos. Si desea estar seguro de que la búsqueda obtiene la información más reciente, especifique esta opción.
Nota "ReCache" es una novedad de la Versión 6.
• "NoCache" obtiene los resultados de la búsqueda de la base de datos, sin utilizar ningún caché. Si desea estar seguro de que Lotus Domino recupera la información más reciente en cada búsqueda, especifique esta opción.

Texto. El nombre del origen de datos externo al que desea tener acceso. Este nombre está especificado como DSN (del inglés Data Source Name, nombre del origen de datos) en el Administrador de origen de datos o en el archivo odbc.ini. El origen de datos sirve para determinar la ubicación de una o varias tablas de base de datos. Consulte "Especificación del origen de datos".

Lista de cadenas de texto. Los ID de usuario necesarios para establecer la conexión con la base de datos externa. Dependiendo del DBMS al que se desea acceder, pueden ser necesarios hasta 2 archivos ID. Consulte "Especificación de los ID y de las contraseñas".

Lista de texto. Las contraseñas requeridas por los ID de usuario. Consulte "Especificación de los ID y de las contraseñas".

Texto. El nombre de la tabla de base de datos que se desea utilizar.

Texto. El nombre de la columna cuyos datos se desea obtener.

Texto. Se emplea para indicar qué se desea hacer si existen valores nulos entre los datos obtenidos. Consulte "Especificación de valores nulos".

Texto. El nombre de la columna en que debe buscarse la "clave" especificada.

Texto, número, fecha-hora o una lista de texto, de números o de fechas-horas. El valor que se ha de buscar en la columna-clave. Utilice el tipo de Notes que se corresponde con el tipo de la columna clave del origen de datos.

Argumento de cadena. Opcional. Elimina de la lista los valores repetidos antes de obtener los datos. Consulte "Especificación de la palabra clave Distinct" más adelante.

Argumento de cadena. Especifique "Ascending" si desea ordenar la lista en orden ascendente y "Descending" si desea hacerlo en orden descendente. Consulte "Especificación del orden" más adelante.

valores-hallados

Texto, número, fecha-hora o una lista de texto, de números o de fechas-horas. Los valores hallados en la columna indicada. Consulte "Acceso a los valores hallados" en este mismo capítulo.

Especificación del origen de datos

El nombre del origen de datos puede contener un máximo de 32 caracteres alfanuméricos.

Especificación de los ID y de las contraseñas

Solo necesitará usar este parámetro si emplea un DBMS que requiere su uso.

En lugar de almacenar los ID en la fórmula de @DbLookup, puede reemplazarlos por cadenas vacías. Si el uso de un ID es obligatorio, el controlador ODBC se lo pedirá al usuario. Esto resulta útil cuando no se desea situar los ID en una fórmula a la que pueden tener acceso otros diseñadores, o bien cuando se desea que cada usuario acceda a los datos externos haciendo uso de su propio ID en lugar de crear archivos ID genéricos. Sin embargo, sí deberá incluir los ID y las contraseñas en las fórmulas que se ejecuten automáticamente (por ejemplo, los agentes), ya que éstas no solicitan esta información al usuario.

En cada sesión de una misma base de datos de Domino, sólo es necesario especificar una vez los ID y las contraseñas de usuario que son necesarios para acceder al origen de datos, siempre que la base de datos permanezca abierta. Si el usuario abre otra base de datos de Domino y ejecuta una fórmula que hace uso del mismo origen de datos, el controlador volverá a pedirle el ID y la contraseña.

Solo necesitará emplear las contraseñas si está usando los parámetros ID descritos anteriormente. Al igual que los ID, las contraseñas pueden almacenarse en la fórmula de @DbLookup o bien reemplazarse por cadenas vacías, en cuyo caso, el controlador ODBC se las pedirá al usuario. Si la contraseña de la base de datos es una cadena vacía, puede omitirla de la fórmula.

Por ejemplo, si va a especificar la contraseña completa, introduzca lo siguiente:

• "";"" (dos cadenas vacías, separadas por un (;) punto y coma) si no desea especificar ni el ID ni la contraseña; es decir, para que el controlador solicite los dos
• "ID1-usuario":"contraseña1" si desea especificar un ID de usuario junto con una contraseña
• "ID1-usuario":"ID2-usuario";"contraseña1":"contraseña2" si desea especificar dos archivos ID de usuario junto con dos contraseñas

Si el DBMS lo permite, puede incluir el nombre del propietario de la tabla para evitar que se produzcan ambigüedades; use el formato "nombre-propietario.nombre-tabla". Asegúrese de que separa el nombre del propietario del nombre de la tabla mediante un punto.

Por ejemplo:

"dbo.author"

Tabla también puede hacer referencia a una vista de la base de datos del DBMS cuyos datos se están utilizando.

Especificación de valores nulos

Para controlar el modo en que se tratan los valores nulos, especifique una de las opciones siguientes detrás del parámetro columna, separada de éste por un signo de dos puntos:

• "Fail" Use esta palabra clave para generar este mensaje de error en caso de que la columna contenga algún valor nulo:

  Null values found - @Db function

  No se obtiene ningún dato junto con el mensaje.

• "Discard" Use esta palabra clave para omitir los valores nulos, con lo que acortará la lista de valores obtenidos. Si se omiten uno o varios valores durante la ejecución de la fórmula que contiene @DbLookup, Lotus Domino lo indicará mostrando este mensaje en la barra de estado:

  Caution: NULL values discarded from @Db list.

• "Valor de reemplazo" Indica el valor que se desea emplear para reemplazar los valores nulos. El valor de reemplazo debe ser una cadena entre comillas y del mismo tipo que los datos de la columna; por ejemplo, para una columna numérica, use un valor de reemplazo numérico.

  Si su fórmula incluye un argumento de cadena para ordenar los datos, la lista de valores obtenidos como resultado será ordenada antes de reemplazar los valores nulos. Al ordenar los datos, Notes situará los valores nulos al principio de la lista y no los reemplazará hasta después de que estén todos ordenados. No los reemplazará hasta después de que estén todos ordenados. Esto puede dar como resultado una lista en la que hay algunos valores ordenados incorrectamente. Por ejemplo, si especifica "zzz" como valor de reemplazo, todos los valores "zzz" se situarán al principio de la lista, incluso si ha indicado que ésta debe encontrarse en orden ascendente.

  Si se reemplazan uno o varios valores durante la ejecución de la fórmula que contiene @DbLookup, Domino lo indicará mostrando este mensaje en la barra de estado:

  Caution: NULL value replaced with user-defined value in @Db list.

  Por regla general, conviene asegurarse de que el valor de reemplazo indicado no coincidirá fácilmente con ninguno de los valores de la lista; por ejemplo, si la columna contiene texto, el valor de reemplazo podría ser "***"; de este modo, resultaría sencillo localizar los valores nulos.

Use "columna-clave" para indicar en qué columna debe buscarse la "clave" especificada; encierre entre comillas el nombre de la columna. Si el DBMS distingue entre mayúsculas y minúsculas al interpretar los nombres de las columnas, asegúrese de que emplea las letras correctas. Los valores de la columna clave no tienen por qué estar ordenados antes de que se recuperen los datos con @DbLookup.

Especifique un valor utilizando el formato de Notes Domino que se corresponde con el tipo de la columna clave del origen de datos. Por ejemplo, especifique un número o una expresión con valor numérico cuando la columna clave sea de cualquier tipo numérico, como, por ejemplo, entero, real, de coma flotante o de doble precisión. Si la clave es una cadena de texto, enciérrela entre comillas. Si desea especificar un valor de fecha-hora, introdúzcalo en el formato utilizado por la base de datos, no en el que utiliza Lotus Domino; por ejemplo, especifique 1997-01-31-12.00.00 para DB2/2 en lugar de 1997-01-31-12:00:00.

Al combinarlas, la columna clave y la clave forman la cláusula "donde" de una sentencia de selección:

"Seleccionar los registros donde columna-clave = clave"

La interfaz de la aplicación ODBC siempre comprueba igualdades y sólo da como resultado datos de aquellos registros que, en la columna clave, contienen un valor exactamente igual a la clave. Para comprobar si el valor de la columna clave coincide con uno de los valores contenidos en una serie de valores, formatee el valor de la clave como una lista y separe los elementos mediante signos de dos puntos; por ejemplo: "Rojo":"Azul":"Verde". Esto se comporta como una operación O, y da como resultado los datos de todos los registros que, en la columna clave, contienen un valor "Rojo" O "Azul" O "Verde". Si desea realizar una operación Y, use @DbCommand para pasar al DBMS la cadena con el comando adecuado. Asimismo, use @DbCommand para pasar la cadena con el comando adecuado si la clave es un valor de fecha-hora, ya que @DbLookup no siempre convierte este valor al formato correcto de fecha-hora del lenguaje de comandos de DBMS.

Si no consigue que @DbLookup dé como resultado los valores correctos a causa de u otros problemas, pruebe a usar una sentencia SELECT en @DbCommand.

Especificación de la palabra clave Distinct

El argumento de cadena Distinct es similar a la función @Unique de Lotus Domino; la diferencia estriba en que Distinct elimina los valores repetidos antes de presentar los datos en Lotus Domino. El uso de Distinct en lugar de @Unique tiene dos ventajas:

• La fórmula se ejecuta con mayor rapidez, ya que el trabajo adicional se realiza fuera de Lotus Domino.
• Es posible obtener una mayor cantidad de datos útiles. Dado que los valores repetidos se eliminan fuera de Lotus Domino, si la presencia de éstos hace que se alcance el límite de datos que pueden obtenerse con la función, al eliminarlos se conseguirá un número mayor de datos no repetidos en Lotus Domino.

Especificación del orden

Si emplea el argumento de cadena Distinct descrito anteriormente, introduzca el argumento correspondiente al parámetro ordenar detrás de Distinct y sepárelos mediante un signo de dos puntos, como se indica en el ejemplo de sintaxis. Use una de las dos palabras clave siguientes:

• "Ascending" ordena la lista en orden ascendente.
• "Descending" ordena la lista en orden descendente.

Nota Las palabras clave de ordenar no pueden emplearse con todos los controladores ODBC. Si intenta usar tanto "Ascending" como "Descending" en su fórmula, Lotus Domino mostrará un mensaje indicándole que ha usado un parámetro no válido.

Acceso a los valores hallados

Si el resultado son varios valores, se les dará formato de lista y se empleará el separador de valores múltiples especificado para el campo actual.

@DbLookup puede dar como resultado un máximo de 64 kB de datos. Use las ecuaciones siguientes para determinar la cantidad de datos que pueden obtenerse con @DbLookup.

• Para búsquedas que dan como resultado texto:

  2 + (2 * número de entradas obtenidas) + tamaño total del texto de todas las entradas

  Cada cadena de texto puede tener un máximo de 511 bytes; si se obtiene una única cadena de texto, ésta puede tener hasta 64 kB.

• Para búsquedas que dan como resultado números o fechas:

  (10 * número de entradas obtenidas) + 6

NoExternalApps=1

cualquier fórmula que contenga la función @DbLookup quedará desactivada. El usuario no verá ningún mensaje de error; simplemente Notes no ejecutará la fórmula. Esto sólo se aplica a @DbLookup cuando esta función se emplea con ODBC.

Uso

@DbLookup tiene su aplicación fundamental en fórmulas de palabras clave. En lugar de crear una fórmula con la lista de palabras clave permitidas en un campo y actualizar dicha lista periódicamente, @DbLookup le permite recuperar dinámicamente una lista de valores procedentes de una tabla de base de datos externa.

@DbLookup no puede utilizarse en agentes que se activan al recibir mensajes por correo, pero sí en aquellos que se activan al pegar documentos. Esta función únicamente opera en aplicaciones de Web si el servidor remoto que alberga la tabla de la que se recuperan los datos se encuentra en el mismo equipo que el servidor Domino, lo que es muy infrecuente.

Ejemplo
Véase también

Accessing external databases through LS:DO using @functions
@DbLookup (origen de datos Domino)
@DbCommand (origen de datos ODBC)
@DbColumn (origen de datos ODBC)
Funciones @ afectadas por la Lista de control de ejecución