Skip to main content
Omnitracs Knowledge Base

Get Proximity Reference Enhanced - OMGETPRXE (new for v7.0)

Get Proximity Reference Enhanced (OMGETPRXE) (new for v7.0)

Required Parameter Group:

1 Place Type Input Char(5)
2 Latitude Input Packed(9,6)
3 Longitude Input Packed(9,6)
4 Place Identifier to Exclude Input Packed(7,0)
5 Proximity Reference Output Char(256)
6 Return Status Output Char(1)

API Overview:
The Get Proximity Reference Enhanced API (OMGETPRXE) returns a proximity reference for a given latitude/longitude pair. The returned proximity reference contains information regarding the nearest QTRACS place . A place is a point on the earth that has been pre-defined to 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 many user-defined place types. The OMGETPRXE function may be passed a place type which will limit the proximity search to those places of the specified type. In addition, the function will also accept a place identifier that will not be returned in the search.

Required Parameter Group Details:
(1) Place Type
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
*QUIT Remove program from memory and return control to calling application

(2) 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.

(3) Longitude
INPUT; PACKED(9,6)
This parameter is the longitude, given in decimal degress, of the point to which the proximity reference should be calculated.

(4) Place Identifier to Exclude
INPUT; PACKED(7,0)
This parameter contains the place identifier of a place that should be excluded from the proximity search. This parameter is useful when passing a latitude/longitude to the function that is known to be a defined place. By passing the exclude place identifier, the API will return the place closest to it, but not that place itself.

(5) Proximity Reference
OUTPUT; CHAR(256)
This parameter is a fixed format 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 following table.

1-25 Place Name (upper case) Char(25)
26-50 Place City (mixed case) Char(25)
51-52 Place State Char(2)
53-61 Place Postal Code Char(9)
62-66 Distance to Place Zoned(5,1)
67-69 Distance Units (displayable text) Char(3)
70-72 Direction to Place (displayable text) Char(3)
73-77 Place Type Char(5)
78-84 Place Identifier Zoned(7,0)
85-94 Place Alias Char(10)
95-256 Reserved Char(162)

(6) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

0 Failure, proximity reference cannot be resolved
1 Success, proximity found
  • Was this article helpful?