Skip to main content
Omnitracs Knowledge Base

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:
  • Allow Daylight Savings
  • Customer Location Attribute
  • Unloading Location Attribute
  • Loading Location Attribute
  • Trailer Drop Location Attribute
  • Intermodal Point Attribute
  • User Defined Attribute #1 through #5
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).
  • Was this article helpful?