FORMULA LANGUAGE


@DbCommand (ODBC data source)
Example

Given data source information from the ODBC.INI file (or equivalent), uses this information to activate the appropriate ODBC driver. The driver then locates the specified DBMS, passes the specified command to it for processing, and returns the data retrieved by that command.

Note @DbCommand only works with ODBC data sources and only with SELECT statements. If used with statements that don't retrieve a result set, @DbCommand simply transmits the statement. Use the ODBC capabilities of LotusScript for more extensive interaction.

Syntax

@DbCommand( "ODBC" : cache ; data_source ; user_ID1 : user_ID2 ; password1 : password2 ; command_string : null_handling )

Parameters

"ODBC"


cache
user_ID1 : user_ID2
password1 : password2
command_string
null_handling
Return value

valuesFound


Note If you use the option button or the check box user interface for a keywords field, Lotus Domino updates the keyword list only when the document is composed or is loaded for editing. If you use the Standard user interface for the list, the keyword list is updated every time the document is recalculated.

Specifying the data source

The data source name can contain up to 32 alphanumeric characters.

@DbCommand can access data sources that have already been registered in the ODBC.INI file (or similar registry on platforms other than Windows).

Specifying IDs and passwords

You only need these arguments if your DBMS requires them.

Instead of storing the IDs in the @DbCommand formula, you can replace them with null strings (""). If an ID is required, the user will be prompted for it. This is useful when you do not want other designers to see IDs, or when you want users to enter their own IDs when accessing external data. However, you must include IDs and passwords in formulas that will run automatically (such as an agent) because these formulas don't prompt for information.

The user IDs and passwords for accessing a data source are required only once per Domino database session as long as that database remains open. If the user opens another Domino database and executes a formula that accesses the same data source, the user ID and password will be required again.

Password parameters are necessary only when ID parameters are specified. Like IDs, passwords can either be stored in the @DbColumn formula, or prompted for by substituting the null string. If the database password is null, you can omit it from the formula.

For example, for the full ID/password specification, enter:


Note For complex connections, additional ID and password parameters may be required to connect to the data source.

Specifying the command string

The command_string can be any of the following:


A date-time value must be entered in the format of the database, not that of Lotus Domino; for example, use 1996-01-31-12.00.00 for DB2/2, not 1996-01-31-12:00:00.

Specifying null handling

To control how null values are handled, specify one of the following, appended to the command_string parameter with a colon:


Accessing values found

@DbCommand can return no more than 64KB of data. Use the following equations to determine how much of your data can be returned with @DbCommand.


If the user's NOTES.INI file includes the statement

NoExternalApps=1

the @DbCommand formula is disabled. The user will not see an error message; the formula fails to execute.

Usage

@DbCommand is useful for testing a non-equal relationship (such as lessĀ­than), or for testing multiple conditions at the same time. To use @DBCommands, pass a command to the backĀ­end database for processing.

For example, to return data from records where:

BALANCE >= 1000.00 and DAYS_OVERDUE > 30

Write the selection statement in SQL, and then use @DbCommand to pass that statement to the DBMS for processing; @DbCommand then returns the requested data.

For Web applications, you can use this function only with the syntax:

@DbCommand("Domino";"ViewNextPage")

or

@DbCommand("Domino";"ViewPreviousPage")

to create a link to the next or previous page in a view. You cannot use @DbCommand in any other context with Web applications.

Note In a Web application, this command acts on an embedded view when it is called from an action on a page or document.

Example
See Also