FORM.VIEWQUERIED Function
Syntax
Arguments
- LayoutName
The name of the form to open. In the case where there are duplicate form names in the database, you can qualify the form name with the table name using this syntax: Form_Name@Table_Name. For example, if a database has a form called Customers for the Current_Customers and the Past_Customers tables, you can specify the form as: " Customers@Current_Customers, or Customers@Past_Customers.
- filter_expn
Optional. Default = ".T." (All records). A character filter expression that evaluates to a logical value and selects the records to show in the dialog.
- order_expn
Optional. Default = record order. A character order expression that sorts selected records.
- style
Optional. Default = "".
- Determines the mode of the form.
- "" (i.e. blank value) = Open the form as a standard modeless MDI window (same as if you double click on the form in the Control Panel)
- "dialog"
- "hidden"
- "hidden-dialog"
- "popup"
- x_position
Optional. Default = "" (i.e. use setting defined in the Form Properties dialog). The horizontal position of the window.
- Possible values are:
- "left"
- "right"
- "center"
- "fill"
- "pixel_coordinate"
- y_position
Optional. Default = "" (i.e. use setting defined in the Form Properties dialog). The vertical position of the window.
- Possible values are:
- "top"
- "bottom"
- "center"
- "fill"
- "pixel_coordinate"
- IsBaseQuery
Optional. 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 form. See 'Active Link Tables' below.
Description
Opens a form and applies a filter and/or order expression. Style = "" for normal, "dialog", "hidden" or "hidden-dialog". If IsBaseQuery = .t. (default value), use cannot remove the filter expression.
Discussion
The FORM.VIEWQUERIED() method opens Form Name and returns an object pointer, , to the form window. In the case where there are duplicate form names in the database, you can qualify the form name with the table name using this syntax: Form Name@Table Name. For example, if a database has a form called "Customers" for the "Current_Customers" and the "Past_Customers" tables, you can specify the form as: "Customers@Current_Customers", or "Customers@Past_Customers". To open the form as a modal dialog box, specify "Dialog" as the optional Style parameter. You can also specify a style of "Popup". See FORM.VIEW() for details. To load the form into memory, without displaying it, specify "Hidden" as the Style or, use the FORM.LOAD() method. Note : If you do not close the form at the end of your script, you will leave the underlying table(s) open.
Understanding 'Base Query'
When you design a form you can go to the Form, Properties dialog and and specify a filter expression for the form. When the form 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 form after the form has been opened (by using Query by Form, Query Genie, Query by expression, etc.). If the user applies some filter to the form 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 form 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 FORM.VIEWQUERIED() method is used with IsBaseQuery set to its default vlaue of .t. the filter that is specified becomes the form's new base query and it cannot be removed by the user. If IsBaseQuery is set to .f., then the form 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 form has been opened, the .BaseQueryRun() method can be used to specify a different base query for the form.
Examples
This script opens the Customer form and displays the record whose number is stored in the variable, recno.
dim shared recno as N
dim frm as P
dim filter as C
filter = "between(recno(), " + recno + "," + recno + ")"
'e.g. if recno = 23, filter = "between(recno(), 23,23)"
frm = form.viewQueried("customer",filter)
... do things
frm.close()This script opens the Customer form for all MA customers. Data is sorted by lastname and firstname
dim frm as P
dim filter as C
dim order as C
filter = "bill_state_region = 'MA'"
order = "lastname + firstname"
frm = form.viewQueried("customer",filter,order)
... do things
frm.close()This script does the same as the previous script, but it opens the form as a modal dialog box. Note the .CLOSE() method which is needed to close the dialog after the user dismisses the dialog.
dim frm as P
dim filter as C
dim order as C
filter = "bill_state_region = 'MA'"
order = "lastname + firstname"
frm = form.viewQueried("customer",filter,order,"dialog")
... do things
frm.close()This script opens the Customer form for all customers in the state specified by the whatState variable.
dim frm as P
dim filter as C
filter = between_char("state",whatState,whatState)
frm = form.viewQueried("customer",filter)
... do things
frm.close()This script opens the Customer form and shows the record in the range of record numbers specified by startrec and endrec.
dim frm as P
filter = between_record(startrec, endrec)
frm = form.viewQueried("customer",filter)
... do things
frm.close()Active Link Tables
A form 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 form is based are opened, the prompting is suppressed. The following example shows how a form that is based on an active-link table can be opened to show just the customers in 'London'. It is assumed that the form 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 = form.viewQueried("Customer","","","","","",.t.,args)In this example, the form 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. Note: 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