Usa la información sobre el origen de datos especificado 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 todos los valores contenidos en dicha columna. 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 @DbColumn sólo puede recuperar datos; no puede añadirlos, suprimirlos ni modificarlos.

Sintaxis

@DbColumn( "ODBC" : caché ; origen-datos ; ID1-usuario : ID2-usuario ; contraseña1 : contraseña2 ; tabla ; columna : valores-nulos ; "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. 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 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".

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.

@DbLookup sólo puede acceder a aquellos orígenes de datos que se hayan registrado previamente en el archivo ODBC.INI (o en un registro similar para plataformas distintas de Windows™).

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 @DbColumn, 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 @DbCommand 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

Normalmente, los valores nulos se ignoran y la lista resultante se acorta (del mismo modo que cuando se usa la opción "Discard", descrita más adelante).

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:

  Se han hallado valores nulos; se está cancelando la función @db

  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 @DbColumn, aparecerá 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. 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 @DbColumn, aparecerá 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 en Lotus Domino.

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 obtener los datos. 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 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. El parámetro ordenar sirve para ordenar la lista de valores antes de incorporarla a Notes.

• "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, aparecerá un mensaje indicándole que ha usado un parámetro no válido.

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.

@DbColumn 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 @DbColumn.

• 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 @DbColumn quedará desactivada. El usuario no verá ningún mensaje de error; simplemente Notes no ejecutará la fórmula. Esto sólo se aplica a @DbColumn cuando esta función se emplea con ODBC.

Uso

@DbColumn 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, @DbColumn le permite recuperar dinámicamente una lista de valores procedentes de una tabla de base de datos externa.

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.

Equivalencias en otros lenguajes

Método GetValue de la clase ODBCResultSet de Lotus Connectors

Ejemplo
Véase también

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