Skip to main content
Omnitracs Knowledge Base

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
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
This parameter indicates the vehicle for which a position report will be retrieved.

(3) Position Time
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
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
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
  • Was this article helpful?