Skip to main content
Omnitracs Knowledge Base

Get Places Near Request - OMPRXPLC

Get Places Near Request (OMPRXPLC)

Required Parameter Group:

1 Latitude Input Packed(7,0)
2 Longitude Input Packed(7,0)
3 Place Type Filter #1 Input Char(5)
4 Place Attribute Filter #1 Input Char(10)
5 Place Type Filter #2 Input Char(5)
6 Place Attribute Filter #2 Input Char(10)
7 Place Type Filter #3 Input Char(5)
8 Place Attribute Filter #3 Input Char(10)
9 Place Type Filter #4 Input Char(5)
10 Place Attribute Filter #4 Input Char(10)
11 Place Type Filter #5 Input Char(5)
12 Place Attribute Filter #5 Input Char(10)
13 Distance Limit Input Packed(3,0)
14 Number of Finds Limit Input Packed(3,0)
15 Direction to Look Input Char(4)
16 Default Initial View Input Char(1)
17 Allow Selection from List Input Char(1)
18 Return Place Identifier Output Packed(7,0)
19 Return F-Key Pressed Output Char(2)
20 Return Status Output Char(1)

API Overview:
The Get Places Near Request API (OMPRXPLC) presents a display to the user that lists the results of a 'places near' proximity request. The results that are shown are a list of places that are 'close to' some specified reference point. This program will select places to be displayed to the user based on the input parameters received. This program will allow the user to scroll through the list of close places in 'closest first' or alphabetic order.

In addition to viewing the list of 'places near', this API allows the user to execute several record-level options. You may display the detail about a selected place, or if allowed, you may select a place and return its identifier to the calling application.

The parameter list that drives this API is obviously quite lengthy and could prove cumbersome depending on how this API is called. Therefore, another API exists that serves as a front end to this API that will present a display to the user and prompt for the required parameters. If this is desirable for your application, see the OMPRXQRY API for details.

Required Parameter Group Details:
(1) Latitude
INPUT; PACKED(7,0)
This parameter is the latitude portion of the reference point coordinate pair. This parameter must be given in signed seconds (not DDMMSS). This coordinate pair defines the geographic location from which the proximity search will begin.

(2) Longitude
INPUT; PACKED(7,0)
This parameter is the longitude portion of the reference point coordinate pair. This parameter must be given in signed seconds (not DDMMSS).

(3) Place Type Filter #1
INPUT; CHAR(5)
This parameter allows the user to filter the list of close places by selecting specific place types. Up to five place types may be specified; if none are specified, then all types are selected.

(4) Place Attribute Filter #1
INPUT; CHAR(10)
This parameter allows the user to filter the list of close places by selecting specific place types. Up to five place types may be specified; if none are specified, then all types are selected.

This parameter allows the user to further refine the filtering criteria by specifying attributes for one or more of the place types. Each one of these Place Attribute Filter parameters may only be specified if, and only if, its corresponding place type was specified. If specified, these parameters must be formatted as an array of up to 10 place type attributes (ie. 'YYNYNNYNNN'). This 'attribute mask' will be used to filter the list of close places that are displayed to the user. The 10 Y/N flags correspond to the following list of attributes:

1. Company Location
2. Unloading Location
3. Loading Location
4. Trailer Drop
5. Intermodal Point
6. User Defined Attribute #1
7. User Defined Attribute #2
8. User Defined Attribute #3
9. User Defined Attribute #4
10. User Defined Attribute #5

(5) Place Type Filter #2
INPUT; CHAR(5)
Same as Place Type Filter #1.

(6) Place Attribute Filter #2
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(7) Place Type Filter #3
INPUT; CHAR(5)
Same as Place Type Filter #1.

(8) Place Attribute Filter #3
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(9) Place Type Filter #4
INPUT; CHAR(5)
Same as Place Type Filter #1.

(10) Place Attribute Filter #4
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(11) Place Type Filter #5
INPUT; CHAR(5)
Same as Place Type Filter #1.

(12) Place Attribute Filter #5
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(13) 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.

(14) Number of Finds Limit
INPUT; PACKED(3,0)
This parameter, which must be between 1 and 999, limits the search to a maximum number of places.

(15) 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

(16) Default Initial View
INPUT; CHAR(1)
This parameter controls the sort of the places near display. Valid values are:

C Present in 'closest first' order
A Present in alphabetic order by place name

(17) Allow Selection from List
INPUT; PACKED(3,0)
This parameter controls the ability of the user to enter option 1 (=Select) against one of the places in the list. Valid values are:

Y Allow the user to select a place from the list
N Do not allow the user to select a place from the list

(18) Return Place Identifier
OUTPUT; PACKED(7,0)
This parameter returns the place identifier if the user selected one of the displayed places with option 1 (=Select). Otherwise, this field is set to zero.

(19) Return F-Key Pressed
OUTPUT; CHAR(2)
This parameter indicates the function key pressed by the user that exited from the screen. It is set to '03' if F3 was pressed or '12' if F12 was pressed. Otherwise, this field is set to blanks.

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

0 Success, proximity search executed and one or more places were found
1 Success, proximity search executed but no places were found
2 Failure, error in one the passed parameters
3 Failure, undefined fatal error occurred

Screenshot
Calling OMPRXPLC will present the following display.
api_2.4.22_screenshot.png

  • Was this article helpful?