Skip to main content
Omnitracs Knowledge Base

Get Vehicle Proximity Reference - OMVEHPRX

Get Vehicle Proximity Reference (OMVEHPRX)


Required Parameter Group:

1 Vehicle Identifier Input Char(10)
2 Global Message Handle Input Packed(9,0)
3 Position Time Input Packed(13,0)
4 Place Type Input Char(5)
5 Proximity Reference Output Char(256)
6 Return Status Output Char(1)

API Overview:
The Get Vehicle Proximity Reference API (OMVEHPRX) returns a proximity reference for a given vehicle. The returned proximity reference may be based on a) the vehicle's current position; or b) a past position of the vehicle as indicated by a given time; or c) a past position of the vehicle as indicated by a given GMH.
In any case, the function also accepts an input parameter that will limit what type of proximity reference is returned. This type may be *AUTO, CITY, TOWN, or one of many user-defined place types. If *AUTO is specified, the system will automatically calculate the type of reference to be returned based on the context of the vehicle's position and the preferences of the user requesting the proximity reference.

The distance and direction of the nearest place is returned to the calling application along with the associated name, state, postal code, and ID of that place. The return status is set to indicate if the vehicle is 'at' the proximity reference.

Required Parameter Group Details:
(1) Vehicle Identifier
This parameter indicates the vehicle for which a proximity reference will be calculated. If the next two parameters are not specified (equal to 0), then the proximity reference will be calculated using this vehicle's current position.

(2) Global Message Handle
This parameter directs the function to calculate a proximity reference based on the vehicle's position that is associated with this message (i.e. where was the vehicle when it sent or received the indicated message.) If a position history record associated with the specified GMH is not found in the position history database, then the position history record that is equal-to (or prior-to) the 'received time' of the indicated message will be retrieved. If this parameter is specified, then the following parameter will be ignored, regardless of its value.

(3) Position Time
This parameter instructs the API to calculate a proximity reference based on the vehicle's position that is closest to the indicated time (i.e. where was the vehicle at the indicated time, or just prior to the indicated time.)

(4) Place Type
This parameter controls which types of places will be considered by the function when trying to determine the nearest place to return as the proximity reference. Valid values are:

*AUTO Return a proximity reference of a type based on the context of the position report and the user's preferences
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

(5) Proximity Reference
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-101 Proximity Time (in GMT seconds) Packed(13,0)
102-256 Reserved Char(155)

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

0 Failure, proximity reference cannot be resolved
1 Success, proximity reference resolved; not "at" indicated place
2 Success, proximity reference resolved; "at" indicated place
A Failure, API failed when called remotely
  • Was this article helpful?