Xbasic

BROWSE.VIEWQUERIED Function

Syntax

as P = Browse.ViewQueried(C LayoutName [,C filter_expn [,C order_expn [,C x_position [,C y_position [,L IsBaseQuery [,* arguments ]]]]]])

Arguments

LayoutName

The name of the browse to open. In the case where there are duplicate browse names in the database, you can qualify the browse name with the table name using this syntax: Browse [email protected] Name. For example, if a database has a browse called "Customers" for the "Current_Customers" and the "Past_Customers" tables, you can specify the browse as: "[email protected]_Customers", or "[email protected]_Customers". r

filter_expn

Optional. Default = all records, subject to any filter defined in the browse layout itself. A character filter expression that evaluates to a logical value and selects records from the table.

order_expn

Optional. Default = record order. A character order expression that sorts selected records.

x_position

Character

y_position

Character

IsBaseQuery

The default value for this property is .T. Specify if the query is a 'base query' or not. See 'Understanding Base Query' below.

arguments

Optional. Allows you to pass in argument values for any arguments that might be referenced by tables in the Browse. See 'Active Link Tables' below.

Description

BROWSE.VIEWQUERIED()opens Browse_Name, displaying selected and ordered records, and returns the BROWSE > object pointer to the browse window.

If IsBaseQuery = .t. (default value), use cannot remove the filter expression.

You cannot open a browse window as a modal dialog box. If you wish to have a modal browse window, design a form with an embedded browse, and then open the form as a modal dialog.

Understanding 'Base Query' 

When you design a Browse layout you can go to the Browse, Properties dialog and and specify a filter expression for the browse. When the browse is opened, only records that satisfy the filter will be shown. This filter is referred to as a 'base query' because it is always applied regardless of what additional filter the user might add to the browse after the browse has been opened (by using Query Genie, Query by expression, etc.). If the user applies some filter to the browse and then clicks the 'show all' button to remove the filter that he added, the base query is still in place. The user cannot remove the base query. (You will notice that when a base query has been defined, the Select Index/Query command is disabled, and the button to change the search key on the Find by Key dialog is also disabled because enabling them would allow the user to remove the base query.). So, for example, if a browse has a base query of 'State = "MA" ' and the user defines a query to search for ' Lastname = "Smith" ', the actual query is ' State = "MA" .and. Lastname = "Smith" '. When the user clicks the 'Show All' button, the 'State = "MA"' query is still in place. When the BROWSE.VIEWQUERIED() method is used with IsBaseQuery set to its default vlaue of .t. the filter that is specified becomes the browse's new base query and it cannot be removed by the user. If IsBaseQuery is set to .f., then the browse is opened showing just the records that satisfy the filter condition, but the filter is not a base query and the user can click the 'Show All' button to remove the filter. Note. After a browse has been opened, the .BaseQueryRun() method can be used to specify a different base query for the browse.

Active Link Tables 

A browse can be based on an active-link table or a set that includes active-link tables. An active-link table can use one or more arguments in its SQL Select statement. For example: SELECT * from customers where city = :whatcity When an active-link table is opened, Alpha Anywhere will prompt for the value of any argument if a value for that argument has not been supplied. The .ViewQueried() method allows you to pass in argument values so that when the active-link table(s) on which the browse is based are opened, the prompting is suppressed. The following example shows how a browse that is based on an active-link table can be opened to show just the customers in 'London'. It is assumed that the browse in this case ('Customer') is based on an active-link table that has an argument in the SQL Select statement.

dim args as sql::arguments
args.add("whatcity","London")
dim f as p 
f = browse.viewQueried("Customer","","",.t.,args)

In this example, the browse will open quickly because the query is executed on the server. You can also specify a "client-side" filter by specifying a value for the option Filter_expn parameter. The "client-side" filter is applied in addition to any server-side filter that is part of the active-link table's definition.

When you specify a value for the filter_expn parameter, the Alpha Anywhere Query Optimizer will analyze the filter expression and determine if it can be expressed as a SQL filter. If so, it will actually execute the query on the server.

Limitations

Desktop applications only.

See Also