Query Subsystem 

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.

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.

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

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