Query Syntax for "Canned" Searches
Product(s): WebPublisher PRO
Most WebPublisher textbases are searched with a QBE screen exported as an HTML form. This is not the only way to search a textbase with WebPublisher though, you can also create link searches or "canned" queries. These "canned" queries are just links that contain the same information that is sent from a search form when the submit button is clicked. You need to understand the syntax of the information sent to WebPublisher to generate your own URL for the link that will contain the "canned" search. When a user clicks on the 'submit query' button in a search form the browser gathers up the information in the search boxes and sends it to the server where WebPublisher can take the information submitted from a form and conduct a search. This information is grouped in name / value pairs and then encoded for transmission over the network. The order of the name / value pairs is not significant. The following link or "canned" query for WebPublisher searches the 'ID' field of the Support Knowledge base for record 2104.
<A HREF="http://support.inmagic.com/dbtw-wpd/exec/dbtwpub.dll?BU=http%3A%2F%2F
support.inmagic.com%2Fsearchsyntax%2FkbaseGet.htm&QB0=AND&QF0=ID&QI0=2104&MR=20&TN=kbase&
DF=Full+Article&RF=brief+by+Title&DL=0&RL=0&NP=1&AC=QBE_QUERY">See record2104</A>
The red characters in the string act as delimiters. The '?' ends the location this search string is sent to and '&' separates all other name value pairs. I have not included the delimiters in the break down of the string below. They are required to separate name / value pairs.
URL Encoding
URL encoding prevents special characters from being misinterpreted by the application that the string is sent to. The delimiters are one of the reasons why the values contained within the string must be URL encoded. An example of this is the '&'. It is considered to be a delimiter in the string above. It could also be part of a WebPublisher search, for example, I would like to search the 'NAMES' field for 'Smith & Jones'. In fact the '&' character is not the only character that must be encoded. The spaces surrounding the ampersand could also cause problems so the string Smith & Jones' is encoded for transmission so that it appears as 'Smith+%26+Jones' URL encoding can be tricky in that it combines hexadecimal notation and special characters like the '+'. Detailed explanations of URL encoding can be found on the web or in a CGI reference book, also you there is a reference chart included at the end of this article.
GET vs. POST
This "Canned" query is constructed using the GET method to submit information to the CGI script. A standard Query to WebPublisher uses the POST method. The primary advantage of Post over GET is that Get is a fixed length submission. It is possible to build a query that exceeds the length supported by your server causing the search to fail. The length of the string allowed is determined by the HTTP server you are using. Test your scripts thoroughly.
Name / Value pairs defined for WebPublisher 3.x and 4.x.
Understanding the name / value pairs that are sent to WebPublisher is the key to correctly constructing canned searches. This search string above contains all possible criteria that could be submitted to WebPublisher. Search strings can be much shorter.
Please Note: All calls within the string are case sensitive, such as AC_QUERY or QB0, etc. Form names, data or other DB/Textworks elements are not case sensitive.
The example above breaks down as follows:
The string starts with the location of WebPublisher. This string uses an ISAPI call to the dll. *REQUIRED*
http://localhost/dbtw-wpd/exec/dbtwpub.dll
A CGI call would submit the string to 'dbtwpcgi.exe' at the same location.
"BU" is the location of the link that submitted the search. It is required for a canned query if you would like to use expand record jump or change the report after the results of the canned query are returned. It is the complete URL of the page that contains the linked query.
BU=http%3A%2F%2Fsupport.inmagic.com%2Fsearchsyntax%2Fkbase.htm
"QB0" sets the Boolean state of the button for the search box in the form. (where "0" equals "zero")
QB0=AND
"QF0" is the field being searched (where "0" equals "zero")-*REQUIRED*
QF0=ID
"QI0" is the search string '2104' (where "0" equals "zero") -*REQUIRED*
QI0=2104
"MR" sets the maximum number of records that will be returned to the browser at on time.
MR=20
"TN" is the name of the textbase to be searched.*REQUIRED*
TN=kbase
"DF" is the default display form used for this search. The display form is the single record view of data. If the display form is not specified the Basic form will be used.
DF=WP+D+Detail
"RF" is the report form used by default. The report form is the multi-record form first seen by the searcher after they click the submit button. In this string the form "brief by Title" is selected for the report window. . If the display form is not specified the Basic form will be used.
RF=brief+by+Title
"DL" gives users the ability to change forms in the Display window. If "DL"=0 then users cannot change the display form. When this value is set to '1' a drop down list will appear allowing users to select a new form. If "DL" is absent from the query string the user will not be able to change the form.
DL=1
"RL" is the equivalent of "DL" except it applies to the report forms. Set "RL=1" to allow users to change the report form, "RL=0" locks users into the form you set. If "RL" is not included in the string user will not be allowed to change the forms.
RL=1
"NP" sets the location of the list as well as the next and previous buttons that appear in the report or display window.
NP=1
"ID" sets the password used in the textbase by the query. It is not shown in this example.
"XC" sets the eXecutable Control to either ISAPI or CGI, dependent on which protocol you are running. This is only required if using CGI exclusively (ie, you do not want to run ISAPI in any circumstances, or your web server does not support ISAPI directly) and can only be used in 4.1 or later of WebPublisher.
XC=/dbtw-wpd/exec/dbtwpcgi.exe
"AC" tells WebPublisher the type of information that is being submitted. Canned searches must always include 'AC= QBE_QUERY' *REQUIRED*
AC=QBE_QUERY
Examples:
Same search as above, minimum criteria:
<A HREF="http://support.inmagic.com/dbtw-wpd/exec/dbtwpub.dll?QF0=ID&QI0=2029&TN=KBase&
AC=QBE_QUERY">Bare Minimum</A>
Search for all WebPublisher records, use the check boxes form for report window display and the have Next/Previous buttons appear at the bottom of the report.
<A HREF="http://support.inmagic.com/dbtw-wpd/exec/dbtwpub.dll?BU=http%3A%2F%2F
support.inmagic.com%2Fsupbase.htm&QF0=product&QI0=WebPublisher&TN=Kbase&RF=Check+Boxes&NP=2&
AC=QBE_QUERY">WebPublisher Records</A>
Multiple search criteria within a field
Our searches have been very specific up till this point. We have searched one field for one criteria. You can create more complex searches using all search operators available to you in a regular WebPublisher search form. "Canned" searches can be identical to searches entered in a regular search screen form exported from DB/Textworks. If you are not familiar with search techniques see "QBE Query Syntax" in the on-line help for DBTextWorks or the WebPublisher HTML help pages. The difference is that when you enter a search in a form your web browser encodes the search so it can be sent over the network. When you create the search in a link you must encode the search criteria yourself.
The following search finds two records in the knowledge base and is equal to "2008 / 2020" entered in a box that searches the ID field on a search form.
QI0=2008+%2F+2020
Multiple search criteria, Multiple fields
The next search combines criteria in two separate fields. It searches the Product field for WebPublisher articles and the "Platform OS" field for Windows 95.
<A HREF="http://support.inmagic.com/dbtw-wpd/exec/dbtwpub.dll?BU=http%3A%2F%2F
support.inmagic.com%2Fsupbase.htm&QB0=AND&QF0=PLATFORM+OS&QI0=WINDOWS+95&
QB1=AND&QF1=Product&QI1=WebPublisher&MR=20&TN=kbase&DF=Full+Article&RF=brief+by+Title
&DL=0&RL=0&NP=2&AC=QBE_QUERY">WebPublisher and Win95 Articles</A>
WebPublisher and Win95 Articles
We can break the specified search into two parts in this query string, one for each field.
QB0=AND&QF0=PLATFORM+OS&QI0=WINDOWS+95
and
QB1=AND&QF1=Product&QI1=WebPublisher
Each field can then be broken into 3 elements
The last item in the name is the digit. It ties the element to the appropriate field. The digit always starts with 0 and increments up by one. The digit 1 in the name "QI1" tells WebPublisher that this is the search criteria for the second field.
Inmagic Search Operators and their URL encoded equivalents
The characters 0-9 and A-Z in both upper and lower case do not need to be encoded.
|
Search |
Character |
Encoded Equivalent |
|
Space |
{space} |
+ |
|
Quote |
" |
%22 |
|
Boolean NOT |
! |
%21 |
|
Boolean AND |
& |
%26 |
|
Boolean OR |
/ |
%2F |
|
Left Parentheses |
( |
%28 |
|
Right Parentheses |
) |
%29 |
|
Truncation |
* |
%2A |
|
Range |
: |
%3A |
|
Greater than |
> |
%3E |
|
Less than |
< |
%3C |
|
Equals |
= |
%3D |
For more information on searching Inmagic Textbases see the WebPublisher HTML help pages
Search Again or check the Support Forums