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

PCRSGetAllStateRRMileage() returns a list of structures, while PCRSGetAllStateRRMileage1() returns a list in text format delimited by pipes. Below are descriptions of each function. 

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

In the above function, Trip refers to the trip setup through PC*MILER Rail-Connect, combinationArray is the output list containing MileageStruct structures, and numCombinations is the number of structures returned in the array. 

This API will return a list of structures with each structure containing the following: 

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

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

1. When calling the API initially, you are instructing the PC*MILER Rail software to go out and gather the number of records combinations (state, railroad and miles) that exist for your trip. The return value of this call will be the number of combinations. The initial call will look something like this (below). 

numCombinations = PCRSGetAllStateRRMileage(trip, NULL, 0)

It is very important to pass in a NULL pointer to the second argument. Also pass in zero as the third argument. This tells PC*MILER Rail to obtain the number of combinations. Later, you will make the call again to get the actual data. If an error occurs, your return value will be a negative number mapping to a PC*MILER Rail error code.

2. After making your initial request, you need to allocate memory for the array of Mileage structures. So, if the API returns 10 for the number of combinations, you will need a “C” statement similar to this:

MileageStruct* mileageArray = new MileageStruct[10]

3. After allocating memory, you are now ready to make your final request to get the array of mileage structures. Notice that you are passing back in the number of combinations to retrieve in the third argument:

srvRet = PCRSGetAllStateRRMileage(myTrip, mileageArray, numCombinations)

In the above function, Trip refers to the trip set up through PC*MILER Rail-Connect, mileageBuffer is the output list of unique combinations of railroad, state and miles for a given trip, and bufferSize is the length of the mileageBuffer.

This API will return a list of unique combinations delimited by the double pipe symbol “||”. Within each item or field in the list, the delimiter is a single pipe “|”. This entire list will be stuffed into your outgoing char buffer (mileageBuffer). See  small snippet below where we have a list of 2 items. Take special note of how the fields are ordered within an item in the list.

||State Abbrev|State Index|RR Abbrev|RR Num|Miles

||KY|32|BNSF|712|143.6

||PA|47|NS|312|156.2

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

1. When calling the API initially, you are instructing the RAIL software to go out and gather how many record combinations (state, railroad and miles) exist for your trip. The return value of this call will be the size of the buffer. The initial call will look something like this (see below). 

bufferSize = PCRSGetAllStateRRMileage1(trip, NULL, 0)

It is very important to pass in a NULL pointer to the second argument. Also pass in zero as the third argument. This tells the RAIL software to go out and determine the buffer size. Later , we will make the call again to get the actual data. If an error occurs, your return value will be a negative number mapping to a RAIL error code.

2. After making your initial API request, you need to allocate memory for the array. You will need a “C” statement similar to this:

char *mileageBuffer = new char[bufferSize]

3. After allocating memory, you are now ready to make your final request to get the return buffer of mileage. Notice you are passing back in the mileage buffer size to the PC*MILER Rail software in the third argument:

srvRet = PCRSGetAllStateRRMileage1(myTrip, mileageBuffer, bufferSize)