Get QTRACS Place Information - OMGETPLC
Get QTRACS Place Information (OMGETPLC) RI
Required Parameter Group:
| 1 | Place Identifier | Input | Packed(7,0) |
| 2 | Place Alias | Input | Char(10) |
| 3 | Place Name | Input | Char(25) |
| 4 | Place State | Input | Char(2) |
| 5 | Place Country | Input | Char(2) |
| 6 | Format Name | Input | Char(6) |
| 7 | Return Status | Output | Char(1) |
| 8 | Return Block | Output | Char(256) |
Optional Parameter Group:
| 9 | Place Key | Input | Char(6) |
| 10 | Place Type | Input | Char(5) |
API Overview:
The Get QTRACS Place Information API (OMGETPLC) is used to retrieve information about an existing QTRACS place. This API allows place information to be retrieved in several ways. Place information may be retrieved by explicitly specifying the place to be returned (either by specifying the Place Identifier, the Place Alias, or the Place Name along with the Country and State Codes). Specifically, it will return the contents of the place record(s) from the Place and ETA Databases. Alternately, this API allows an external application to 'play through' all defined places by place type. By specifying *FIRST or *NEXT along with a place type, the API can be used to return the entire place database in ascending place type/place name order.
This API will be useful for external applications when:
- partial place data is returned from proximity APIs such as OMGETPRX or OMVEHPRX. If the application needs additional place-related information, it can call this API using the place identifier.
- the external application needs to cross reference the QTRACS Place Database from an entry in some other location database, it can use the customer alias (cross-reference) key to retrieve the associated record. (This, of course is only available if the user has properly maintained the alias field.)
- the external application needs to retrieve a QTRACS place by name (because the QTRACS place identifier or alias is unknown), it can call this API using the country/state/name key.
Required Parameter Group Details:
(1) Place Identifier
INPUT; PACKED(7,0)
This parameter indicates the QTRACS place for which data will be retrieved. If specified, it must contain the unique identifier for the place. It is the first of three methods that may be used to specify the desired place.
(2) Place Alias
INPUT; CHAR(10)
This parameter indicates the QTRACS place for which data will be retrieved. If specified, it must contain the customer alias for the place. It is the second of three methods that may be used to specify the desired place. The customer alias is not necessarily unique. If the user defines more than one place with the same alias, then this API will return the first place record that matches the given alias.
(3) Place Name
INPUT; CHAR(25)
This parameter indicates the QTRACS place for which data will be retrieved. If specified, then the Place State and Place Country parameters must also be specified. Together, these three fields must contain the unique name/state/country for the desired place.
(4) Place State
INPUT; CHAR(2)
This parameter indicates the QTRACS place for which data will be retrieved. If specified, then the Place Name and Place Country parameters must also be specified. Together, these three fields must contain the unique name/state/country for the desired place.
(5) Place Country
INPUT; CHAR(2)
This parameter indicates the QTRACS place for which data will be retrieved. If specified, then the Place Name and Place State parameters must also be specified. Together, these three fields must contain the unique name/state/country for the desired place.
Format Name
INPUT; CHAR(6)
The format of the information to be returned. Valid values are:
| PLC000 | Common place information |
| PLC010 | Address information |
| PLC020 | Miscellaneous information |
| PLC030 | Place type and attribute information |
| PLC040 | Place counts |
| PLC050 | Milemaker information |
| PLC060 | Related place ETA information |
Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, place found and information block returned |
| 1 | Failure, place not found |
| 2 | Failure, invalid format name specified |
| 3 | Failure, invalid place key specified |
| 4 | Failure, invalid place type specified |
| 5 | Failure, invalid use of input parameters |
| A | Failure, API failed when called remotely |
Return Block
OUTPUT; CHAR(256)
Variable format data structure that returns information to the calling program based on the 'format name' parameter. If the 'return status' parameter is not '0', the contents of this return block are not reliable.
The supported data formats are shown in the shaded tables below.
PLC000 Data Format (Common place information)
| 1-4 | Place Identifier | Packed(7,0) |
| 5-29 | Place Name | Char(25) |
| 30-34 | Place Type | Char(5) |
| 35-38 | Latitude (seconds) | Packed(7,0) |
| 39-42 | Longitude (seconds) | Packed(7,0) |
| 43-45 | Place Radius (miles or kilometers) | Packed(5,1) |
| 46-50 | Latitude (degrees) (added v7.0) | Packed(9,6) |
| 51-55 | Longitude (degrees) (added v7.0) | Packed(9,6) |
PLC010 Data Format (Address information)
| 1-25 | Place Name | Char(25) |
| 26-50 | Address Line 1 | Char(25) |
| 51-75 | Address Line 2 | Char(25) |
| 76-100 | City Name | Char(25) |
| 101-102 | State Abbreviation | Char(2) |
| 103-104 | Country Abbreviation | Char(2) |
| 105-113 | Postal Code | Char(9) |
| 114-119 | Phone Number | Packed(11,0) |
PLC020 Data Format (Miscellaneous information)
| 1-9 | SPLC Code | Char(9) |
| 10-12 | Time Zone Code | Char(3) |
| 13-13 | Allow Daylight Savings (Y/N) | Char(1) |
| 14-23 | Alias Cross Reference to Customer Files | Char(10) |
| 24-28 | Original Source of Place | Char(5) |
| 29-38 | Last Change User | Char(10) |
| 39-45 | Last Change Date/Time | Packed(13,0) |
PLC030 Data Format (Place type and attribute information)
| 1-5 | Place Type | Char(5) |
| 6-6 | Customer Location Attribute (Y/N) | Char(1) |
| 7-7 | Unloading Location Attribute (Y/N) | Char(1) |
| 8-8 | Loading Location Attribute (Y/N) | Char(1) |
| 9-9 | Trailer Drop Location Attribute (Y/N) | Char(1) |
| 10-10 | Intermodal Point Attribute (Y/N) | Char(1) |
| 11-11 | User Defined Attribute #1 (Y/N) | Char(1) |
| 12-12 | User Defined Attribute #2 (Y/N) | Char(1) |
| 13-13 | User Defined Attribute #3 (Y/N) | Char(1) |
| 14-14 | User Defined Attribute #4 (Y/N) | Char(1) |
| 15-15 | User Defined Attribute #5 (Y/N) | Char(1) |
PLC040 Data Format (Place counts)
| 1-1 | Refine Coordinates (Y/N) | Char(1) |
| 2-7 | Total Events at Place | Packed(11,0) |
| 8-13 | QASPAR Events at Place | Packed(11,0) |
| 14-19 | GPS Events at Place | Packed(11,0) |
| 20-25 | ORBCOM Events at Place | Packed(11,0) |
| 26-31 | Int GPS Events at Place | Packed(11,0) |
PLC050 Data Format (Milemaker information)
| 1-25 | Milemaker Name | Char(25) |
| 26-50 | Milemaker County | Char(25) |
| 51-59 | Milemaker SPLC Code | Char(9) |
PLC060 Data Format (Related place ETA information)
| 1-3 | Peak Traffic Base AM Time(HHMM) | Packed(5,0) |
| 4-5 | Peak Traffic Duration AM | Packed(3,0) |
| 6-8 | Peak Traffic Base PM Time(HHMM) | Packed(5,0) |
| 9-10 | Peak Traffic Duration PM | Packed(3,0) |
| 11-12 | Local Distance(mls or kms) | Packed(3,0) |
| 13-14 | Local Average Speed: Traffic(mls or kms) | Packed(3,0) |
| 15-16 | Local Average Speed: Non-Traffic(mls or kms) | Packed(3,0) |
| 17-18 | Average Wait Time to Dock | Packed(3,0) |
| 19-20 | Average Wait Time to Depart | Packed(3,0) |
| 21-22 | Average Detention Time to Dock | Packed(3,0) |
| 23-24 | Average Detention Time to Depart | Packed(3,0) |
Optional Parameter Group Details:
Place Key
INPUT; CHAR(6)
This parameter instructs the API which place record to return. If specified, then the Place Type parameter must also be specified. Together, these two fields make up the criteria to 'play through' the place database. Valid values are:
| *FIRST | Returns the first place record (of the place type specified) from the Place Database |
| *NEXT | Returns the next place (of the place type specified) from the Place Database (assuming that the file cursor has been set from a previous call which specified *FIRST and a place type) |
Note: This parameter must be blank if you are specifying a place using the Place Identifier, Place Alias, or Place Name parameters for this API.
Place Type
INPUT; CHAR(5)
This parameter instructs the API which place type record to return. If specified, then the Place Key parameter must also be specified. Together, these two fields make up the criteria to 'play through' the place database. Valid values are:
| *ALL | Returns a place regardless of its type |
| *CUST | Returns a place of a custom type (not CITY or TOWN) |
| Place Type | Returns a place of this specific place type |
Note: This parameter must be blank if you are specifying a place using the Place Identifier, Place Alias, or Place Name parameters for this API.