# Query Subsystem

Invoking a Query |

To invoke a query panel from your application, a number of methods are available:

- It can be associated with various types of Panel Controls.
- It can be included in Panel Events logic.
- It can be launched programmatically via the PROCESS directive.

Each of these methods, as well as how to invoke Query+ vs. the Classic Query, is explained below.

## Assigning a Query

Using the Panel Designer, you can associate a query with List Box, Drop Box, Multi-Line or Grid controls via the Query tab of a control definition.

#### Note:
If you are using the Property Sheets version of the NOMADS Panel Designer, then the Associated Object property for Multi-Line controls must be set to Query so that the Query property is active.

At run time, a query button is drawn next to Multi-Line controls that are one line high and have an associated query. The height of the Multi-Line must be set to 1; otherwise, NOMADS will not draw the button. Clicking this button invokes the associated query. A query can also be invoked (for all controls) by pressing Shift - F2. Besides the pre-defined queries that were described previously in this section, you can use the assigned query interface to launch query-related programs, non-query logic, spinner controls, calendars, etc.

Queries are assigned in the Panel Designer by selecting the Query tab of the control's definition.

## Query Type

The Query assignment interface allows you to assign one of five different Query Types:

Panel | Select Panel to assign a pre-defined query to the control. This refers to a query that has been defined using the query definition steps. See Defining a Query. When invoked, NOMADS passes the current value of the associated control to the query, and the selected query value is returned to that control. You can also use this interface to display a panel that is not a query definition. If you do this, then the value in the Multi-Line will be passed to and back from the panel in ARG_1$. Other information is also available to the panel in ARG_2$ through ARG_6$, which includes the name of the control invoking the query, the CTL value of the control, the control's tag value, the current panel name, and the channel of the current panel library. For information on making your Drop Query more closely emulate a Drop Box, see the PermaLock/Query Input attribute (on the Attributes tab of the Multi-Line Properties dialog).
Query Program | Select Query Program to run a program when the query is invoked. The value of the control is available to the program in the QRY_VAL$ variable. When the program has finished running, then the value in QRY_VAL$ is loaded back into the control. You can also use this type of query to invoke a service program, such as launching a website, an email interface, a map or a standardized file selection dialog. See Service Queries for Web, Email, Map and Open File.
Non-Query Logic | Select Non-Query Logic to execute specified logic when the query is invoked. Select the logic type (Link, Perform, Execute, etc.), and supply the program;label reference. The QRY_VAL$ variable interface is not available in this instance.
Spinner Controls | (Multi-Lines Only) Select Spinner Controls to attach a spinner control to a Multi-Line. A spinner control is a one-line vertical scrollbar drawn next to the control that can be used to increment/decrement numeric values in the Multi-Line.
Calendar | (Multi-Lines Only) Select Calendar to attach a calendar query to a Multi-Line to return a date. Calendar attributes must be previously defined using the NOMADS Calendar utility. #### Note: An alternate way to create a calendar query is to select Panel as the Query Type, and then set the Library to *win/calendar.* and the Panel to CALENDAR.

Depending on the Query Type selected, different information is entered:

Query Type: Panel
Panel Information | Query information can be entered as Fixed values or as an Expression. If Fixed, select a query definition by clicking the Select Query button or enter the Library and Panel information. If the information is an Expression, select Expression from the drop-down list and enter an expression that will be evaluated to give the query definition name and library in the following format: "QueryName,Library". (The library path is optional if the query uses the current library.)
Select Query | Button that invokes the Select a Query Definition window for selecting query definitions only. This window presents a tree-view structure that lists queries that exist at the current display level and lower, arranged by directory, screen library and query. Select a query by clicking on it. When selected, the Library and Panel input fields are automatically populated. To select other panel types, enter the Library and select a Panel. (The Select Query button and Select a Query Definition window were added in PxPlus 2020.)
Library | Enter the path to the library containing the query definition. The drop-down arrow invokes a list of recently used libraries. The Browse button allows you to browse the directory to find the library. Be sure to use the simplest form of the path for your application. #### Note: The Library name may be a specific or generic reference. See Cascading Language Suffixes.
Panel | Name of the query or panel definition to invoke. The drop-down list contains all panels in the library. If the query has not yet been defined, enter a new name and click the Define button to create it. #### Note: When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.
Define | Button that launches Query Definition window (for Standard Query) or Query List Definition (for Query List) using the Panel name to either create a new or edit an existing query definition. If creating a new query definition, a prompt displays for selecting a Query Type.
Auto Complete | (Multi-Lines Only) Besides the query reference, you can also assign the Auto Complete feature to a Multi-Line. Auto Complete attributes must be previously defined using the NOMADS Auto Complete utility.
Query Type: Query Program
Query Program | Enter the absolute, relative or simple path location of a user-supplied program, e.g. program;label, or simply ;label if the default program is being used. May be defined as a Fixed value or Expression.
Auto Complete | (Multi-Lines Only) Besides the query reference, you can also assign the Auto Complete feature to a Multi-Line. Auto Complete attributes must be previously defined using the NOMADS Auto Complete utility.
Query Type: Non-Query Logic
Non-Query Logic | Select the type of logic (Link, Perform, Call, Execute, etc.) and the program logic reference "program;label". Example: PERFORM "programs/browse;Browse_Directory"
Auto Complete | (Multi-Lines Only) Besides the query reference, you can also assign the Auto Complete feature to a Multi-Line. Auto Complete attributes must be previously defined using the NOMADS Auto Complete utility.
Query Type: Spinner Controls (Multi-Lines Only)
Increment | Sets the increment value for scrollbar movement.
Start | Minimum value of the spinner control.
End | Maximum value of the spinner control.
Query Type: Calendar (Multi-Lines Only)
Calendar | Select the calendar definition from the drop-down list. See Calendar utility.

#### Note:
A query can be associated with an entire grid as described or with individual cells within the grid. For information on grid queries, see Queries.

## Query Button Options

Query definitions that are associated with Multi-Lines and have a Query Type that is Panel, Query Program or Non-Query Logic also have Query Button Options. In general, the default appearance of query buttons is governed by the %NOMADS property settings Qry_Attr$, Qry_Btn$, Qry_Tip$, and Qry_Wide. See Query Variables.

The default values can be overridden by setting Query Button Options for the individual Multi-Line:

Query Button Options
Suppress Query Button | Suppresses the query button on the associated one-line high Multi-Line.
Bitmap Image | Specify the embedded or external bitmap to display on the button (Fixed or string Expression). Click the Query button to invoke the Bitmaps dialog. (The ability to enter an expression for a Bitmap Image was added in PxPlus 2019.)
Width | Width of the query button in columns. Enter a value or use the spinner control.
Floating Tip | Associate a floating tip message (Fixed, string Expression or Message Library Reference).
Attributes |
Bitmap Button | Button is a bitmap button.
Transparent | Button is "see-through" to the window contents behind the button area.
Flat Button | Button shows no raised outline unless the mouse is over the button or the button is pushed.
Flat – No Border | Button has no border and shows no raised outline when the mouse hovers or the button is pushed.
Embedded | Button is displayed within the Multi-Line, rather than shortening the Multi-Line and displaying the query button to its right.

If the Transparency attribute is not selected, the appearance of the query button will be affected by the active NOMADS theme (see Themes), or if a Visual Class is defined for the associated Multi-Line, Visual Class settings for the button will override the theme (see Visual Classes).

#### Note:
Query buttons are drawn only if the associated Multi-Line is one line high.
If the Multi-Line is greater than one line high, NOMADS will not draw the query button and will display a message when you save the Multi-Line. (If using Property Sheets, this message will only display in the Assign Query window (Query property) when a query is assigned and the OK button is selected.)
See Height in Multi-Line Properties.
(The message for Multi-Line height was added in PxPlus 2020.)

## Event-Driven Queries

A query can be launched automatically when an event for a control such as OnChange occurs when processing a NOMADS panel. See Events Logic. This is accomplished by defining Link logic for the control to trigger the query.

Example:

You can add a separate lookup button to a panel that triggers a query when pressed, then load the return value into the specified control. To process the query, assign logic to the button's OnChange logic:

> Link="LOOKUP_NAME","MYLIB.EN",NAME$

When the button is pressed, the query called LOOKUP_NAME in the MYLIB.EN library will be processed using the value in the NAME control. Be sure to select the Auto Refresh attribute in the Panel Header so that the value in the NAME$ Multi-Line is refreshed.

## Using the PROCESS Directive

The PROCESS directive can be used to invoke a NOMADS query panel directly from a program.

Format:

> PROCESS "panel_name","[ lib_name ]",value$

NOMADS returns to the program when the query panel is exited. You can pass one optional argument, a starting value to, and a return value from the query.

## Query Examples

Some query examples are provided below.

Example 1: | For queries that are not attached to a NOMADS control: 0110 PROCESS "MY_QUERY","",X$ When MY_QUERY runs, the value of X$ is used to set the starting position in the file. When MY_QUERY is exited, NOMADS passes the return value to the calling program in X$.
Example 2: | For event-driven queries: An alternative to using the Link method to launch an event-driven query (see Event-Driven Queries above) is to Execute a PROCESS command in the OnChange logic: Execute= PROCESS "LOOKUP_NAME","MYLIB.EN",NAME$;REFRESH_FLG=1 #### Note: REFRESH_FLG=1 is not necessary if the Auto Refresh attribute is turned On in the Panel Header.
Example 3: | For attached queries: Normally, attached queries do not require any code. If a query panel is assigned to a control, NOMADS provides a query button (or looks for a Shift – F2) to invoke the query and will process it automatically. However, you may want to process additional logic in conjunction with the query. In this case, assign a query program to the control. The program can do the additional logic, as well as invoke the query. The following is an example of a query program that invokes different queries depending on a condition: PROCESS_PRODUCT_QUERY: IF ProductCode="F" THEN PROCESS "PRODF_QRY","MYLIB.EN",QRY_VAL$ ELSE PROCESS "PRODX_QRY","MYLIB.EN",QRY_VAL$ EXIT For queries associated with a control, NOMADS uses the reserved variable QRY_VAL$ to pass the value of the control to the query and back.
Example 4: | For attached queries: If you want to include more complex programming to manipulate the query value before and after invoking the query, you must load QRY_VAL$ with the value you want to be loaded in the associated control: Process_Query: WorkVal$=QRY_VAL$ ! Get the current value of the control ! Manipulate WorkVal$ value however you want PROCESS "MY_QUERY","MYLIB.EN",WorkVal$ ! Start & return value ! Manipulate WorkVal$ return value however you want QRY_VAL$=WorkVal $ ! value is loaded back into the control EXIT If you process your own custom query panel rather than a NOMADS query panel, you can invoke it in the same way, being sure to use QRY_VAL$ to retrieve and reload the query control. Keep in mind that when you process your panel, the starting/return argument is passed to the panel as ARG_1$, and your panel logic must load ARG_1$ with the return value before exiting the query panel and returning to your program.
Example 5: | Using a single query to load multiple controls into a NOMADS File Maintenance panel: When you define a query, you can specify a formula for your return value that can return a string containing the values for multiple controls. To load multiple controls using a single query, you can assign a query program to the first control that will invoke the query and parse the return value to load the controls. The following is an example of a query program that will load three key segments into a NOMADS File Maintenance panel: Process_SalesData_Query: ! Build the starting value for the query KeyVal$=PAD(SDT_Smn_ID$,3,$00$)+SDT_Year$+SDT_Month$ ! Invoke the query using the starting value PROCESS "SDTQRY","",KeyVal$ ! Parse the value returned in KeyVal$ into the control variables ! Note that the control with the query must be loaded using QRY_VAL$ ! _kcnt, _numkeys and _enable_flg are NOMADS File Maintenance variables IF KeyVal$<>"" THEN QRY_VAL$=STP(KeyVal$(1,3),1,$00$); SDT_YEAR$=KeyVal$(4,4); SDT_MONTH$=KeyVal$(8,2); _kcnt=_numkeys,_enable_flg=1,refresh_flg=1 RETURN If you wish to invoke the query using a separate button rather than assigning the query program to the Multi-Line, the code for the button On Change logic is slightly different: Process_SalesData_Query: ! Build the starting value for the query KeyVal$=PAD(SDT_SMN_ID$,3,$00$)+SDT_YEAR$+SDT_MONTH$ ! Invoke the query using the starting value PROCESS "SDTQRY","",KeyVal$ ! Parse the value returned in KeyVal$ into the control variables ! _kcnt, _numkeys and _enable_flg are NOMADS File Maintenance variables IF KeyVal$<>"" \ THEN SDT_SMN_ID$=STP(KeyVal$(1,3),1,$00$); SDT_YEAR$=KeyVal$(4,4); SDT_MONTH$=KeyVal$(8,2); _kcnt=_numkeys,_enable_flg=_numkeys,_EOM$=$0D$; PERFORM "*win/flmaint;find_rec"; refresh_flg=1 RETURN

## Switching Modes: Query+ vs. Classic Query

Query+ mode is the default mode. You can use the QueryProgram$ property of the %NOMADS object to set the mode:

| To Use Classic Query: | Set %NOMADS'QueryProgram$="*winqry"
| To Use Query+: | Set %NOMADS'QueryProgram$="*winqry2"

It is also possible to force an individual query to be displayed in Classic mode by selecting the Use Classic Query option on the Query Header Definition Options tab. See Use Classic Query.