Busca en el archivo ODBC.INI (o un archivo equivalente) el nombre del origen de 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), le pasa el comando especificado para que lo procese y da como resultado todos los valores seleccionados por dicho comando.

Nota @DbCommand sólo se aplica a los orígenes de datos ODBC y sólo con sentencias SELECT. Si se utiliza con sentencias que no seleccionan un conjunto de valores, se limitará a transmitir la sentencia. Utilice la posibilidad que le brinda ODBC de utilizar scripts creados con LotusScript si desea una mayor interacción.

Sintaxis

@DbCommand( "ODBC" : caché ; origen-datos ; ID1-usuario : ID2-usuario ; contraseña1 : contraseña2 ; cadena-comandos : valores-nulos )

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. Una sentencia SQL, una sentencia de comandos, o el nombre del procedimiento que se desea ejecutar. Consulte "Especificación de una cadena de comandos" más adelante.

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

valores-hallados

Texto, número, fecha-hora o una lista de texto, de números o de fechas-horas. Los valores que da como resultado la cadena-comandos. Consulte "Acceso a los valores hallados" más adelante.

Especificación del origen de datos

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

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

Especificación de una cadena de comandos

El parámetro cadena-comandos puede ser de cualquiera de los tipos siguientes:

• Una sentencia SQL (debe usarse la sintaxis de SQL adecuada para el DBMS).
• Una sentencia de comandos que haga uso del lenguaje de comandos del DBMS.
• El nombre de un procedimiento almacenado en el DBMS (un procedimiento contiene una o varias cadenas de comandos que se activan cuando @DbCommand hace una llamada al procedimiento).

Especificación de valores nulos

Para controlar el modo en que se tratan los valores nulos, especifique una de las opciones siguientes a continuación del parámetro cadena-comandos; separe ambos elementos mediante 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 @DbCommand, 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 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.

  Si se reemplazan uno o varios valores durante la ejecución de la fórmula que contiene @DbCommand, 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.

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

• 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 @DbCommand quedará desactivada. El usuario no verá ningún mensaje de error; simplemente Notes no ejecutará la fórmula.

Uso

@DbCommand resulta de utilidad para comprobar relaciones de desigualdad (como, por ejemplo, menor que) o para comprobar varias condiciones al mismo tiempo. Para usar @DBCommand, pase un comando al otro programa gestor de bases de datos para que sea éste quien lo procese.

Por ejemplo, para obtener datos de aquellos registros que cumplen la condición:

SALDO >= 1000000 Y DIAS_VENCIDOS > 30

Escriba la sentencia de selección adecuada en SQL y después use @DbCommand para pasar dicha sentencia al DBMS con objeto de que éste la procese; @DbCommand dará como resultado los datos solicitados.

En las aplicaciones para Web, esta función sólo puede usarse con la sintaxis:

@DbCommand("Domino";"ViewNextPage")

O bien,

@DbCommand("Domino";"ViewPreviousPage")

para crear un vínculo a la página siguiente o anterior de una vista. @DbCommand no puede usarse en ningún otro contexto con las aplicaciones para Web.

Nota En una aplicación de Web, este comando actúa sobre una vista incrustada cuando es invocado desde una acción de una página o documento.

Ejemplo
Véase también

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