Get Vehicle Position History - OMGETPHS
Get Vehicle Position History (OMGETPHS) RI
Required Parameter Group:
| 1 | Function Code | Input | Char(1) |
| 2 | Vehicle Identifier | Input | Char(10) |
| 3 | Position Time | Input | Packed(13,0) |
| 4 | Position Report Data Structure | Output | Char(55) |
| 5 | Return Status | Output | Char(1) |
API Overview:
The Get Vehicle Position History API (OMGETPHS) returns a historical position report for a given vehicle. The returned position report is determined by the values of the input parameters that are passed to the API. The full position report, including the latitude and longitude coordinates and all of the associated information, is returned to the calling application.
Required Parameter Group Details:
(1) Function Code
INPUT; CHAR(1)
This parameter is a function code that instructs the API what action to perform. Valid values are:
| 1 | Return the vehicle's most recent position report. (Ignore the Position Time parameter.) |
| 2 | Return the vehicle's position report that is closest to the indicated time. |
| 3 | Return the vehicle's position report that is equal to, or earlier than, the indicated time. |
| 4 | Return the vehicle's position report that is equal to, or later than, the indicated time. |
| 5 | Return the vehicle's next earlier position report (assumes that the file cursor has been set by a previous call) |
| 6 | Return the vehicle's next later position report (assumes that the file cursor has been set by a previous call) |
| 9 | Remove program from memory and return control to the calling application |
(2) Vehicle Identifier
INPUT; CHAR(10)
This parameter indicates the vehicle for which a position report will be retrieved.
(3) Position Time
INPUT; PACKED(13,0)
This parameter contains a position time in GMT seconds that is used to retrieve a specific position report for the specified vehicle. This parameter is interpreted differently depending on the Function Code parameter.
(4) Position Report Data Structure
OUTPUT; CHAR(55)
This parameter is a fixed format data structure that returns elements of the position report. An external data structure named OCDPHS has been provided to allow easy integration to calling applications. See the shaded table below for the data structure format.
| 1-7 | Position Time(GMT secs) | Packed(13,0) |
| 8-14 | Position Report Arrival Time(GMT secs) | Packed(13,0) |
| 15-15 | Trip Status (I=in, O=out, U=unknown) | Char(1) |
| 16-16 | Ignition Status | Char(1) |
| 17-18 | Macro Number of Associated Message | Packed(3,0) |
| 19-20 | Macro Version Number of Associated Message | Packed(3,0) |
| 21-25 | GMH of Associated Message | Packed(9,0) |
| 26-29 | Next Stop Place Identifier | Packed(7,0) |
| 30-36 | Next Stop Appointment Time(GMT secs) | Packed(13,0) |
| 37-40 | Last Stop Place Identifier | Packed(7,0) |
| 41-47 | Last Stop Appointment Time(GMT secs) | Packed(13,0) |
| 48-51 | Latitude(total signed secs) | Packed(7,0) |
| 52-55 | Longitude(total signed secs) | Packed(7,0) |
(5) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, position report returned |
| 1 | Failure, no position history found for indicated parameters |
| 2 | Failure, invalid function code specified |
| 3 | Failure, invalid vehicle identifier specified |
| 4 | Failure, invalid position time specified |
| 5 | Failure, begin or end of file reached on get next operation |
| A | Failure, API failed when called remotely |