Description
Returns the next record that meets the specified criterea.
Syntax
object.Find( Expression [,Envelope] [,FromBookmark] [,ScriptLanguage] ) |
|
Parameters
- Expression
- Required. A String that specifies the search terms.
- Envelope
- Optional. A Rectangle that specifies the extent to search within.
- FromBookmark
- Optional. A Long that specifies the starting bookmark for the search.
- ScriptLanguage
- Optional. A String that specifies the script language used to define the expression.
Return Type
Long
Remarks
Expression is a string specifying the search terms in the form: "[FIELD] = VALUE".
For example, if you have a field called NAME and you want to search for the value John, you would use:
"[NAME] = ""John"""
If you want to search for the values John or Sally, you would use:
"[NAME] = ""John"" OR [NAME] = ""Sally"""
If you want to search for all values beginning with J, you would use:
"[NAME] >= ""J"" AND [NAME] < ""K"""
When using variables as part of the expression, you need to build up the expression using the contents of the variables rather than the names of the variables. For example, if you want to search for the value stored in the variable strName, you would use:
"[NAME]=""" & strName & """"
Note the double quotes inside the expression. This is how you place a string inside another string in VBScript (the Expression argument itself is a string). Here's an example using a numeric field:
"[AGE] > 10"
To take advantage of attribute indexes on fields used in the expression, use the character sequence "//" followed by the index critera. For example:
Recordset.Find("[TREETYPE] = 8 // CITY = 'Redlands' ")
The example above is a query that will find trees with a type 8 that also are in Redlands. The " CITY = 'Redlands' " part is used for the fast attribute indexed search, while the expression "[TREETYPE] = 8" is processed by the (slower) scripting engine for further refinement.
Expressions used in previous versions of ArcPad can be tuned to take advantage of index-based queries. For example:
Recordset.Find( "LEFT([RDNAME],4) = ""Main"" AND [RDTYPE] = ""RD"" " )
can be modified to use an attribute index on RDNAME as follows:
Recordset.Find( "LEFT([RDNAME],4) = ""Main"" AND [RDTYPE] = ""RD"" // RDNAME LIKE 'Main*' ")
Here are some additional example expressions that take advantage of attribute indexes:
"// NAME = 'Stephen Quan'"
"// NAME LIKE 'Steph*'"
"// NAME LIKE 'St?ph?n*'"
"// NAME = 'Stephen' AND AGE = 35"
"// NAME = 'Stephen' AND NOT (GENDER = 'F')"
"// NAME = 'Stephen' OR NAME = 'Elvin'"
"// WHEN = '20062203'"
"// CHECKED = 'T'"
The rules when building expressions that use attribute indexes are:
a. Column names are specified as: NAME or "NAME".
b. The multi-character wildcard in LIKE expressions is either * or %.
c. The single character wildcard in LIKE expressions is ?.
d. String expressions are enclosed by single quotes. For example, 'somestring'. Double quotes refer to columns.
e. String searches are case insensitive. For example, NAME = "Stephen" will also return "stephen" and "STEPHEN".
f. Numerical expressions are supplied without quotes. For example, 3.14159.
g. Date expressions are an 8 character quoted string. For example, '20060420' represents April 20, 2006.
h. Logical expressions are quoted strings starting with 'T', 'Y', '1' representing true, false otherwise.
i. Use boolean operators such as AND, OR and NOT to combine expressions.
j. The precedence rule is AND, followed by OR, followed by NOT. For example, A AND B OR C AND D is the same as (A AND B) OR (C AND D).
k. Use ( and ) to alter the order of precedence. For example, ((A AND B) OR C) AND D.
Envelope is a rectangle specifying the extent to search within. If not specified, the entire map is searched. [Optional].
FromBookmark is a long specifying the starting bookmark for the search. If not specified, or set to 0, the search starts from the first record. [Optional].
ScriptLanguage is a string specifying the script language to use when parsing the Expression argument. If not specified, the default script language specified in the preferences is used. ScriptLanguage can be any valid scripting language present on the system and does not have to be the same as the language of the calling script.
Each time you call the Find method, one result is returned. A return value of 0 indicates that no record was found. If you want to find multiple records, keep calling the Find method while the return value is not 0 and pass in the previously returned value as the FromBookmark argument.
For example, if you have a field called NAME and you want to search for the value John, you would use:
"[NAME] = ""John"""
If you want to search for the values John or Sally, you would use:
"[NAME] = ""John"" OR [NAME] = ""Sally"""
If you want to search for all values beginning with J, you would use:
"[NAME] >= ""J"" AND [NAME] < ""K"""
When using variables as part of the expression, you need to build up the expression using the contents of the variables rather than the names of the variables. For example, if you want to search for the value stored in the variable strName, you would use:
"[NAME]=""" & strName & """"
Note the double quotes inside the expression. This is how you place a string inside another string in VBScript (the Expression argument itself is a string). Here's an example using a numeric field:
"[AGE] > 10"
To take advantage of attribute indexes on fields used in the expression, use the character sequence "//" followed by the index critera. For example:
Recordset.Find("[TREETYPE] = 8 // CITY = 'Redlands' ")
The example above is a query that will find trees with a type 8 that also are in Redlands. The " CITY = 'Redlands' " part is used for the fast attribute indexed search, while the expression "[TREETYPE] = 8" is processed by the (slower) scripting engine for further refinement.
Expressions used in previous versions of ArcPad can be tuned to take advantage of index-based queries. For example:
Recordset.Find( "LEFT([RDNAME],4) = ""Main"" AND [RDTYPE] = ""RD"" " )
can be modified to use an attribute index on RDNAME as follows:
Recordset.Find( "LEFT([RDNAME],4) = ""Main"" AND [RDTYPE] = ""RD"" // RDNAME LIKE 'Main*' ")
Here are some additional example expressions that take advantage of attribute indexes:
"// NAME = 'Stephen Quan'"
"// NAME LIKE 'Steph*'"
"// NAME LIKE 'St?ph?n*'"
"// NAME = 'Stephen' AND AGE = 35"
"// NAME = 'Stephen' AND NOT (GENDER = 'F')"
"// NAME = 'Stephen' OR NAME = 'Elvin'"
"// WHEN = '20062203'"
"// CHECKED = 'T'"
The rules when building expressions that use attribute indexes are:
a. Column names are specified as: NAME or "NAME".
b. The multi-character wildcard in LIKE expressions is either * or %.
c. The single character wildcard in LIKE expressions is ?.
d. String expressions are enclosed by single quotes. For example, 'somestring'. Double quotes refer to columns.
e. String searches are case insensitive. For example, NAME = "Stephen" will also return "stephen" and "STEPHEN".
f. Numerical expressions are supplied without quotes. For example, 3.14159.
g. Date expressions are an 8 character quoted string. For example, '20060420' represents April 20, 2006.
h. Logical expressions are quoted strings starting with 'T', 'Y', '1' representing true, false otherwise.
i. Use boolean operators such as AND, OR and NOT to combine expressions.
j. The precedence rule is AND, followed by OR, followed by NOT. For example, A AND B OR C AND D is the same as (A AND B) OR (C AND D).
k. Use ( and ) to alter the order of precedence. For example, ((A AND B) OR C) AND D.
Envelope is a rectangle specifying the extent to search within. If not specified, the entire map is searched. [Optional].
FromBookmark is a long specifying the starting bookmark for the search. If not specified, or set to 0, the search starts from the first record. [Optional].
ScriptLanguage is a string specifying the script language to use when parsing the Expression argument. If not specified, the default script language specified in the preferences is used. ScriptLanguage can be any valid scripting language present on the system and does not have to be the same as the language of the calling script.
Each time you call the Find method, one result is returned. A return value of 0 indicates that no record was found. If you want to find multiple records, keep calling the Find method while the return value is not 0 and pass in the previously returned value as the FromBookmark argument.