Get Vehicle Proximity Reference - OMVEHPRX
Get Vehicle Proximity Reference (OMVEHPRX)
RI
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
INPUT; CHAR(10)
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
INPUT; PACKED(9,0)
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
INPUT; PACKED(13,0)
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
INPUT; CHAR(5)
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
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-101 | Proximity Time (in GMT seconds) | Packed(13,0) |
| 102-256 | Reserved | Char(155) |
(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 reference resolved; not "at" indicated place |
| 2 | Success, proximity reference resolved; "at" indicated place |
| A | Failure, API failed when called remotely |