Xbasic

SQL_Lookup Function

Syntax

A value = sql_lookup(* conn ,C table ,C filter ,C result_Expression [,* args [,L flagReturnAllValues [,C ColumnSeparator ]]])

Arguments

connCharacter SQL::Connection

An explicit AlphaDAO connection string, or a named connection string. E.g. ::name::myconnectionstring, or a pointer to an open SQL::Connection object.

tableCharacter

The name of the table in the remote database in which to perform the lookup.

filterCharacter

A filter expression to determine which record in the remote table to find. The filter expression must use SQL syntax and must use portable AlphaDAO functions. For example, strings must be single quoted, the AND, OR and NOT operators are not surrounded by periods. The filter expression can use arguments. For example, customerid = :whatcustomerid. The function will accept a blank filter expression and return all values. If the "result_Expression" in the function is a comma delimited list of fields, then the function returns all fields listed in "result_Expression" for the first record found when "flagReturnAllValues" is false.

result_ExpressionCharacter

A expression to determine what value gets returned. The expression can be as simple as a single column name in the remote table, or it can be a complex expression. The expression must be written using portable AlphaDAO syntax.

argsSQL::Arguments

If the filter expression includes arguments, you must supply argument values using a SQL::arguments object.

flagReturnAllValuesLogical

A flag that indicate whether or not all values should be returned. Returns one record if false, otherwise all records are returned.

ColumnSeparatorCharacter

Default = tab. The character used to separate columns. The column separator is only used if the result expression is a comma delimited field list.

Returns

valueAny Type Character

Value returned by the function. Can be of any type, depending on the value that result_expression evaluates to. Returns a null value if no matching value was found. If a filter is defined and a single field is specified in the return expression, the return value is typed appropriately. If more than one value is returned, or no filter is specified, the return value is a character string.

Description

Does a lookup into a table in a remote database using AlphaDAO. Returns a field value or expression from the remote table. Connection can be explicit, or a named connection (e.g. ::name::myconnection).

If you need to return multiple fields, use sql_lookup_multi(). The sql_lookup_multi() function is more efficient for looking up and returning multiple fields from a record.

Example 

connection = "{A5API=Access,FileName='C:\northwind2\northwind2003.mdb',UserName='Admin'}"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = 'bolid'"
?sql_lookup(connection,table,filter,result_expression)
= "Madrid - Mart n Sommer"

'This example uses a named connection string and it uses arguments in the filter
connection = "::Name::Northwind"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = :whatcustomerid"
dim args as sql::arguments
args.set("whatcustomerid","Bolid") ?sql_lookup(connection,table,filter,result_expression,args) = "Madrid - Mart n Sommer"

'In this example we pass in an open connection.
'Since the function will not have to open and then close the connection, it is significantly faster
dim cn as sql::connection
cn.open("::Name::Northwind")
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = 'bolid'"
?sql_lookup(cn,table,filter,result_expression)
= "Madrid - Mart n Sommer"

See Also