alk.connect
Class PCMSJava

java.lang.Object
  extended byalk.connect.PCMSJava

public class PCMSJava
extends java.lang.Object

PCMSJava is a wrapper class for the C-style API supported by PC*Miler Connect v18.0 and higher. It allows a user to access PC*Miler's native routines through a Java interface. To access this functionality you must first have a licensed version PC*Miler Connect installed on your machine. Then import the package alk.connect. You may also need to import alk.connect.results if you plan to use any of the methods that require a results object as a parameter (i.e. SetCalcTypeEx). Finally, instantiate an instance of the PCMSJava class within your existing Java application and access its methods as you would any other Java class.

Note: You must have alk.jar included in your CLASSPATH in order to access its packages. Also make sure the location of the pcmsrv32 library is set in java.library.path before running your application. You can set this environment variable at execution time. (ex. java -Djava.library.path=[path] test)


Constructor Summary
PCMSJava()
           
 
Method Summary
 int About(java.lang.String which, java.lang.StringBuffer strBuf)
          Gets PC*Miler version information.
 int AddressToLatLong(short serverID, java.lang.String address, java.lang.StringBuffer strBuf)
          Finds corresponding latlong for given address.
 int AddStop(long tripID, java.lang.String stop)
          Adds stop to end of trip.
 int AFLinks(long tripID, boolean bFavor)
          Sets trip option so that selected links are respectively avoided and favored during route calculation (if true).
 int AFLoad(short serverID, java.lang.String filename)
          Loads current set of avoided/favored links for default region.
 int AFLoadForRegion(short serverID, java.lang.String filename, java.lang.String regionID)
          Loads current set of avoided/favored links for specified region.
 int AFSave(short serverID)
          Saves current set of avoided/favored links for default region to file
 int AFSaveForRegion(short serverID, java.lang.String regionID)
          Saves current set of avoided/favored links for specified region to file.
 long AirDistToRte(long tripID, java.lang.String location, int legNum)
          Calculates closest air distance between "location" and specified leg.
 long CalcDistance(short serverID, java.lang.String orig, java.lang.String dest)
          Calculates distance from orig to dest.
 long CalcDistance2(short serverID, java.lang.String orig, java.lang.String dest, int routeType)
          Calculates distance from orig to dest given routing type.
 long[] CalcDistance3(short serverID, java.lang.String orig, java.lang.String dest, int routeType)
          Calculates distance and minutes of travel from orig to dest given routing type.
 int CalcDistToRoute(long tripID, java.lang.String location)
          Calculates orthogonal distance to route from "location".
 long CalcTrip(long tripID, java.lang.String orig, java.lang.String dest)
          Calculates distance from orig to dest using trip settings.
 long Calculate(long tripID)
          Calculates trip distance through all stops using current trip settings.
 int ChangeWWDataSet(java.lang.String regionID)
          Sets default region to given regionID.
 int CheckPlaceName(short serverID, java.lang.String cityZip)
          Verifies that input has an exact match in the database.
 int CityToLatLong(short serverID, java.lang.String city, java.lang.StringBuffer strBuf)
          Finds corresponding latlong for given city.
 void ClearStops(long tripID)
          Clears trip of all stops.
 int CloseServer(short serverID)
          Clean up and dismiss PC*Miler server.
 void ConvertLLToPlace(long tripID, boolean bYesNo)
          Sets trip option to automatically convert latlongs to PC*MILER place names (true).
 void Defaults(long tripID)
          Reset all options to default values.
 int DeleteStop(long tripID, int idx)
          Deletes specified stop.
 void DeleteTrip(long tripID)
          Frees existing PC*MILER trip and resources associated with it.
 long GetBorderWaitHours(long tripID)
          Gets time spent waiting at borders (in minutes).
 long GetBreakHours(long tripID)
          Gets the interval designated on-duty and between breaks (in minutes).
 long GetBreakWaitHours(long tripID)
          Gets length of breaks (in minutes).
 int GetCalcType(long tripID)
          Gets criteria used to calculate distance for given trip.
 int GetCalcTypeEx(long tripID, CalcTypeEx calcTypeEx)
          Gets extended criteria used to calculate distance for given trip.
 int GetCost(long tripID)
          Gets cost per mile (in cents).
 int GetDebug()
          Gets debugging level for this PC*Miler Server.
 int GetDefaultRegion(java.lang.StringBuffer str)
          Gets default region.
 long GetDuration(long tripID)
          Gets duration of trip in minutes.
 int GetError()
          Gets last error code associated with server.
 int GetErrorString(int errorCode, java.lang.StringBuffer str)
          Gets specific error string for given error code.
 int GetExactLevel(short serverID)
          Gets current threshold at which an address is considered a match.
 int GetFmtMatch(long tripID, int idx, java.lang.StringBuffer strBuf, int zipLen, int cityLen, int countyLen)
          Gets specific place name from last Lookup in a custom format.
 int GetFmtMatch2(long tripID, int idx, java.lang.StringBuffer addr, java.lang.StringBuffer city, java.lang.StringBuffer state, java.lang.StringBuffer zip, java.lang.StringBuffer county)
          Gets specific place name from last Lookup, parsed into separate fields for address, city, state, zip and county.
 long GetHTMLRpt(long tripID, int rptNum, java.lang.StringBuffer strBuf)
          Copies HTML-formatted report into user-supplied StringBuffer.
 int GetLegInfo(long tripID, int legNum, LegInfoType pLegInfo)
          Gets information about leg miles, total miles, leg cost, total cost, leg hours, and total for specific leg of trip.
 int GetLocAtMiles(long tripID, long miles, java.lang.StringBuffer strBuf)
          Gets nearest location on the route after travelling 'miles' from the origin.
 int GetLocAtMinutes(long tripID, long minutes, java.lang.StringBuffer strBuf)
          Gets nearest location on the route after travelling 'minutes' from the origin.
 int GetLocRadItem(long tripID, int index, java.lang.StringBuffer strBuf)
          Gets an item found through a LocRadLookup query.
 int GetMatch(long tripID, int idx, java.lang.StringBuffer strBuf)
          Gets specific place name from last Lookup.
 int GetNumSegments(long tripID)
          Gets number of segments in detailed report.
 long GetOptions(long tripID)
          Gets trip options as single set of flags.
 int GetRegionName(short serverID, int idx, java.lang.StringBuffer strBuf)
          Gets full name for idx-th region.
 int GetRpt(long tripID, int rptNum, java.lang.StringBuffer strBuf)
          Copies entire report text into user-supplied StringBuffer.
 int GetRptLine(long tripID, int rptNum, int lineNum, java.lang.StringBuffer strBuf)
          Copies line from specified report into user-supplied StringBuffer.
 int GetSegment(long tripID, int segNum, SegmentStruct pSegment)
          Gets segment by 0-based index.
 int GetStop(long tripID, int idx, java.lang.StringBuffer strBuf)
          Gets place name for specific stop.
 int GetStopType(long tripID, int idx)
          Gets stop type for given stop.
 long GetToll(long tripID)
          Gets total toll amount for trip in cents.
 long GetTollBreakdown(long tripID, int discProgram)
          Gets tolls owed when using specific discount program.
 int GetTollDiscountName(short serverID, int idx, java.lang.StringBuffer strBuf)
          Gets specific toll discount program name by index.
 int IsValid(short serverID)
          Check that server is valid.
 int LatLongAtMiles(long tripID, long miles, java.lang.StringBuffer strBuf, boolean bUseShpPts)
          Get latlong on the route after travelling 'miles' from the origin.
 int LatLongAtMinutes(long tripID, long minutes, java.lang.StringBuffer strBuf, boolean bUseShpPts)
          Get latlong on the route after travelling 'minutes' from the origin.
 double[] LatLongsEnRoute(long tripID, long numPairs, boolean bUseShpPts)
          Gets lat/long pairs along route.
 int LatLongToAddress(short serverID, java.lang.String latlong, java.lang.StringBuffer strBuf)
          Finds corresonding address for given latlong.
 int LatLongToCity(short serverID, java.lang.String latlong, java.lang.StringBuffer strBuf)
          Finds corresonding city for given latlong.
 int LocRadLookup(long tripID, java.lang.String city, int radius, boolean bCities, boolean bPostalCodes, boolean bCustomPlaces, boolean bPOI, int POICategoryIndex)
          Looks up cities, postal codes, custom places, and/or POIs within a radius around a city/state or zip.
 int Lookup(long tripID, java.lang.String str, int easyMatch)
          Looks up zip or city/state name and returns number of matching places.
 long NewTrip(short serverID)
          Creates new PC*MILER trip.
 long NewTripWithRegion(short serverID, java.lang.String regionID)
          Creates a new PC*MILER trip for a specific region.
 long NumHTMLRptBytes(long tripID, int rptNum)
          Gets total length of HTML-formatted report.
 long NumLatLongsEnRoute(long tripID, boolean bUseShpPts)
          Gets total number of lat/long pairs in route.
 int NumLegs(long tripID)
          Gets number of legs in trip.
 int NumMatches(long tripID)
          Gets total number of matches found in last Lookup.
 int NumPOICategories(short serverID)
          Gets total number of POI categories in data.
 int NumRegions(short serverID)
          Gets number of available region names.
 long NumRptBytes(long tripID, int rptNum)
          Gets total length of report in bytes.
 int NumRptLines(long tripID, int rptNum)
          Gets number of lines in report.
 int NumStops(long tripID)
          Gets number of stops in trip.
 int NumTollDiscounts(short serverID)
          Gets number of toll discount programs (EZPass, FasTrak, etc) tracked by PC*Miler.
 short OpenServer(int hAppInst, int hWnd)
          Initializes new PC*Miler server.
 int Optimize(long tripID)
          Optimizes order of stops for given trip.
 int POICategoryName(short serverID, int index, java.lang.StringBuffer strBuf)
          Gets the name of a POI category.
 void SetAlphaOrder(long tripID, boolean bAlphaOrder)
          Sets trip option to sort state report in alphabetical (true) or in driving order (false).
 void SetBordersOpen(long tripID, boolean bOpen)
          Sets trip option to run routes with international borders open (true) or closed (false).
 void SetBorderWaitHours(long tripID, long mins)
          Sets time spent waiting at borders (in minutes).
 void SetBreakHours(long tripID, long mins)
          Sets the interval designated on-duty and between breaks (in minutes).
 void SetBreakWaitHours(long tripID, long mins)
          Sets length of breaks (in minutes).
 void SetCalcType(long tripID, int calcType)
          Sets criteria used to calculate distance for given trip.
 void SetCalcTypeEx(long tripID, CalcTypeEx calcTypeEx)
          Sets extended criteria used to calculate distance for given trip.
 void SetCost(long tripID, int cost)
          Sets cost per mile (in cents).
 void SetCustomMode(long tripID, boolean bOnOff)
          Sets trip option to route with custom mode on(true) or off(false).
 int SetDebug(int levl)
          Sets debugging level for this PC*Miler Server.
 int SetDefaultRegion(java.lang.String regionID)
          Sets default region to given regionID.
 void SetExactLevel(short serverID, int threshold)
          Sets threshold at which an address is considered a match.
 void SetHazOption(long tripID, int hazType)
          Sets Hazardous Routing options.
 void SetHubMode(long tripID, boolean bOnOff)
          Sets hub routing mode on (true) so that first stop becomes common origin for all subsequent stops, or off (false) to route through all stops.
 void SetKilometers(long tripID)
          Sets trip option to report all distances in kilometers.
 int SetLoaded(long tripID, int idx, boolean bLoaded)
          Sets stop flag to either loaded or empty.
 void SetMiles(long tripID)
          Sets trip option to report all distances in miles.
 void SetOldMode(long tripID, boolean bOnOff)
          Sets trip option to enable old-style (no comma) geocoding (if true).
 int SetOldModeForRegion(short serverID, java.lang.String regionID, boolean bOnOff)
          Sets server option to enable old-style (no comma) geocoding for an entire region.
 void SetOnRoad(long tripID, boolean bOnOff)
          Sets trip option determining whether a latlong should be geocoded to a road (true), or used as an exact position.
 void SetOptions(long tripID, long opts)
          Sets trip options from set of flags.
 void SetResequence(long tripID, boolean bChangeDest)
          Sets trip option so that when optimizing, reorder all but first stop (true), or all but the first and last stops (false).
 void SetRoadNameOnly(long tripID, boolean bOnOff)
          Sets trip option to match addresses on road names only (true), or only match addresses exactly(false).
 void SetShowFerryMiles(long tripID, boolean bOnOff)
          Sets trip option to include ferry miles in distance calculations (true) or ignore them (false).
 void SetTollMode(long tripID, int mode)
          Sets level of toll reporting for trip.
 void SetVehicleType(long tripID, boolean bOnOff)
          Sets trip option to calculate route with heavy vehicle on (true) or off(false)
 void TranslateAlias(long tripID, boolean bTranslate)
          Sets wheter aliases (custom places) should be translated to corresponding location or left as user-defined name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PCMSJava

public PCMSJava()
Method Detail

SetDebug

public int SetDebug(int levl)
Sets debugging level for this PC*Miler Server.

Parameters:
levl - debug level maps to following values:
0 = no debugging
1 = some debugging (currently not used)
2 = lots of message boxes about the state of the DLL.
Returns:
previous debug level.

GetDebug

public int GetDebug()
Gets debugging level for this PC*Miler Server. Refer to SetDebug for valid return values.

Returns:
current debug level.

OpenServer

public short OpenServer(int hAppInst,
                        int hWnd)
Initializes new PC*Miler server. Arguments are not currently used. Future versions will use arguments to find resources and define parent windows.

Parameters:
hAppInst - calling application's instance handle. (Use 0 for current version)
hWnd - parent window's window handle. (Use 0 for current version)
Returns:
unique 2-byte ID for this server connection.

CloseServer

public int CloseServer(short serverID)
Clean up and dismiss PC*Miler server.

Parameters:
serverID - unique server ID. Must be passed in to free resources.
Returns:
1 on success; 0 on error

IsValid

public int IsValid(short serverID)
Check that server is valid. I.e. was initialized; exists in global client list.

Parameters:
serverID - unique server ID
Returns:
1 on success; 0 on error

GetErrorString

public int GetErrorString(int errorCode,
                          java.lang.StringBuffer str)
Gets specific error string for given error code.

Parameters:
errorCode - error code returned by GetError()
str - user-supplied StringBuffer to hold error string
Returns:
number of characters copied into buffer on success; 0 if buffer was misallocated; -1 if string not found

GetError

public int GetError()
Gets last error code associated with server.

Returns:
last error that server encountered. See error codes in PCM_DEFS.H for more information

About

public int About(java.lang.String which,
                 java.lang.StringBuffer strBuf)
Gets PC*Miler version information.

Parameters:
which - designates which string to return. Can be one of following:
"ProductName"
"ProductVersion"
"LegalCopyright"
"LegalTrademarks"
strBuf - user-supplied StringBuffer to hold version information on success
Returns:
number of bytes written to strBuf on success, -1 on error, 0 if string not found.

ChangeWWDataSet

public int ChangeWWDataSet(java.lang.String regionID)
Sets default region to given regionID.

Parameters:
regionID - String can be one of following:
"AF" or "Africa"
"AS" or "Asia"
"EU" or "Europe"
"NA" or "North America"
"OC" or "Oceania"
"SA" or "South America"
Returns:
0 on success, -1 on error. (Fails if region is not installed)

SetDefaultRegion

public int SetDefaultRegion(java.lang.String regionID)
Sets default region to given regionID.

Parameters:
regionID - String can be one of following:
"AF" or "Africa"
"AS" or "Asia"
"EU" or "Europe"
"NA" or "North America"
"OC" or "Oceania"
"SA" or "South America"
Returns:
0 on success, -1 on error. (Fails if region is not installed)

GetDefaultRegion

public int GetDefaultRegion(java.lang.StringBuffer str)
Gets default region.

Parameters:
str - user-supplied StringBuffer to hold region information on success. Will contain one of following two-letter abbreviations:
"AF" for Africa
"AS" for Asia
"EU" for Europe
"NA" for North America
"OC" for Oceania
"SA" for South America
Returns:
0 on success, -1 on error.

CalcDistance

public long CalcDistance(short serverID,
                         java.lang.String orig,
                         java.lang.String dest)
Calculates distance from orig to dest.

Parameters:
serverID - unique server ID
orig - String specifiying origin. (ex. "08540", "Princeton, NJ", "Princeton, NJ; 1000 Herrontown Rd")
dest - String specifiying destination.
Returns:
distance in tenths of miles

CalcDistance2

public long CalcDistance2(short serverID,
                          java.lang.String orig,
                          java.lang.String dest,
                          int routeType)
Calculates distance from orig to dest given routing type.

Parameters:
serverID - unique server ID
orig - String specifiying the origin.
dest - String specifiying the destination.
routeType - int with one of following values:
-1 - Invalid 0 - Practical
1 - Shortest
2 - National Network
3 - Avoid Tolls
4 - Air Distance
5 - POV
6 - 53'
Returns:
distance in tenths of miles

CalcDistance3

public long[] CalcDistance3(short serverID,
                            java.lang.String orig,
                            java.lang.String dest,
                            int routeType)
Calculates distance and minutes of travel from orig to dest given routing type.

Parameters:
serverID - unique server ID
orig - String specifiying the origin.
dest - String specifiying the destination.
routeType - int specifying a routing type. Refer to CalcDistance2 for valid input values.
Returns:
array of longs with distance in tenths of miles as first element and minutes travelled as second.

CheckPlaceName

public int CheckPlaceName(short serverID,
                          java.lang.String cityZip)
Validates city name or zip code.

Parameters:
serverID - unique server ID
cityZip - String containing location information (ex. "08540", "Pri*, NJ");
Returns:
number of exact matches

CityToLatLong

public int CityToLatLong(short serverID,
                         java.lang.String city,
                         java.lang.StringBuffer strBuf)
Finds corresponding latlong for given city.

Parameters:
serverID - unique server ID
city - String containing city to be looked up
strBuf - user-supplied StringBuffer to hold latlong information on success
Returns:
number of bytes written to strBuf on success, -1 if city not found

LatLongToCity

public int LatLongToCity(short serverID,
                         java.lang.String latlong,
                         java.lang.StringBuffer strBuf)
Finds corresonding city for given latlong.

Parameters:
serverID - unique server ID
latlong - String containing latlong to be looked up
strBuf - user-supplied StringBuffer to hold city information on success
Returns:
number of bytes written to strBuf on success, -1 on error

AddressToLatLong

public int AddressToLatLong(short serverID,
                            java.lang.String address,
                            java.lang.StringBuffer strBuf)
Finds corresponding latlong for given address.

Parameters:
serverID - unique server ID
address - String containing address to be looked up
strBuf - user-supplied StringBuffer to hold latlong information on success
Returns:
number of bytes written to strBuf on success, -1 if address not found

LatLongToAddress

public int LatLongToAddress(short serverID,
                            java.lang.String latlong,
                            java.lang.StringBuffer strBuf)
Finds corresonding address for given latlong.

Parameters:
serverID - unique server ID
latlong - String containing latlong to be looked up
strBuf - user-supplied StringBuffer to hold address information on success
Returns:
number of bytes written to strBuf on success, -1 on error

NumRegions

public int NumRegions(short serverID)
Gets number of available region names.

Parameters:
serverID - unique server ID
Returns:
number of available region names

GetRegionName

public int GetRegionName(short serverID,
                         int idx,
                         java.lang.StringBuffer strBuf)
Gets full name for idx-th region.

Parameters:
serverID - unique server ID
idx - 0-based index into list of region names
strBuf - user-supplied StringBuffer to hold region name string on success
Returns:
0 on success; -1 on error

NewTrip

public long NewTrip(short serverID)
Creates new PC*MILER trip.

Parameters:
serverID - unique server ID
Returns:
unique trip identifier of type long

NewTripWithRegion

public long NewTripWithRegion(short serverID,
                              java.lang.String regionID)
Creates a new PC*MILER trip for a specific region.

Parameters:
serverID - unique server ID
regionID - String containing region identifier. Refer to GetDefaultRegion for possible values.
Returns:
unique trip identifier of type long

DeleteTrip

public void DeleteTrip(long tripID)
Frees existing PC*MILER trip and resources associated with it.

Parameters:
tripID - unique trip identifier

CalcTrip

public long CalcTrip(long tripID,
                     java.lang.String orig,
                     java.lang.String dest)
Calculates distance from orig to dest using trip settings.

Parameters:
tripID - unique trip identifier
orig - String specifiying the origin
dest - String specifiying the destination
Returns:
distance in tenths of miles

Calculate

public long Calculate(long tripID)
Calculates trip distance through all stops using current trip settings.

Parameters:
tripID - unique trip identifier
Returns:
distance in tenths of miles

Optimize

public int Optimize(long tripID)
Optimizes order of stops for given trip. (Involves computationally-intensive route calculation)

Parameters:
tripID - unique trip identifier
Returns:
1 on success; 0 if already optimized; -1 on error

GetDuration

public long GetDuration(long tripID)
Gets duration of trip in minutes.

Parameters:
tripID - unique trip identifier
Returns:
duration of trip in minutes

GetToll

public long GetToll(long tripID)
Gets total toll amount for trip in cents.

Parameters:
tripID - unique trip identifier return total amount owed for trip in cents

NumTollDiscounts

public int NumTollDiscounts(short serverID)
Gets number of toll discount programs (EZPass, FasTrak, etc) tracked by PC*Miler. Note: also includes cash, which is technically not a discount program.

Parameters:
serverID - unique server ID
Returns:
number of toll discount programs tracked by PC*Miler

GetTollDiscountName

public int GetTollDiscountName(short serverID,
                               int idx,
                               java.lang.StringBuffer strBuf)
Gets specific toll discount program name by index.

Parameters:
serverID - a unique server ID
idx - 0-based index into list of toll discount programs
strBuf - user-supplied StringBuffer to hold program name on success
Returns:
number of bytes written to strBuf or -1 on error

GetTollBreakdown

public long GetTollBreakdown(long tripID,
                             int discProgram)
Gets tolls owed when using specific discount program.

Parameters:
tripID - unique trip identifier
discProgram - 0-based index into list of toll discount program
Returns:
total amount owed in cents

AddStop

public int AddStop(long tripID,
                   java.lang.String stop)
Adds stop to end of trip.

Parameters:
tripID - unique trip identifier
stop - String containing location information (ex. "08540", "Princeton, NJ", "Princeton, NJ; 1000 Herrontown Rd")
Returns:
1 on success; -1 on error

DeleteStop

public int DeleteStop(long tripID,
                      int idx)
Deletes specified stop.

Parameters:
tripID - unique trip identifier
idx - 0-based index into trip list of stops
Returns:
1 on success; 0 on error

ClearStops

public void ClearStops(long tripID)
Clears trip of all stops.

Parameters:
tripID - unique trip identifier

GetStop

public int GetStop(long tripID,
                   int idx,
                   java.lang.StringBuffer strBuf)
Gets place name for specific stop.

Parameters:
tripID - unique trip identifier
idx - 0-based index into trip list of stops
strBuf - user-supplied StringBuffer to hold place name string on success
Returns:
number of bytes written to strBuf on success; -1 on error

NumStops

public int NumStops(long tripID)
Gets number of stops in trip.

Parameters:
tripID - unique trip identifier
Returns:
number of stops in trip

GetStopType

public int GetStopType(long tripID,
                       int idx)
Gets stop type for given stop.

Parameters:
tripID - unique trip identifier
idx - 0-based index into trip list of stops
Returns:
stop type corresponding to one of following values:
0 - A valid PC*Miler stop
1 - A valid LatLong or address
2 - A valid SPLC

SetLoaded

public int SetLoaded(long tripID,
                     int idx,
                     boolean bLoaded)
Sets stop flag to either loaded or empty.

Parameters:
tripID - unique trip identifier
idx - 0-based index into trip list of stops
bLoaded - boolean with value true if loaded, false if empty
Returns:
1 on success; 0 on error

Lookup

public int Lookup(long tripID,
                  java.lang.String str,
                  int easyMatch)
Looks up zip or city/state name and returns number of matching places. Use PCMSGetMatch() to retrieve each matching place.

Parameters:
tripID - unique trip identifier
str - String containing location information
easyMatch - int with value 1 for exact matches only, 0 to include partial matches
Returns:
number of matches

GetMatch

public int GetMatch(long tripID,
                    int idx,
                    java.lang.StringBuffer strBuf)
Gets specific place name from last Lookup.

Parameters:
tripID - unique trip identifier
idx - 0-based index into list of matches
strBuf - user-supplied StringBuffer to hold place name string on success
Returns:
number of bytes written to strBuf; -1 on error

GetFmtMatch

public int GetFmtMatch(long tripID,
                       int idx,
                       java.lang.StringBuffer strBuf,
                       int zipLen,
                       int cityLen,
                       int countyLen)
Gets specific place name from last Lookup in a custom format.

Parameters:
tripID - unique trip identifier
idx - 0-based index into list of matches
strBuf - user-supplied StringBuffer to hold place name string on success
zipLen - maximum number of bytes allocated to zip information
cityLen - maximum number of bytes allocated to city information (including state)
countyLen - maximum number of bytes allocated to county information
Returns:
number of bytes written to strBuf, -1 on error

GetFmtMatch2

public int GetFmtMatch2(long tripID,
                        int idx,
                        java.lang.StringBuffer addr,
                        java.lang.StringBuffer city,
                        java.lang.StringBuffer state,
                        java.lang.StringBuffer zip,
                        java.lang.StringBuffer county)
Gets specific place name from last Lookup, parsed into separate fields for address, city, state, zip and county.

Parameters:
tripID - unique trip identifier
idx - 0-based index into list of matches
addr - user-supplied StringBuffer to hold address string on success
city - user-supplied StringBuffer to hold city string on success
state - user-supplied StringBuffer to hold state string on success
zip - user-supplied StringBuffer to hold zip string on success
county - user-supplied StringBuffer to hold county string on success
Returns:
1 on success; -1 on error

NumMatches

public int NumMatches(long tripID)
Gets total number of matches found in last Lookup.

Parameters:
tripID - unique trip identifier
Returns:
number of matches found in last Lookup

NumPOICategories

public int NumPOICategories(short serverID)
Gets total number of POI categories in data.

Parameters:
serverID - unique server identifier
Returns:
number of POI categories in data

POICategoryName

public int POICategoryName(short serverID,
                           int index,
                           java.lang.StringBuffer strBuf)
Gets the name of a POI category.

Parameters:
serverID - unique server identifier
index - 0-based index into list of categories (list size determined by POICategoriesNum)
strBuf - user-supplied StringBuffer to hold category name
Returns:
number of bytes written to strBuf; -1 on error

LocRadLookup

public int LocRadLookup(long tripID,
                        java.lang.String city,
                        int radius,
                        boolean bCities,
                        boolean bPostalCodes,
                        boolean bCustomPlaces,
                        boolean bPOI,
                        int POICategoryIndex)
Looks up cities, postal codes, custom places, and/or POIs within a radius around a city/state or zip. To find the index for a POI category use the POICategoriesNum and POICategoryName methods.

Parameters:
tripID - unique trip identifier
city - String containing location information (city/state or zipcode)
radius - search radius in miles
bCities - include cities in search (if true)
bPostalCodes - include postal codes in search (if true)
bCustomPlaces - include custom places in search (if true)
bPOI - include pois in search (if true)
POICategoryIndex - category index of POIs to search
Returns:
number of items found

GetLocRadItem

public int GetLocRadItem(long tripID,
                         int index,
                         java.lang.StringBuffer strBuf)
Gets an item found through a LocRadLookup query. Returns a buffer containing item information prepended by distance from original lookup location.

Parameters:
tripID - unique trip identifier
index - 0-based index into list of items foudn by LocRadLookup
strBuf - user-supplied StringBuffer to hold item results (distance to lookup location is prepended)
Returns:
number of bytes written to strBuf; -1 on error

GetRpt

public int GetRpt(long tripID,
                  int rptNum,
                  java.lang.StringBuffer strBuf)
Copies entire report text into user-supplied StringBuffer.

Parameters:
tripID - unique trip identifier
rptNum - type of report to return. Can be one of following values:
0 - Detailed
1 - State
2 - Mileage
strBuf - user-supplied StringBuffer to hold text of report on success
Returns:
length of report in bytes

GetRptLine

public int GetRptLine(long tripID,
                      int rptNum,
                      int lineNum,
                      java.lang.StringBuffer strBuf)
Copies line from specified report into user-supplied StringBuffer. Index lines from 0.

Parameters:
tripID - unique trip identifier
rptNum - type of report to return. Refer to GetRpt for appropriate values
lineNum - line of report to be copied
strBuf - user-supplied StringBuffer to hold report line on success
Returns:
number of bytes copied; -1 on error; 0 if report not ready

NumRptLines

public int NumRptLines(long tripID,
                       int rptNum)
Gets number of lines in report.

Parameters:
tripID - unique trip identifier
rptNum - type of report to generate. Refer to GetRpt for appropriate values
Returns:
number of lines in report

NumRptBytes

public long NumRptBytes(long tripID,
                        int rptNum)
Gets total length of report in bytes.

Parameters:
tripID - unique trip identifier
rptNum - type of report to generate. Refer to GetRpt for appropriate values
Returns:
number of bytes in report

GetHTMLRpt

public long GetHTMLRpt(long tripID,
                       int rptNum,
                       java.lang.StringBuffer strBuf)
Copies HTML-formatted report into user-supplied StringBuffer.

Parameters:
tripID - unique trip identifier
rptNum - type of report to return. Refer to GetRpt for appropriate values
strBuf - user-supplied StringBuffer to hold text of report
Returns:
number of bytes in report

NumHTMLRptBytes

public long NumHTMLRptBytes(long tripID,
                            int rptNum)
Gets total length of HTML-formatted report.

Parameters:
tripID - unique trip identifier
rptNum - type of report to return. Refer to GetRpt for appropriate values
Returns:
number of bytes in report

GetNumSegments

public int GetNumSegments(long tripID)
Gets number of segments in detailed report.

Parameters:
tripID - unique trip identifier
Returns:
number of segments in detailed report

GetSegment

public int GetSegment(long tripID,
                      int segNum,
                      SegmentStruct pSegment)
Gets segment by 0-based index.

Parameters:
tripID - unique trip identifier
segNum - 0-based index into segment list
pSegment - empty user-supplied object of type SegmentStruct. Used to return method results.
Returns:
1 on success; 0 if segNum exceeds bounds; -1 if report not ready

GetLegInfo

public int GetLegInfo(long tripID,
                      int legNum,
                      LegInfoType pLegInfo)
Gets information about leg miles, total miles, leg cost, total cost, leg hours, and total for specific leg of trip.

Parameters:
tripID - unique trip identifier
legNum - 0-based index into list of legs
pLegInfo - empty user-supplied object of type pLegInfo. Used to return method results.
Returns:
1 on success; -1 on error

SetCalcType

public void SetCalcType(long tripID,
                        int calcType)
Sets criteria used to calculate distance for given trip.

Parameters:
tripID - unique trip identifier
calcType - Refer to CalcDistance2 for appropriate input values

GetCalcType

public int GetCalcType(long tripID)
Gets criteria used to calculate distance for given trip.

Parameters:
tripID - unique trip identifier
Returns:
Refer to CalcDistance2 for mapping of output values

SetCalcTypeEx

public void SetCalcTypeEx(long tripID,
                          CalcTypeEx calcTypeEx)
Sets extended criteria used to calculate distance for given trip. Analogous to CALCEX_ #defines in PCMSDefs.h

Parameters:
tripID - unique trip identifier
calcTypeEx - user-supplied object of type CalcTypeEx with each member initialized to one of following values:
rtType:
0x00000001 - Practical
0x00000002 - Shortest
0x00000004 - Air Distance
optFlags:
0x00000100 - Avoid Tolls
0x00000200 - National Routing
0x00000400 - 53' Routing
vehType:
0x00000000 - Truck
0x01000000 - Auto

GetCalcTypeEx

public int GetCalcTypeEx(long tripID,
                         CalcTypeEx calcTypeEx)
Gets extended criteria used to calculate distance for given trip.

Parameters:
tripID - unique trip identifier
calcTypeEx - empty user-supplied object of type CalcTypeEx. Used to return method results.
Returns:
a concatenation of all three CalcTypeEx members bit-wise or'ed into a single integer.

SetBordersOpen

public void SetBordersOpen(long tripID,
                           boolean bOpen)
Sets trip option to run routes with international borders open (true) or closed (false).

Parameters:
tripID - unique trip identifier
bOpen - if true, run with borders open; if false, run with borders closed

SetShowFerryMiles

public void SetShowFerryMiles(long tripID,
                              boolean bOnOff)
Sets trip option to include ferry miles in distance calculations (true) or ignore them (false).

Parameters:
tripID - unique trip identifier
bOnOff - if true, include ferry miles; if false, ignore ferry miles

SetKilometers

public void SetKilometers(long tripID)
Sets trip option to report all distances in kilometers.

Parameters:
tripID - unique trip identifier

SetMiles

public void SetMiles(long tripID)
Sets trip option to report all distances in miles.

Parameters:
tripID - unique trip identifier

SetHubMode

public void SetHubMode(long tripID,
                       boolean bOnOff)
Sets hub routing mode on (true) so that first stop becomes common origin for all subsequent stops, or off (false) to route through all stops.

Parameters:
tripID - unique trip identifier
bOnOff - if true, turn hub routing on; if false, turn hub routing off

SetCost

public void SetCost(long tripID,
                    int cost)
Sets cost per mile (in cents).

Parameters:
tripID - unique trip identifier
cost - cost/mile in cents

GetCost

public int GetCost(long tripID)
Gets cost per mile (in cents).

Parameters:
tripID - unique trip identifier
Returns:
cost/mile in cents

SetResequence

public void SetResequence(long tripID,
                          boolean bChangeDest)
Sets trip option so that when optimizing, reorder all but first stop (true), or all but the first and last stops (false).

Parameters:
tripID - unique trip identifier
bChangeDest - if true, resequence all stops except origin; if false, resequence all stops except origin and last stop

SetTollMode

public void SetTollMode(long tripID,
                        int mode)
Sets level of toll reporting for trip.

Parameters:
tripID - unique trip identifier
mode - use one of following values:
0 - no toll information
1 - cash toll amount
2 - discount toll amount

SetOptions

public void SetOptions(long tripID,
                       long opts)
Sets trip options from set of flags. Refer to OPTDEFS.H for valid input values

Parameters:
tripID - unique trip identifier
opts - concatenation of possible options flags bit-wise or'ed into single long

GetOptions

public long GetOptions(long tripID)
Gets trip options as single set of flags. Refer to OPTDEFS.H for valid output values

Parameters:
tripID - unique trip identifier
Returns:
concatenation of possible options flags bit-wise or'ed into single long

NumLegs

public int NumLegs(long tripID)
Gets number of legs in trip.

Parameters:
tripID - unique trip identifier

Defaults

public void Defaults(long tripID)
Reset all options to default values.

Parameters:
tripID - unique trip identifier

SetBreakHours

public void SetBreakHours(long tripID,
                          long mins)
Sets the interval designated on-duty and between breaks (in minutes).

Parameters:
tripID - unique trip identifier
mins - number of minutes between breaks

GetBreakHours

public long GetBreakHours(long tripID)
Gets the interval designated on-duty and between breaks (in minutes).

Parameters:
tripID - unique trip identifier
Returns:
number of minutes between breaks

SetBreakWaitHours

public void SetBreakWaitHours(long tripID,
                              long mins)
Sets length of breaks (in minutes).

Parameters:
tripID - unique trip identifier
mins - length of breaks in minutes

GetBreakWaitHours

public long GetBreakWaitHours(long tripID)
Gets length of breaks (in minutes).

Parameters:
tripID - unique trip identifier
Returns:
length of breaks in minutes

SetBorderWaitHours

public void SetBorderWaitHours(long tripID,
                               long mins)
Sets time spent waiting at borders (in minutes).

Parameters:
tripID - unique trip identifier
mins - minutes spent waiting at borders

GetBorderWaitHours

public long GetBorderWaitHours(long tripID)
Gets time spent waiting at borders (in minutes).

Parameters:
tripID - unique trip identifier
Returns:
minutes spent waiting at borders

SetOnRoad

public void SetOnRoad(long tripID,
                      boolean bOnOff)
Sets trip option determining whether a latlong should be geocoded to a road (true), or used as an exact position.

Parameters:
tripID - unique trip identifier
bOnOff - true if enable latlong geocoding to road, false if disable latlong geocoding to road

SetCustomMode

public void SetCustomMode(long tripID,
                          boolean bOnOff)
Sets trip option to route with custom mode on(true) or off(false).

Parameters:
tripID - unique trip identifier
bOnOff - true if enable custom routing, false if disable custom routing

SetOldMode

public void SetOldMode(long tripID,
                       boolean bOnOff)
Sets trip option to enable old-style (no comma) geocoding (if true).

Parameters:
tripID - unique trip identifier
bOnOff - true if enable old-style geocoding, false if disable old-style geocoding

SetOldModeForRegion

public int SetOldModeForRegion(short serverID,
                               java.lang.String regionID,
                               boolean bOnOff)
Sets server option to enable old-style (no comma) geocoding for an entire region. Note: assumes default region if none is given.

Parameters:
serverID - unique server identifier
regionID - String denoting region to be set
bOnOff - true if enable old-style geocoding; false if disable old-style geocoding

SetAlphaOrder

public void SetAlphaOrder(long tripID,
                          boolean bAlphaOrder)
Sets trip option to sort state report in alphabetical (true) or in driving order (false).

Parameters:
tripID - unique trip identifier
bAlphaOrder - true if sort state report in alphabetical order; false if sort in driving order

ConvertLLToPlace

public void ConvertLLToPlace(long tripID,
                             boolean bYesNo)
Sets trip option to automatically convert latlongs to PC*MILER place names (true).

Parameters:
tripID - unique trip identifier
bYesNo - true to convert latlongs to place names; false to keep latlongs intact

AFLinks

public int AFLinks(long tripID,
                   boolean bFavor)
Sets trip option so that selected links are respectively avoided and favored during route calculation (if true).

Parameters:
tripID - unique trip identifier
bFavor - true to avoid or favor selected links during route calculation; false otherwise
Returns:
1 on success; 0 if could not find any actively selected links; -1 on error

AFLoad

public int AFLoad(short serverID,
                  java.lang.String filename)
Loads current set of avoided/favored links for default region.

Parameters:
serverID - unique server identifier
filename - name of file to be loaded

AFSave

public int AFSave(short serverID)
Saves current set of avoided/favored links for default region to file

Parameters:
serverID - unique server identifier
Returns:
1 on success; 0 on error

AFLoadForRegion

public int AFLoadForRegion(short serverID,
                           java.lang.String filename,
                           java.lang.String regionID)
Loads current set of avoided/favored links for specified region. Note: assumes default region if none is given.

Parameters:
serverID - unique server identifier
filename - name of file to be loaded

AFSaveForRegion

public int AFSaveForRegion(short serverID,
                           java.lang.String regionID)
Saves current set of avoided/favored links for specified region to file. Note: assumes default region if none is given.

Parameters:
serverID - unique server identifier
regionID - String specifiying region
Returns:
1 on success; 0 on error

CalcDistToRoute

public int CalcDistToRoute(long tripID,
                           java.lang.String location)
Calculates orthogonal distance to route from "location".

Parameters:
tripID - unique trip identifier
location - String containing location information
Returns:
orthogonal distance to route, or -1 on error

AirDistToRte

public long AirDistToRte(long tripID,
                         java.lang.String location,
                         int legNum)
Calculates closest air distance between "location" and specified leg.

Parameters:
tripID - unique trip identifier
location - String containing location information
legNum - 0-based index into list of legs
Returns:
air distance to route, or -1 on error

GetLocAtMiles

public int GetLocAtMiles(long tripID,
                         long miles,
                         java.lang.StringBuffer strBuf)
Gets nearest location on the route after travelling 'miles' from the origin.

Parameters:
tripID - unique trip identifier
miles - number of miles along route
strBuf - StringBuffer to hold location information
Returns:
number of bytes written to strBuf; 0 on error

GetLocAtMinutes

public int GetLocAtMinutes(long tripID,
                           long minutes,
                           java.lang.StringBuffer strBuf)
Gets nearest location on the route after travelling 'minutes' from the origin.

Parameters:
tripID - unique trip identifier
minutes - number of minutes travelled
strBuf - StringBuffer to hold location information
Returns:
number of bytes written to strBuf; 0 on error

LatLongAtMiles

public int LatLongAtMiles(long tripID,
                          long miles,
                          java.lang.StringBuffer strBuf,
                          boolean bUseShpPts)
Get latlong on the route after travelling 'miles' from the origin.

Parameters:
tripID - unique trip identifier
miles - number of miles along route
strBuf - StringBuffer to hold latlong information
bUseShpPts - use shape points in route calculation
Returns:
number of bytes written to strBuf; 0 on error

LatLongAtMinutes

public int LatLongAtMinutes(long tripID,
                            long minutes,
                            java.lang.StringBuffer strBuf,
                            boolean bUseShpPts)
Get latlong on the route after travelling 'minutes' from the origin.

Parameters:
tripID - unique trip identifier
minutes - number of minutes travelled
strBuf - StringBuffer to hold latlong information
bUseShpPts - use shape points in route calculation (true)
Returns:
number of bytes written to strBuf; 0 on error

NumLatLongsEnRoute

public long NumLatLongsEnRoute(long tripID,
                               boolean bUseShpPts)
Gets total number of lat/long pairs in route.

Parameters:
tripID - unique trip identifier
bUseShpPts - use shape points in route calculation (true)
Returns:
nubmer of lat/long pairs in route; 0 on error

LatLongsEnRoute

public double[] LatLongsEnRoute(long tripID,
                                long numPairs,
                                boolean bUseShpPts)
Gets lat/long pairs along route.

Parameters:
tripID - unique trip identifier
numPairs - number of pairs to return
bUseShpPts - use shape points in route calculation (true)
Returns:
array of doubles containing lat/long pairs along route

SetVehicleType

public void SetVehicleType(long tripID,
                           boolean bOnOff)
Sets trip option to calculate route with heavy vehicle on (true) or off(false)

Parameters:
tripID - unique trip identifier
bOnOff - true if heavy vehicle on, false if heavy vehicle off

SetRoadNameOnly

public void SetRoadNameOnly(long tripID,
                            boolean bOnOff)
Sets trip option to match addresses on road names only (true), or only match addresses exactly(false).

Parameters:
tripID - unique trip identifier
bOnOff - true if match address to road name, false if only match exactly

SetExactLevel

public void SetExactLevel(short serverID,
                          int threshold)
Sets threshold at which an address is considered a match.

Parameters:
serverID - unique serverID
threshold - valid range 0 to 100

GetExactLevel

public int GetExactLevel(short serverID)
Gets current threshold at which an address is considered a match.

Parameters:
serverID - unique serverID
Returns:
threshold value

SetHazOption

public void SetHazOption(long tripID,
                         int hazType)
Sets Hazardous Routing options. Available only when HazMat installed

Parameters:
tripID - unique trip ID
hazType - one of the following values:
0 - none
1 - general
2 - explosive
3 - inhalant
4 - radioactive

TranslateAlias

public void TranslateAlias(long tripID,
                           boolean bTranslate)
Sets wheter aliases (custom places) should be translated to corresponding location or left as user-defined name.

Parameters:
tripID - unique trip identifier
bTranslate - true if translate; false if do not translate