====== QUERY.SUB=====

^Published By^Date^Version^Knowledge Level^Keywords^
|Sprezzatura Ltd|01 JUN 1991|2.03+|EXPERT|QUERY.SUB, LCQUERY.MODE, CUSTOMIZE, QUERY, RLIST, MAKE.SELECT, DO.QUERY|

John Parr of Progressive Computer Solutions in Basingstoke queried how to
get the system to produce RLIST sentences from stored data, in the way
achieved by the query window. Whilst investigating this, it became apparent
that QUERY.SUB (the routine used by the system to accomplish the \ Query
functionality) has application for all developers. Its usage is therefore
covered in this article.

Release 1.1 introduced "Query" technology, whereby the user could type in \
at the key prompt and convert the window into a query window. It also
introduced the frequently overlooked %%\\%% which permits the user to call back
the set of parameters used in the last query operation, modify and then
rerun them.

==== COMMON /LCQUERY.MODE/ ====

There are a number of labelled common areas maintained by the system for its
own use. As these are labelled common the developer has access to them.
Query uses an area called LCQUERY.MODE which has three variables associated
with it

<code>
     COMMON /LCQUERY.MODE/ FLAG, OLD_QUERY, TEMPLATE
</code>

|FLAG|This seems only to be set when the Query window is invoked with a %%\\%% at which time it will contain %%\\%% . It is subsequently cleared down and will therefore normally appear to be null.|
|OLD_QUERY|Contains the information making up the previous query in a field mark delimited array, with each element of the array corresponding to a prompt on the window.|
|TEMPLATE|The title of the query screen with which the current OLD_QUERY is associated.|

Thus without interacting with QUERY.SUB at all it is possible for the
developer to affect what will be displayed when the user enters %%\\%% . Simply
load OLD_QUERY with the query to be performed - in a layout corresponding to
the screen layout rather than the normal layout of @RECORD. Thus if the
company name were the second prompt on the screen, but field number four in
the current record, to preset the query to look for all companies whose name
began with A, OLD_QUERY would be loaded with @FM : "A]", and TEMPLATE with
the Query window title.

QUERY.SUB takes two parameters, the first being a branch, but the second
does not seem to be used. The possible branch values are  DO.QUERY,
CHECK.REDISPLAY, CUSTOMIZE, MAKE.SELECT and FILTER.SAVE. Those which the
developer can use are documented below.


==== DO.QUERY ====

Calling QUERY.SUB with a branch label of DO.QUERY forces the window to enter
query mode automatically. If the user selects any records using query, these
records will replace the currently active browse list - without
confirmation. This can be used to great effect by the developer if it is
wished to reassign "Query Mode" to a softkey. The softkey could simply call
a QUERY.SUB passing it DO.QUERY. Note that as mentioned above, if it is
desired to use the same parameters as previously in the query (perhaps on a
different softkey), the labelled common area FLAG must be loaded with %%\\%% .
Note further that if a record is currently displayed in the window and new
records are chosen, it is the job of the developer to unlock the current
record. The system will not do so.


==== MAKE.SELECT ====

This call is normally used to construct the RLIST sentence from the current
query window contents and to perform the select statement thus constructed,
returning an active select list. However it can be used by developers who
wish to have the system construct RLIST statements for them from known data
and make an active select list. The actual technique used is a little
cumbersome but effective.

Essentially one needs to write a program that includes all of WINDOW_COMMON%
but dimensions the WC_W% array to as many fields are there are to be in the
select statement. WC_W%<2> must be loaded with the dictionary names to use
and @RECORD must be loaded with the comparisons. Then QUERY.SUB is called
passing it MAKE.SELECT and an active select list is returned. To illustrate
this, try out the code segment below.

<code>
    COMMON WC_SRC_FILE%
    COMMON WC_SRC_DICT%
    ~~~~~~~~~~~~~~~~~~~~ Rest omitted for space
    COMMON WC_W%(5)
    ~~~~~~~~~~~~~~~~~~~~ Rest omitted for space
    CLEAR COMMON
    WC_W_CNT% = 5 ; * Set to no of fields to query on
    WC_W%(1)<2> = "F1" ; * field names
    WC_W%(2)<2> = "F2"
    WC_W%(3)<2> = "F3"
    WC_W%(4)<2> = "F4"
    WC_W%(5)<2> = "F5"
    WC_DATAFILE% = "VOC" ; * filename
    @RECORD = "VERB]" ; * comparisons
    @RECORD<3> = "VERBS;BP"
    CALL QUERY.SUB("MAKE.SELECT","")
    PERFORM "LIST VOC"
</code>

Examine the TCL stack to see how QUERY.SUB has constructed the select
statement.

==== CUSTOMIZE ====

Customize is normally used within the query window to call the QUERY.SELECT/
command window for customising RLIST.SELECT and RLIST.SORT. It is possible
to define (in @ENVIRON.SET<57> and <58>) a code and command to be called in
place of the customize window. If this is done, the select and sort
statement generated by QUERY.SUB will be passed to the alternative routine
in @PSEUDO<1> and <2> respectively.


Thus if it was required to generate the select statement BUT NOT run it, the
code above would be used, but with the following changes. @ENVIRON.SET would
be temporarily modified to call a routine to capture @PSEUDO. QUERY.SUB
would be called with CUSTOMIZE, then @ENVIRON.SET would be restored.


(Volume 3, Issue 2, Pages 6,7)