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