The following function returns a list of latitude/longitude coordinates along a route line in sequential order, starting at the origin and ending at the destination. When the sequence of lat/longs has been obtained in Connect, the user can overlay the PC*MILER Rail route line onto the mapping product of choice.
This API does not have any limit on the number of legs in the input trip. The coordinates list will be returned for all legs of the multi-leg trip.
Trip refers to the trip setup through PC*MILER Rail-Connect, latlong is the list of lat/long pairs, and numPairs is the number of lat/long pairs returned in the list.
This function 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 coordinate pairs. The return value of this call will be the number of lat/long pairs. The initial call will look something like this (below).
numPairs = PCRSLatLongsEnRoute(myTrip, NULL, 0)
It is very important to pass in a NULL pointer to the second argument and zero to the third argument. This tells the PC*MILER Rail software to go out and gather the count of pairs. 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 API request, you need to allocate memory for the array of Lat/Long Coordinates. So, if the API returns 10 for the number of pairs, you will need a “C” statement similar to this:
double* coordArray = new double[2*numPairs]
3. After allocating memory, you are now ready to make your final request to get the array of lat/longs:
srvRet = PCRSLatLongsEnRoute(myTrip, coordArray, numPairs)