Add a QTRACS Place Enhanced - OMADDPLCE (new for v7.0)
Add a QTRACS Place Enhanced (OMADDPLCE) (new for v7.0)
Required Parameter Group:
1 |
Format Name |
Input |
Char(6) |
2 |
Place Data Structure |
Input |
Char(512) |
3 |
Place Identifier |
Output |
Packed(7,0) |
4 |
Return Status |
Output |
Char(1) |
5 |
Reason Code |
Output |
Char(4) |
API Overview:
The Add a QTRACS Place Enhanced API (OMADDPLCE) is used to add a place to the QTRACS Place database. It is similar to the API OMADDPLC but OMADDPLCE has been modified to support enhanced positioning. Upon successful validation, the API will update the place file and return the newly associated 'place id' to the calling application program. This API provides a reliable and easy to use mechanism for external applications to add places to the QTRACS database.
Required Parameter Group Details:
(1) Format Name
INPUT; CHAR(6)
The format of the information being given. Valid values are:
PLC010 |
Place record with no ETA data |
PLC020 |
Place record with ETA data included |
(2) Place Data Structure
INPUT; CHAR(512)
This parameter is a fixed format data structure that contains place information used to fill a QTRACS place record.
PLC010 Data Format (Place record with no ETA data)
1-5 |
Latitude (decimal degrees) |
Packed(9,6) |
6-10 |
Longitude (decimal degrees) |
Packed(9,6) |
11-15 |
Place Type |
Char(5) |
16-40 |
Place Name |
Char(25) |
41-65 |
Address Line #1 |
Char(25) |
66-90 |
Address Line #2 |
Char(25) |
91-115 |
City Name (mixed case) |
Char(25) |
116-117 |
State/Province Abbreviation |
Char(2) |
118-119 |
Country Abbreviation |
Char(2) |
120-128 |
Postal Code |
Char(9) |
129-137 |
SPL Code |
Char(9) |
138-140 |
Size (radius in mls/kms) |
Packed(5,1) |
141-146 |
Phone number |
Packed(11,0) |
147-149 |
Time Zone Code |
Char(3) |
150-150 |
Allow Daylight Savings (Y/N) |
Char(1) |
151-160 |
Alias, Cross Reference to Customer File |
Char(10) |
161-161 |
Customer Location Attribute (Y/N) |
Char(1) |
162-162 |
Unloading Location Attribute (Y/N) |
Char(1) |
163-163 |
Loading Location Attribute (Y/N) |
Char(1) |
164-164 |
Trailer Drop Location Attribute (Y/N) |
Char(1) |
165-165 |
Intermodal Point Attribute (Y/N) |
Char(1) |
166-166 |
User-Defined Attribute #1 |
Char(1) |
167-167 |
User-Defined Attribute #2 |
Char(1) |
168-168 |
User-Defined Attribute #3 |
Char(1) |
169-169 |
User-Defined Attribute #4 |
Char(1) |
170-170 |
User-Defined Attribute #5 |
Char(1) |
171-171 |
Refine Coordinates (Y/N) |
Char(1) |
173-196 |
Milemaker Name |
Char(25) |
197-221 |
Milemaker County |
Char(25) |
222-230 |
Milemaker SPL Code |
Char(9) |
PLC020 Data Format (Place record with ETA data included)
1-230 |
PLC010 Data Format (see above) |
* |
231-233 |
Peak Traffic Base AM Time (HHMM) |
Packed(5,0) |
234-235 |
Peak Traffic Duration AM (min) |
Packed(3,0) |
236-238 |
Peak Traffic Base PM Time (HHMM) |
Packed(5,0) |
239-240 |
Peak Traffic Duration PM (minutes) |
Packed(3,0) |
241-242 |
Local Distance (mls/kms) |
Packed(3,0) |
243-244 |
Local Average Speed in Traffic (MPH/KPH) |
Packed(3,0) |
245-246 |
Local Average Speed Non-Traffic (MPH/KPH) |
Packed(3,0) |
247-248 |
Average Wait Time to Dock (min) |
Packed(3,0) |
249-250 |
Average Wait Time to Depart (min) |
Packed(3,0) |
251-252 |
Average Detention Time to Dock (min) |
Packed(3,0) |
253-254 |
Average Detention Time to Depart (min) |
Packed(3,0) |
Update (Carrier Function)
This function updates a single Carrier record.
Note: Release 5.2 changes are highlighted in red.
XML Request
Definitions
- null fields are the fields that are either omitted or initialized to a special value - string "NULL".
- E.g., <Street>NULL<Street/> will be interpreted as a null field.
- Empty string fields are, e.g., <Street /> or <Street></Street>
The Update function takes the following request parameters:
Parameter | Type | Optional | Description |
---|---|---|---|
Name | String | Yes | Carrier name, required in both old and new. New carrier name must be at least 4 characters. |
Street | String | Yes | Street segment of Carrier address |
Street2 | String | Yes | Street segment of Carrier address - line 2 |
City | String | Yes | City segment of Carrier address |
State | String | Yes | State segment of Carrier address |
Postal | String | Yes | Postal code segment of Carrier address |
MiscInfo | String | Yes | Additional information. This can be used to match the corresponding company's office information field |
USDotNumber | String | Yes | Identifying number issued by DOT |
- oldCarrier record is found based on Name specified in oldCarrier and on NMCAccount derived from the user login credentials.
- Only oldCarrier/Name field is used. Any other oldCarrier fields are ignored.
- Name is a required filed in both oldCarrier and newCarrier. It may not be either an empty string or null.
- Name must be unique for a given customer. If this constraint is violated, SOAP fault "System.Web.Services.Protocols.SoapException: Record already exists." will result.
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <Update xmlns="http://www.omnitracs.com"> <oldCarrier> <Name>string</Name> <Street>string</Street> <Street2>string</Street2> <City>string</City> <State>string</State> <Postal>string</Postal> <MiscInfo>string</MiscInfo> <USDotNumber>string</USDotNumber> </oldCarrier> <newCarrier> <Name>string</Name> <Street>string</Street> <Street2>string</Street2> <City>string</City> <State>string</State> <Postal>string</Postal> <MiscInfo>string</MiscInfo> <USDotNumber>string</USDotNumber> </newCarrier> </Update> </soap:Body> </soap:Envelope>
XML Response
The return result indicates success or failure via SOAP exceptions.
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <UpdateResponse xmlns="http://www.omnitracs.com" /> </soap:Body> </soap:Envelope>
Place Identifier
OUTPUT; PACKED(7,0)
This parameter contains the place identifier associated to the newly created place record.
Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
0 | Success, place record has been written |
1 | Success, place and ETA record have been written |
2 | Failure, place data structure given does not correspond to one of the above types |
3 | Failure, invalid value in place data structure |
Reason Code
OUTPUT; CHAR(4)
This parameter contains a reason code when the return status parameter is equal to '3'. Possible values returned include;
0001 | Invalid data block requested (other than "PLC010" or "PLC020") |
0002 | Place name, city name, state, country, postal code, or place type was left blank. |
0003 | Invalid country or state entered. |
0004 | Radius given is out of valid range (0-50) |
0005 | Place Type is invalid. |
0006 | Time Zone is invalid. |
0007 | Yes/No flag is not set to "Y" or "N" for one of the following:
|
0008 | AM Peak Traffic Base Time invalid |
0009 | AM Peak Traffic Duration is out of valid range (0-240) |
0010 | PM Peak Traffic Base Time invalid |
0011 | PM Peak Traffic Duration is out of valid range (0-240) |
0012 | Local Distance is out of valid range (0-999) |
0013 | Local Average Traffic Speed is out of valid range (0-999) |
0014 | Local Average Non-Traffic Speed is out of valid range (0-999) |
0015 | Average Wait to Dock is out of valid range (0-999) |
0016 | Average Wait to Depart is out of valid range (0-999) |
0017 | Average Detention Time to Dock is out of valid range (0-999) |
0018 | Average Detention Time to Depart is out of valid range (0-999) |
0019 | One of the following is true: o Latitude/Longitude is invalid o Place denoted by latitude/longitude already exists o Place denoted by latitude/longitude overlaps another defined place. |
0020 | Place denoted by country/state/name is not unique (already exists). |