PCMilerInterface

PC Miler Interface

Minor Business Rule

Object Name: B4900500

Parent DLL: CTRAN

Location: Client/Server

Language: C

1.Functional Description

1.1 Purpose

This business function provides an interface with the PC Miler software which calculates distances and routes over the North American highways
for an origin-destination pair of locations with intermediate stop-off points. Locations are specified as postal codes. PCMiler/ Server Dynamic
Link Library (DLL) is designed to fulfill all the routing and mileage reporting needs of custom truck and shipper application development.

1.2Setup Notes and Prerequisites

In order to invoke the PC Miler interface, the Distance Source in the Transportation Constants must be set as '4'.  When a program such as
rating or Load Build calls the GetDistance function, the Distance Source is used to determine what function should be called.  A distance source
of '4' results in this function being called, and in turn the PC Miler DLL is called.

If processing in a WAN environment or any environment where business functions are mapped to run on the server, the PC Miler product
must be installed on a server as well.  Furthermore, the server must support the Windows DLL calls (i.e. it must be a windows server).  If the PC
Miler product is installed to run on a server, then this business function must be mapped through OCM to run on that same server.

1.3Special Logic

Include the PC Miler header files pcmdefs.h, pcmstrip.h and pcminit.h. Include these files in the server through the help of the PVC support.

The header file pcmdefs.h has the data type definition BOOL in small case which is not compatible with the compiler. Hence define the BOOL
in upper case in the header before including the pcmdefs.h header file and undefine the same after including the pcmdefs.h header file.

Due to the implementation differences of exception handling between Microsoft Developer Studio and the PC Miler software, calling the PC
Miler DLL by using static binding results in a failure, when exceptions are thrown from the DLL. Hence load the DLL dynamically at run time
using the Load Library function and retrieve the entry points for the PC Miler functions exported from the DLL by calling GetProcAddress
function.
The definitions of the PC Miler functions can be found in the PC Miler header file pcmsrv.h. Paste these definitions in the header.

Define a structure of function pointers in the header for each of the PC Miler functions with their data types obtained from their definitions.
The function pointers are initialized in the source file and persistence of these pointers should reflect throughout the code whenever the PC
Miler functions are called.

The PCMiler functions and their usage is listed below. These are the functions specific to this program.

PCMSSetDebug ( int levl ) - Specifies the current debugging level.

PCMSOpenServer ( HINSTANCE hAppInst, HWND hwnd ) - Initializes the DLL, checks PCMiler licenses, loads the PCMiler highway
database and starts the engine for routing calculations. The arguments are currently not used.
hAppInst - the calling application's instance handle. May be NULL.
hWnd - the parent window's window handle. May be NULL.
Returns a unique ID for this server connection.

PCMSIsValid ( PCMServerID server ) - Checks that the server is a valid handle.

PCMSCalcDistance2 ( PCMServerID serv, const char *orig, const char *dest, int routeType ) - Returns the distance between orig and
dest by calculating the route using the given routeType (CALC_SHORTEST). The distance is returned in tenths of miles.

PCMSNewTrip ( PCMServerID , serverID) - Returns a handle to a new trip( a trip indicates multiple stops and various options).

PCMSDeleteTrip ( Trip tripID ) - Clean's up the trip's memory.

PCMSAddStop ( Trip tripID, const char *stop) - adds a stop off as the last stop in the stop list of the trip.

PCMSClearStops ( Trip tripID) - Clears the trip's list of all stops.

PCMSGetStop ( Trip tripID, int which, char *buffer, int bufSize) - Returns the stop name in the supplied buffer. Use which to index into
the list of stops.

PCMSNumStops ( Trip tripID ) - returns the total number of stops currently in the trip's stop list, including origin and the destination.

PCMSOptimize ( Trip tripID ) - Optimizes the order of stops. Returns -1 on error, 0 if already optimized 1 on success.

PCMSSetResequence ( Trip tripID, BOOL changeDest ) - Specifies whether optimization should be allowed for the destination stop (
TRUE ), or not ( FALSE).

PCMSCheckPlaceName ( PCMServerID serv, const char *cityZIP ) - Validates the city names and ZIP codes.

PCMSCloseServer (PCMServerID server) - Cleans up and unloads the PCMiler highway database. Must be the last DLL function
called when done using the engine.

2.Technical Specifications

2.1Parameters:
Data Item Data Structure DescriptionI/OReqNotes
EV01cModeIYIf 0 - Single Shipment     1 - Load Shipment without optimization     2 - Load Shipment with optimization and
  floating destination     3 - Load Shipment with optimization and                  fixed destination
ADDZszOriginPostalCodeINRequired if Mode = 0
ADDZszDestinationPostalCodeIN             "
DSTNmnDistanceOYCumulative Distance of the entire trip
JOBSmnJobNumberINIndicates cache
DTAIszErrorMessageOY
SUPPScSuppressErrorMessageIY
EV01cRouteTypeIYIf 1 - Practical Route Option.           CALC_PRACTICAL     2 - Shortest Route Option
CALC_SHORTEST     3 - Toll Discouraged Route Option           CALC_AVOIDTOLL     4 - National Network Route Option           CALC_NATIONAL

Data Structure

D4900500 - PC Miler Interface Template

Parameter Name Data Item Data Type Req/Opt I/O/Both

cMode EV01 char NONE NONE

An option that specifies the type of processing for an event.

szOriginPostalCode ADDZ char NONE NONE

The United States ZIP code or the postal code that specifies where a letter is to be routed.  Attach this code to the address for delivery in
other countries. This code is used as the low end value when doing Postal Code Transaction range processing.

szDestinationPostalCode ADDZ char NONE NONE

The United States ZIP code or the postal code that specifies where a letter is to be routed.  Attach this code to the address for delivery in
other countries. This code is used as the low end value when doing Postal Code Transaction range processing.

mnDistance DSTN MATH_NUMERIC NONE NONE

Either the total amount of distanced traveled, or the total amount of time spent idle.

mnJobNumber JOBS MATH_NUMERIC NONE NONE

The job number (work station ID) which executed the particular job.

szErrorMessage DTAI char NONE NONE

A code that identifies and defines a unit of information. It is an alphanumeric code up to 8 characters long that does not allow blanks or
special characters such as %, &, or +. You create new data items using system codes 55-59. You cannot change the alias.

cSuppressErrorMessage SUPPS char NONE NONE

A flag indicating whether or not runtime error messaging will occur when an error message is issued from a business function.        0 = allow
runtime error message handling.        1 = suppress runtime error message handling.

cRouteType EV01 char NONE NONE

An option that specifies the type of processing for an event.

mnAddressNumberDeconsolida ANCC MATH_NUMERIC OPT NONE

The address book number of a hub or deconsolidation center.  A hub number is entered for a load to indicate a pooled shipment.

Related Functions

None

Related Tables

None

Parameter Name	Data Item	Data Type	Req/Opt	I/O/Both
cMode	EV01	char	NONE	NONE
An option that specifies the type of processing for an event.
szOriginPostalCode	ADDZ	char	NONE	NONE
The United States ZIP code or the postal code that specifies where a letter is to be routed. Attach this code to the address for delivery in other countries. This code is used as the low end value when doing Postal Code Transaction range processing.
szDestinationPostalCode	ADDZ	char	NONE	NONE
The United States ZIP code or the postal code that specifies where a letter is to be routed. Attach this code to the address for delivery in other countries. This code is used as the low end value when doing Postal Code Transaction range processing.
mnDistance	DSTN	MATH_NUMERIC	NONE	NONE
Either the total amount of distanced traveled, or the total amount of time spent idle.
mnJobNumber	JOBS	MATH_NUMERIC	NONE	NONE
The job number (work station ID) which executed the particular job.
szErrorMessage	DTAI	char	NONE	NONE
A code that identifies and defines a unit of information. It is an alphanumeric code up to 8 characters long that does not allow blanks or special characters such as %, &, or +. You create new data items using system codes 55-59. You cannot change the alias.
cSuppressErrorMessage	SUPPS	char	NONE	NONE
A flag indicating whether or not runtime error messaging will occur when an error message is issued from a business function. 0 = allow runtime error message handling. 1 = suppress runtime error message handling.
cRouteType	EV01	char	NONE	NONE
An option that specifies the type of processing for an event.
mnAddressNumberDeconsolida	ANCC	MATH_NUMERIC	OPT	NONE
The address book number of a hub or deconsolidation center. A hub number is entered for a load to indicate a pooled shipment.