AutoRouting Functions

PC*Miler Rail-Connect supports both Interactive routing and AutoRouting, similar to the PC*Miler Rail user interface. AutoRouting allows you to specify an origin, destination, and optional via point, and finds all routes between those points. These routes are determined from all rail carriers serving those points, unless you specify a particular carrier at any point (origin, destination, or via). You can then get a summary of all routes as well as 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 you to specify the geoName and type (station, SPLC, etc.). Railroad (rrIn) is optional: if specified, the AutoRouter will only use that railroad at that point; otherwise, all railroads serving the location will be considered.

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

PCRSAddAutoRouteDest() is the same as above but for the destination stop.

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

PCRSAddAutoRouteVia() is similar to the origin and destination versions above, but 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 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.

Example: Running an AutoRoute

#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

You 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);
}