#set TITLE = "WHERE clause"
#include top

.SH WHERE clause
The \fCSELECT\fR, \fCUPDATE\fR, and \fCDELETE\fR commands involve the use of 
a \fCWHERE\fR clause to select rows.  
\fBshsql\fR's \fCWHERE\fR clause syntax does not conform to SQL standards and
is somewhat simplistic.
Nevertheless, it is reasonably powerful and flexible.

#include space


.SH Examples
.IP
\fCWHERE lastname = "Jones"\fR
.IP
\fCWHERE lastname LIKE "J*"\fR
.IP
\fCWHERE balance < 0.0 AND status = "A"\fR
.IP
\fCWHERE status = null\fR
or alternatively: 
\fCWHERE status IS null\fR
.IP
\fCWHERE status != null\fR
or alternatively: 
\fCWHERE status ISNOT null\fR
.IP
\fCWHERE color IN "red,green,blue"\fR
.IP
\fCWHERE desc_code IN "univ,hut,NULL"\fR
.IP
\fCWHERE placename IN "Pigeon Creek,Lost Valley"\fR
.IP
\fCWHERE name INLIKE "alb*,cran*,dela*"\fR
.IP
\fCWHERE zscore INRANGE -0.1,0.1\fR
.IP
\fCWHERE zscore OUTRANGE -2.5,2.5\fR
.IP
\fCWHERE authorlist CONTAINS "smith"\fR
.IP
\fCWHERE docname CONTAINS '"rolling stones" tour dates'\fR
.IP
\fCWHERE latitude INRANGE 38.1,38.5 OR latitude = null\fR


#include space

.SH Interaction with indexing
For data tables for which 
#set FILE = "indexes.html"
#set TAG = "indexes"
#include link
have been created, the \fCWHERE\fR clause plays an important role in the 
index access operation.  Many (but not all) comparison operators can exploit indexes.
#set FILE = "indexes.html"
#set TAG = "More info."
#include link

#include space

.SH Comparisons
A where clause contains one or more comparisons.
Comparisons usually have a database field specified on the left hand 
side, an operator in the middle, and a constant is on the right hand side.  
Comparisons \fBmust\fR be structured this way is indexing is involved; otherwise the constant
may be on the left if necessary (such as when getting wild card patterns from the database
for comparison against a constant using \fCLIKE\fR).
.LP
\fBshsql\fR supports the following comparison operators in \fCWHERE\fR clauses.
Some operators have one or more alternatives that may be used if desired.
.IP
.nf
\fB= \fR        Equal to.  Case sensitive. (alt: \fB==\fR or IS)
\fB!=\fR        Not equal to (alt: \fB<>\fR or ISNOT)
\fB> \fR        Greater than.
\fB>=\fR        Greater than or equal to.
\fB< \fR        Less than.
\fB<=\fR        Less than or equal to.
\fBLIKE\fR      Wild card match.  Case insensitive.
\fB!LIKE\fR     Not a wild card match (alt: NOTLIKE)
.fi
#include space
.LP
\fBshsql\fR also provides the following operators which are not part of 
standard SQL (some of these are available as functions in other SQL implementations).
See also the examples above.
.IP
.ig >>
<table cellpadding=0 cellspacing=4>
.>>
#include tabnewrow
\fBIN\fR
#include tabmidrow
true if field content is a member of a 
#set FILE = "#lists"
#set TAG = "list"
#include link
.br
#include tabnewrow
\fB!IN\fR
#include tabmidrow
opposite of IN.  Alternative usage: NOTIN
.br
#include tabnewrow
\fBINLIKE\fR
#include tabmidrow
similar to IN but 
#set FILE = "#lists"
#set TAG = "list"
#include link
members may contain wild cards.
.br
#include tabnewrow
\fB!INLIKE\fR
#include tabmidrow
opposite of INLIKE.  Alternate usage: NOTINLIKE
.br
#include tabnewrow
\fBINRANGE\fR
#include tabmidrow
true if field content is within a numeric range, expressed as a
#set FILE = "#lists"
#set TAG = "list"
#include link
(no embedded whitespace).
.br
#include tabnewrow
\fBOUTRANGE\fR
#include tabmidrow
true if field content is outside a numeric range, expressed as a
#set FILE = "#lists"
#set TAG = "list"
#include link
(no embedded whitespace).
.br
#include tabnewrow
#set FILE = "multiword.html"
#set TAG = "CONTAINS"
#include link
#include tabmidrow
multiword comparisons (search engine syntax).  Described on its own manual page.
.ig >>
</td></tr></table>
.>>

#include space

.SH Alpha vs. numeric
\fC=\fR and \fC!=\fR can be used with any data.
.LP
\fCIN\fR, \fC!IN\fR, \fCINLIKE\fR, and \fC!INLIKE\fR are intended for alphanumeric strings.
However since \fBshsql\fR is typeless, these operators can be used similarly with 
numerics eg. \fCid in "20,28,35"\fR or \fCid like "40*"\fR.  If the comparison
database field is indexed, the index should must be built as alpha, not numeric, in order
for this to work.
.LP
Numeric-only comparison operators are: \fC > >= < <= INRANGE OUTRANGE\fR.
If the comparison database field is indexed, the index must be built with
#set FILE = "create.html#index"
#set TAG = "ORDER = NUMERIC"
#include link
in order for numeric comparisons to work properly.



#include space

.SH Case sensitivity
The \fC=\fR and \fC!=\fR operators are case sensitive.  The other operations are case insensitive.
To do a direct case-insensitive comparison use \fCLIKE\fR instead of \fC=\fR.

.ig >>
<a name=lists></a>
.>>
#include space

.SH Lists
The \fCIN\fR, \fCINLIKE\fR, and \fCINRANGE\fR comparison operators (as well as their inverses)
take a 
#set FILE = "commalist.html"
#set TAG = "comma-delimited list"
#include link
as the right side operand.  
.LP
For \fCIN\fR and \fCINLIKE\fR (and inverses) the list should be enclosed in quotes,
\fCNULL\fR is permitted as a list member, and individual members may contain embedded 
spaces, which will be considered part of the individual.
Zero-length members are ignored; if the entire list is a zero-length string it is taken as \fCNULL\fR.
.LP
For \fCINRANGE\fR and \fCOUTRANGE\fR, the values are numbers, the list should not be enclosed
in quotes, should not have any \fCNULL\fR members, and should not contain any embedded whitespace.
The examples at top of this page include some that use comma-delimited lists.
Note that the
#set FILE = "multiword.html"
#set TAG = "CONTAINS"
#include link
operator can also be used with comma-delimited lists, however "words" are delimited not just on
commas but on any whitespace or punctuation.
.LP
Sometimes \fCSELECT DISTINCT\fR is in effect automatically when list comparison operators are used
on indexed fields..  see the notes at the end of the
#set FILE = "indexes.html"
#set TAG = "indexes manual page."
#include link



#include space

.SH Wild card characters
Wild card matching may be done using \fCLIKE\fR, \fC!LIKE\fR, \fCINLIKE\fR, and \fC!INLIKE\fR.
Wild card characters are \fB*\fR which 
matches any number of any character, and \fB?\fR which matches a single
instance of any character.  Matching is case-insensitive.
Full-fledged regular expressions capability is not implemented,
and use of the \fC*\fR character is limited to the following positions: 
\fC*abc\fR, \fCabc*\fR, \fCab*cd\fR, and \fC*abc*\fR.  \fC?\fR may be 
used anywhere.
(\fC%\fR may be used rather than \fB*\fR by setting \fCdbwildcard\fR in your 
#set FILE = "config.html#dbwildcard"
#set TAG = "project config file.
#include link
)

#include space

.SH NULL handling
#set FILE = "null.html"
#set TAG = "Described here."
#include link

#include space

.SH Searching text fields
The 
#set FILE = "multiword.html"
#set TAG = "CONTAINS operator"
#include link
allows multiword fields to be searched using a "search engine" syntax.

#include space

.SH Compound conditionals, and presidence
A compound conditional is two or more conditionals that are connected
using the \fBAND\fR and/or \fBOR\fR logical connectors:
.IP
.nf
\fBAND\fR       logical AND (alternate symbol: \fB&&\fR)
\fBOR\fR        logical OR (alternate symbol: \fB||\fR)
.fi
.LP
\fBPresidence:\fR compound conditional expressions are evaluated by splitting into \fCOR\fR
terms, and then evaluating each term starting with the leftmost.
For example:
.IP
.nf
\fCwhere  A = 1  and  B = 2  OR  C = null\fR

would be split into these terms: 

1.)  A = 1 and B = 2
2.)  C = null
.fi
.LP
\fBshsql\fR does not allow presidence to be altered by use of parentheses.  
The provided operators such as \fCIN\fR, \fCINLIKE\fR, \fCINRANGE\fR and \fCOUTRANGE\fR 
may be useful in eliminating lower-level \fCOR\fRs.
It may also be helpful to capitalize \fCOR\fRs to emphasize their presidence.
.LP
\fCSELECT DISTINCT\fR will be in effect automatically when \fCOR\fR is used
with a query involving indexed fields..  see the notes at the end of the
#set FILE = "indexes.html"
#set TAG = "indexes manual page."
#include link

#include space

.SH Functions and arithmetic expressions
.LP
These are not supported in \fBshsql\fR \fCWHERE\fR clauses.


#include bottom
