Finds the closest point to a target point using a filter to reject unwanted objects.
Syntax
intl pipObjectFindFirstNearestEx ( pipObjectFile obj_h, intl lonCenter, intl latCenter, intl maxHits, pstr criteria, pstr name, intl nameSize );
Arguments
obj_h The handle of the opened object file. Input.
lonCenter The longitude (in millionths of degrees) or x coordinate defining the input point. Input.
latCenter The latitude (in millionths of degrees) or y coordinate defining the input point. Input.
maxHits The maximum number of points to find. The maximum number of values you can request is 65,536. Input.
criteria The filter criteria is compared to values in the attribute file (GSA) to determine if the point is kept. The filter criteria uses the following format: Fieldname operator value:
- The Fieldname must be a valid field from the attribute file.
- String values support the following operators: =, <>, IN.
- The = operator for string values supports the * wild card operator as long as it appears as the last character.
- Numeric values support the following operators: =, <>, IN, >, >=,<, and <=.
- The IN operator works as an OR condition. All of the
values are compared until an exact match is found. Numeric values can be decimal numbers. (Commas are supported with all numeric operators except the IN operator, since the comma is the value delimiter for this operator).
- Values for string searches must be have an apostrophe on each end. An example is 'string value'. Values for numeric searches do not have this restriction.
Examples of valid criteria include:
- "Lastname = 'Smith'"
- "Population >= 20000"
- "Lastname IN ('Jones', 'Smith', 'Johnson', 'Williams')"
- "Lastname = 'Sm*'"
- "City <> 'Los Angeles'"
If the criteria is not valid, a PIP_ERROR is returned. Detailed information is available with the pipErrorGet function.
name A pointer to a buffer to be filled with the identifier of the object in which the point is located. Output.
nameSize The size of the buffer that contains the identifier of the object in which the point is located. If the buffer size is smaller than the identifier, the identifier is truncated. Input.
Return Value
PIP_ERROR PIP_NOT_FOUND PIP_OK
Prerequisites
pipObjectFileOpen
Alternates
pipRadFindFirstNearest
Notes
pipObjectFindFirstNearestEx uses a filter criteria to find the closest point to a target point.You must define a single field name, an operator, and a string that defines the object of the operator. Only those objects that satisfy the filter condition on the indicated attribute are returned. A simple check is performed on the attribute after the Spatial+ query is performed.
This function does the same thing as pipRadFindFirstNearest, except that there is no filtering and it does not require that all of the points are loaded into memory. It is somewhat slower than pipRadFindFirstNearest, so use it in situations where you want to minimize the startup time and do not require the fastest possible speed.
Use pipObjectFindNextEx or pipObjectFindNext to return the next closest object up to the number of maximum hits. The filter is applied before the maxHits parameter is processed. The maxHits parameter indicates the total number of points to search for. If this is set to 3, then pipObjectFindFirstNearestEx and pipObjectFindNext will not find more than 3 points, regardless of how many points are in the search tree. It is important to set this number carefully; setting too high a number may drastically increase the search time.
To get distance and bearing to the returned point, use pipDistance. If no points are found, the function returns PIP_NOT_FOUND.