Skip to main content
Omnitracs Knowledge Base

Get List of Vehicles Near a Given Place Enhanced - OMVEHLSTE (new for v7.0)

Get List of Vehicles Near a Given Place Enhanced (OMVEHLSTE) (new for v7.0)

Required Parameter Group:

1 Latitude Input Packed(9,6)
2 Longitude Input Packed(9,6)
3 Distance Limit Input Packed(5,1)
4 Number of Finds Limit Input Packed(3,0)
5 Direction to Look Input Char(4)
6 Format Name Input Char(6)
7 Return Status Output Char(1)
8 Reason Code Output Char(4)
9 Number of Vehicles Found Output Packed(3,0)
10 Return Block Output Char(3000)

API Overview:
The Get List of Vehicles Near a Given Place Enhanced API (OMVEHLSTE) returns a variable length list of vehicles (in closest first order) that are near a given latitude and longitude. The returned list will be dependent on the input parameters received: a) the distance limit; b) the number of finds limit; and c) the direction to look.
The distance and direction from the given latitude and longitude are returned to the calling application along with the last known location place, state and timestamp. Also returned is the distance and direction from the last known location. The return status is set to indicate if any vehicles have been found.

Required Parameter Group Details:
(1) Latitude
INPUT; PACKED(9,6)
This parameter is the latitude portion of the reference point coordinate pair. This parameter must be given in decimal degrees. This coordinate pair defines the geographic location from which the proximity search will begin.

(2) Longitude
INPUT; PACKED(9,6)
This parameter is the longitude portion of the reference point coordinate pair. This parameter must be given in decimal degrees.

(3) Distance Limit
INPUT; PACKED(3,0)
This parameter limits the search to only those places that are within the specified radius. This value, which must be between 1 and 500, will be interpreted as either miles or kilometers depending on the system configuration.

(4) Number of Finds Limit
INPUT; PACKED(3,0)
This parameter limits the search to a maximum number of places. Valid limits vary depending on the value specified in the Format Name parameter.
The valid range for LST100 is 1 - 187. The valid range for LST200 is 1 - 53.

(5) Direction to Look
INPUT; CHAR(4)
This parameter limits the search by controlling which geographic direction the system will check for close places. Valid values are:

*ALL All directions E East NW Northwest
N North W West SE Southeast
S South NE Northeast SW Southwest

(6) Format Name
INPUT; CHAR(6)
The format of the information to be returned. Valid values are:

LST100 Vehicle distance and direction
LST200 Vehicle proximity - *AUTO style

(7) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

0 Success, Proximity search executed
1 Failure, Proximity search executed but may be inaccurate due to wide search limits
2 Failure, see reason code.

(8) Reason Code
OUTPUT; CHAR(4)
This parameter contains a reason code. Possible values returned include;

0000 One or more vehicles were found
0001 No vehicles were found
0002 Too many vehicles found*
0003 Invalid latitude specified
0004 Invalid longitude specified
0005 Invalid distance limit specified
0006 Invalid number of finds limit specified
0007 Invalid direction to look specified
0008 Invalid format name specified
  • Reason code 0002 will always be returned with return status 1. The proximity search did not fail but more than 1000 vehicles were found within the search limits given. Therefore, there is no guarantee that the closest vehicles have been found because more vehicles are within the circle of consideration than could be returned. For better accuracy, decrease the distance limit or limit the direction to look.
    (9) Number of Vehicles Found
    OUTPUT; PACKED(3,0)
    This parameter returns the total number of vehicles found within the requirements set by the input parameters.
    (10) Return Block
    OUTPUT; CHAR(3000)
    Variable format data structure that returns information to the calling program based on the 'format name' parameter. This parameter contains a list of repeating blocks of data. One block of data is returned for each vehicle that meets the selection criteria. The maximum number of vehicles returned varies depending on the format name parameter. If the maximum is not found, then the block is padded with blanks.
    The supported data formats are shown in the shaded tables below.
    LST100 Data Format (Vehicle distance and direction)
1-10 Vehicle Identifier Char(10)
11-13 Distance from Reference Point(mls or kms) Packed(5,1)
14-16 Direction from Reference Point Char(3)

LST200 Data Format (Vehicle proximity - *AUTO style)

1-10 Vehicle Identifier Char(10)
11-13 Distance from Reference Point(mls or kms) Packed(5,1)
14-16 Direction from Reference Point Char(3)
17-41 Last Known Location Place Name Char(25)
42-43 Last Known Location State Char(2)
44-50 Last Known Location Timestamp Packed(13,0)
51-53 Distance from Last Known Location(mls or kms) Packed(5,1)
54-56 Direction from Last Known Location Char(3)
  • Was this article helpful?