Generating and Retrieving Rail Reports

Once a trip’s route has been calculated, you can retrieve reports showing the route’s information. The reports are returned in tab-delimited lines, which allow easy pasting into spreadsheets, list boxes, and grids. The DLL API allows users to retrieve the entire report body or line by line. These functions and an example are below.

HRESULT PCRSGetRpt(Trip trip, char *rptType, char *buffer, int bufSize, int *pBuflen)
HRESULT PCRSGetRptLine(Trip trip, char *rptType, int rowNum, char *buffer, int bufSize, int *pBuflen)
HRESULT PCRSGetNumRptLines(Trip trip, char *rptType, int *numLines)
HRESULT PCRSGetRptLength(Trip trip, char *rptType, long *rptLen)

The call PCRSGetRpt() will place the entire report body into the buffer (up to bufSize bytes). The rptType ("K", "D", or "G") argument indicates which type of report is desired:

• K: Key Station report
• D: Detailed Route report
• G: Detailed Geocode report

As the names suggest:

• The Key Cities report lists each stop in the route along with locations marked as Key Cities (or stations) in the PC*Miler Rail database.
• The Detailed Route report contains the information in the Key Cities report plus more of the smaller stations/points along the route.
• The Detailed Geocode report includes the same information as the Detailed Report, but also lists geographic codes for each stop.

All three reports contain mileage breakdowns by state and railroad appended to the end of the report body. (To generate a separate report containing only state mileage, see the description of PCRSGetStateRRMiles() below.)

Reports can also be retrieved line by line, as shown in the following example:

/* Assume a trip has already been run via
  PCRSCalcTrip or PCRSCalculate
*/

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

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

/* Index lines from 0. Buffer must be > 100 char */
/* Get the KEY CITIES report */
srvRet = PCRSGetNumRptLines(myTrip, "K", &numLines);
for (i = 0; i < numLines; i++) {
   srvRet = PCRSGetRptLine(myTrip, "K", i, buffer, BUFLEN, NULL);
   printf("%s\n", buffer);
}

Retrieving State Mileage

HRESULT PCRSGetStateRRMiles(Trip trip, int stIndx, short rrNum, long *pMiles)

The call PCRSGetStateRRMiles() returns only the trip mileage by state. Argument values are:

• stIndx: state index #
• rrNum: RR number
• pMiles: state miles

For example:

/*****************************************************
* Get miles in Alberta
*
* Initialize to args so we can later make a call to get the railroad miles in Alberta on CPRS
******************************************************/

// Arg1 - Get the Rail Road Number for "CPRS"
srvRet = PCRSRRName2Num("CPRS", &rrNum);

// Arg2 - Alberta state index is 1
int stateIndex = 1;

// Get the railroad miles in Alberta on CPRS
srvRet = PCRSGetStateRRMiles(myTrip, stateIndex, rrNum, &tempMiles);