PC*MILER Rail-Connect supports both Interactive routing and AutoRouting, similar to the PC*MILER Rail user interface. AutoRouting allows the user to specify an origin, destination, and optional ‘via’ point, and finds all routes between those points. These routes will be determined from all rail carriers serving those points, unless the user chooses to specify a particular carrier at any point (orig, dest, or via). Users can then get a summary of all routes as well as (Key Station, Detailed Route, and Detailed Geocode) reports on any specific route.


The following is a list of the DLL API functions for AutoRouting, along with a brief description.



HRESULT PCRSClearAutoRouter (Trip trip)


PCRSClearAutoRouter() simply clears any stops or trips previously stored in the AutoRouter.



HRESULT PCRSAddAutoRouteOrig (Trip trip, char *geoName, char *geoChar, char *rrIn)


PCRSAddAutoRouteOrig() adds the origin point to the AutoRouter. This requires the user to specify the geoName and type (station, SPLC, etc.). Railroad (rrIn) is an optional field: if specified, the AutoRouter will only use that railroad at that point, otherwise all railroads serving the specified location will be considered.



HRESULT PCRSAddAutoRouteDest (Trip trip, char *geoName, char *geoChar, char *rrIn)


PCRSAddAutoRouteDest() same as above but for destination stop.



HRESULT PCRSAddAutoRouteVia (Trip trip, char *geoName, char *geoChar)


PCRSAddAutoRouteVia() similar to the orig and dest versions above, however this is simply a "waypoint" and does not allow specification of a railroad.



HRESULT PCRSCalcAutoRoutes (Trip trip, int *numAutoRoutes)


PCRSCalcAutoRoutes() finds all routes between the points previously set using the above functions. The number of routes found is returned in the pointer argument numAutoRoutes.



HRESULT PCRSGetNumAutoRoutes (Trip trip, int *numAutoRoutes)


PCRSGetNumAutoRoutes() returns the number of routes previously calculated in in the pointer argument numAutoRoutes.



HRESULT PCRSGetAutoRouteLine (Trip trip, char *buffer, int bufSize, int which, int *pNumJcts)


PCRSGetAutoRouteLine() returns a summary of the selected route (by which) that includes mileage, railroads, and junctions.



HRESULT PCRSGetAutoRouteMiles (Trip trip, int which, long *pMiles)


PCRSGetAutoRouteMiles() returns the mileage of the route selected by which.



A code sample of running an AutoRoute follows:


#define BUFLEN 128
char buffer[BUFLEN];
int numLines, i;
HRESULT srvRet;

/* Error handling code (of srvRet) will be omitted 
for brevity */

srvRet = PCRSClearAutoRouter (myTrip);
srvRet = PCRSAddAutoRouteOrig (myTrip, "OAKLAND CA",
"C", NULL);
srvRet = PCRSAddAutoRouteDest (myTrip, "BALTIMORE MD", 
"C",NULL);
srvRet = PCRSCalcAutoRoutes (myTrip, &numAutoRoutes);
for (i = 0; i < numAutoRoutes; i++)
{
  srvRet = PCRSGetAutoRouteMiles (myTrip, i, 
        &miles_tenths);
  srvRet = PCRSGetAutoRouteLine (myTrip, buffer, 
        BUFLEN, i, &numJcts);
  miles = (float) miles_tenths / 10;
  printf ("Route #%d/%d, Miles: %3.1f, NumJcts:%d,             Desc:%s", i, numAutoRoutes, miles, 
        numJcts, buffer);
}


Reports

Users can also generate the standard reports for any AutoRoute calculated by the above functions. These AutoRoute reporting functions are as follows:


HRESULT PCRSGetARRpt (Trip trip, int which, char *rptType, char *buffer, int bufSize, int *pBuflen)

HRESULT PCRSGetARRptLine (Trip trip, int which, char *rptType, int rowNum, char *buffer, int bufSize, int *pBuflen)

HRESULT PCRSARGetRptLength (Trip trip, int which, char *rptType, long *rptLen)

HRESULT PCRSGetARNumRptLines(Trip trip, int which, char *rptType, int *numLines)


PCRSGetARRpt() will place the entire report body in the given buffer (up to bufSize-1 bytes) while the remaining functions retrieve the report from the server one line at a time. A code example for line by line retrieval of a specific AutoRoute follows:


int routeNum;

/* Get Detailed Route report for 2nd route: */
routeNum = 2;
srvRet = PCRSGetARNumRptLines(myTrip, routeNum, "D", 
      &numLines); 
for (i = 0; i < numLines; i++)
{
  srvRet = PCRSGetARRptLine(myTrip, routeNum, "D", i,   
        buffer, BUFLEN, NULL);
  printf ("%s", buffer);
}