Get Three Proximity References Enhanced - OMTHRPRXE (new for v7.0)
Get Three Proximity References Enhanced (OMTHRPRXE) (new for v7.0)
Required Parameter Group:
| 1 | Place Type #1 | Input | Char(5) |
| 2 | Place Type #2 | Input | Char(5) |
| 3 | Place Type #3 | Input | Char(5) |
| 4 | Latitude | Input | Packed(9,6) |
| 5 | Longitude | Input | Packed(9,6) |
| 6 | Proximity Reference #1 | Output | Char(256) |
| 7 | Proximity Reference #2 | Output | Char(256) |
| 8 | Proximity Reference #3 | Output | Char(256) |
| 9 | Return Status | Output | Char(1) |
API Overview:
The Get Three Proximity References Enhanced API (OMTHRPRXE) returns one, two, or three proximity references for a given latitude/longitude pair. The returned proximity reference contains information regarding the nearest QTRACS place of the specified type. A place is a point on the earth that has been predefined in the QTRACS Place Database. The distance and direction of the nearest place is returned to the calling application along with the associated name, state, postal code, and identifier of that place.
Each place is defined as a certain type , which may be CITY, TOWN, or one of the many user-defined place types. The OMTHRPRXE API must be passed a place type that is used to limit the proximity search to those places of the specified type. This function will accept up to three types and return a proximity reference for each type.
Required Parameter Group Details:
(1) Place Type #1
INPUT; CHAR(5)
This parameter controls which types of places will be considered by the API when trying to determine the nearest place to return as the proximity reference. Valid values are:
| TOWN | Return a proximity reference to the nearest place of type TOWN (unless a City is closest) |
| CITY | Return a proximity reference to the nearest place of type CITY |
| ttttt | Return a proximity reference to the nearest place of the user defined type ttttt |
| *UDEF | Return a proximity reference to the nearest place of any user-defined type |
| *QUIT | Remove program from memory and return control to calling application |
Place Type #1 must be filled but Place Types #2 and #3 are optional. Blanks should be moved to Place Type #2 and #3 when not in use. If the requested type is equal to *UDEF, then the closest user-defined place will be returned. In other words, *UDEF instructs the API to not consider cities or towns when finding the closest place. See the Special Note below.
(2) Place Type #2
INPUT; CHAR(5)
This parameter controls which types of places will be considered by the API when trying to determine the nearest place to return as the proximity reference. Valid values are the same as those specified above for Place Type #1.
(3) Place Type #3
INPUT; CHAR(5)
This parameter controls which types of places will be considered by the API when trying to determine the nearest place to return as the proximity reference. Valid values are the same as those specified above for Place Type #1.
(4) Latitude
INPUT; PACKED(9,6)
This parameter is the latitude, given in decimal degrees, of the point to which the proximity reference should be calculated.
(5) Longitude
INPUT; PACKED(9,6)
This parameter is the longitude, given in decimal degrees, of the point to which the proximity reference should be calculated.
(6) Proximity Reference #1
OUTPUT; CHAR(256)
This parameter is a data structure that contains the elements of the proximity reference, as well as the identifier of the referenced place. The identifier may be used to retrieve additional data regarding the referenced place. The information returned is described in the OMGETPRXE API documentation.
(7) Proximity Reference #2
OUTPUT; CHAR(256)
This parameter is a data structure that contains the elements of the proximity reference, as well as the identifier of the referenced place. The identifier may be used to retrieve additional data regarding the referenced place. The information returned is described in the OMGETPRXE API documentation.
(8) Proximity Reference #3
OUTPUT; CHAR(256)
This parameter is a data structure that contains the elements of the proximity reference, as well as the identifier of the referenced place. The identifier may be used to retrieve additional data regarding the referenced place. The information returned is described in the OMGETPRXE API documentation.
(9) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, proximity reference(s) resolved and returned |
| 1 | Failure, at least one proximity reference could not be resolved (see Special Note below) |
| 2 | Failure, place type #1 cannot be blank |
| 3 | Failure, invalid input parameter |
Special Note
If searching for a user-defined place (type equals ttttt or *UDEF) and a failure status of 1 is returned, then the error occurred because no reference was found within a 'reasonable' distance (approximately 20 miles). The likelihood of encountering this error is higher when searching for user-defined places.