Getting a Mileage Breakdown by Railroad and State

The functions below return a list of unique combinations representing the mileage breakdown by railroad and state for a given trip.

Function Overview

• PCRSGetAllStateRRMileage() returns a list of structures.
• PCRSGetAllStateRRMileage1() returns a list in text format delimited by pipes.

Below are descriptions of each function.

PCRSGetAllStateRRMileage

HRESULT PCRSGetAllStateRRMileage(Trip trip, MileageStruct* combinationArray, long numCombinations)

• Trip: The trip set up through PC*Miler Rail-Connect.
• combinationArray: Output list containing MileageStruct structures.
• numCombinations: Number of structures returned in the array.

Each structure contains:

1. State abbreviation (char*)
2. State Index (int)
3. Railroad Abbreviation (char*)
4. Railroad Number (short)
5. Miles for the above State/RR combination (long)

Usage Pattern

This API is meant to be used in a two-call sequence:

1. Initial Call: Get the number of combinations.

numCombinations = PCRSGetAllStateRRMileage(trip, NULL, 0);

• Pass NULL for the second argument and 0 for the third.
• The return value is the number of combinations.
• If an error occurs, the return value will be negative.

2. Allocate Memory: Allocate memory for the array of MileageStruct.

MileageStruct* mileageArray = new MileageStruct[numCombinations];

3. Final Call: Retrieve the array of mileage structures.

srvRet = PCRSGetAllStateRRMileage(myTrip, mileageArray, numCombinations);

PCRSGetAllStateRRMileage1

HRESULT PCRSGetAllStateRRMileage1(Trip trip, char* mileageBuffer, long bufferSize)

• Trip: The trip set up through PC*Miler Rail-Connect.
• mileageBuffer: Output list of unique combinations of railroad, state, and miles.
• bufferSize: Length of the mileageBuffer.

The API returns a list of unique combinations delimited by the double pipe symbol ||. Within each item, fields are delimited by a single pipe |. The entire list is stored in the outgoing char buffer (mileageBuffer).

Example Output:

||State Abbrev|State Index|RR Abbrev|RR Num|Miles
||KY|32|BNSF|712|143.6
||PA|47|NS|312|156.2

Usage Pattern

This API is also used in a two-call sequence:

1. Initial Call: Get the required buffer size.

bufferSize = PCRSGetAllStateRRMileage1(trip, NULL, 0);

• Pass NULL for the second argument and 0 for the third.
• The return value is the required buffer size.
• If an error occurs, the return value will be negative.

2. Allocate Memory: Allocate memory for the buffer.

char* mileageBuffer = new char[bufferSize];

3. Final Call: Retrieve the mileage data.

srvRet = PCRSGetAllStateRRMileage1(myTrip, mileageBuffer, bufferSize);