Work with Vehicle Position History - OMWWVPH
Work with Vehicle Position History (OMWWVPH)
Required Parameter Group:
| 1 | Vehicle Identifier | Input | Char(10) |
| 2 | Place Type | Input | Char(7) |
| 3 | Return Status | Output | Char(1) |
API Overview:
The Work with Vehicle Position History API (OMWWVPH) allows a user to view a vehicle's position history. It presents a user interface that allows specification of a vehicle, a proximity reference type, and optionally a place identifier to reference.
In addition to viewing position history, this API allows the user to perform place-related functions. A user may display a place, or display a list of close places relative to a position, or he may add a new place.
Required Parameter Group Details:
(1) Vehicle Identifier
INPUT; CHAR(10)
This parameter indicates which vehicle's position history will be displayed first. The user may change this after initial display.
(2) Place Type
INPUT; CHAR(7)
This parameter controls which types of places will be considered when calculating the proximity references for each position report. Valid values are:
| *AUTO | Show proximity references based on context of position report and user preferences |
| *TOWN | Show proximity references of type TOWN (unless a CITY is closest) |
| *CITY | Show proximity references of type CITY |
| ppppppp | Show proximity references to this place id only, where ppppppp is a valid place identifier |
(3) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success |
| 1 | Success, F3 pressed to exit |
| 2 | Success, F12 pressed to exit |
| 3 | Failure, user not defined in QTRACS |
Note
LR is not set on when this program returns control to the calling program. It will stay active in the calling application's PAG until the job ends or a RCLACTGRP is issued.
Screenshot
Calling OMWWVPH will present the following display.
Additional Information
Automatic Proximity References
In previous versions of QTRACS, proximity references were always calculated the same way regardless of the context of a particular vehicle position report.
That is, a small city reference and a big city reference were always used to describe the location of any vehicle, regardless of its context. A single proximity reference is calculated by the system and its type is dependent upon several factors including context of the vehicle and user preferences.
The 'context' of a vehicle, or rather the context of the position report for which a proximity reference is to be calculated is very important. Rather than always returning the same type of proximity reference, the system may, if instructed, automatically determine the type of reference to compute. That is, it must determine if the proximity string will reference the vehicle's next scheduled trip stop; or some user-defined place that is associated with the vehicle position report; or a company location; or the closest big city; or simply the closest small town. The system employs the following 5-step algorithm to calculate the proximity reference.
1) If the historical position report is bound to a return macro, check if the macro has been defined with an associated user-defined place type. If so, and the closest place of that type is within the user's 'preferred place reference limit' (miles), then that is the proximity reference type to use...
2) Else, if the historical position report was stored when the vehicle had a current 'next scheduled appointment' defined, check if the next stop appointment time is within the user's 'next stop reference limit' (minutes) of the position report time. If so, then that is the actual proximity reference location to use...
3) Else, if the historical position report is within the user's 'preferred place reference limit' (miles) of the closest 'company location', then that is the proximity reference type to use...
4) Else, if the historical position report is within the user's 'big city reference limit' of the closest big city, then that is the proximity reference type to use...
5) Otherwise, a proximity reference to a 'small city' will be calculated...
Some examples:
An unsolicited position report may resolve to a big city (4) or a small city (5) reference depending upon the user's big city reference limit.
A position report that is associated with a specific return macro message may resolve to a user-defined place type (1) reference. For instance, an 'arrived at shipper' return macro message may resolve to a *CUSTOMER SITE reference.
A position report received within a meaningful distance to a pre-defined scheduled next stop may resolve to the reference type indicated by the next stop (2).
User-Specified Proximity References
The system will, in most cases, default to the automatic proximity reference calculation described in the preceding section. This reference type may be overridden by the user at many places throughout the system. The theory is that the automatic reference will be preferable most of the time; however, there may be some scenario where the user wants to force a specific type of proximity reference to be calculated.
For example; the user may be viewing a vehicle's position history in the *AUTO mode, but due to unfamiliarity with the geographic location of the vehicle, the small cities and next stop references are not meaningful. If so, the user may override the *AUTO mode to the *CITY mode providing a look at the same positions with reference to big cities.
'At' a Proximity Reference
Normally, a proximity reference is displayed as 'X miles DDD of Someplace, ST' where DDD is the direction of the vehicle from the indicated place. In QTRACS Version 4, a new concept of being 'at' a place was introduced. If a vehicle is determined to be 'at' a place, the proximity reference will be formatted as 'at Someplace, ST' (i.e. the distance, units, and direction will be replaced by 'at'). This benefit of this feature is that a stationary vehicle will not 'wiggle' around because of trivial differences in its reported position. Instead, a vehicle will be correctly displayed as being 'at' a place up until the time that it actually departs.
Vehicles are considered to be 'at' a place if the coordinates on the position report fall within the radius of that place. The type of hardware (QASPAR, GPS, Differential GPS, etc.) that generated the position report is also considered since some types are more accurate than others.