Looking Up Place Names and Railroads (Geocoding)

Several functions are included in PC*Miler Rail-Connect that support looking up places and railroads.

Geocode Lookup

HRESULT PCRSGeoLookup(Trip trip, char *geoName, char *geoChar, char *rrIn, int *numMatches)

PCRSGeoLookup() finds a list of matching places and returns how many match your input. You can check each item in the list for a matching name or display the list in your own UI. Input names can contain the meta-character * to force partial matches. For example, HOU* TX returns all places matching HOU in Texas. The railroad (rrIn) is optional and can be used to narrow the search to stations on a specific rail carrier. If rrIn is NULL, it is ignored.

Input names can be any of the geocode types (station name/state, SPLC, FSAC, ERPC, Rule260). The argument geoChar denotes which type is being given (S = SPLC, E = ERPC, C = City/State (station name), F = FSAC, R = Rule260). The number of matches found is returned in the pointer numMatches. Input places can be mapped to other places in the PC*Miler Rail network via overrides, if necessary.

Retrieving Matches

HRESULT PCRSGetGeoMatch(Trip trip, int which, char *buffer, int bufSize, int *pNumChars)
HRESULT PCRSGetNumGeoMatches(Trip trip, int *numMatches)

Once you’ve seeded the trip with matching cities, use PCRSGetGeoMatch() to retrieve each matching place. Pass the index of the desired match and a buffer to store the information. The name stored in the buffer (first 22 chars) is the place name as PC*Miler Rail knows it and should be the name passed to PCRSAddStop().

PC*Miler Rail names are 22-character station/state names, including the NULL terminator. The buffer should be long enough to contain the entire name. Additional information (such as SPLC and FSAC) will be included in the buffer where possible.

Geocode Lookup Example

#define BUFLEN 25
char buffer[BUFLEN];
int matches, numChars;
HRESULT srvRet;

/* Lookup all cities that match */
srvRet = PCRSGeoLookup(myTrip, "HOU* TX", "C", NULL, &matches);
printf("%d matching cities to 'HOU* TX'\n", matches);

/* Show all the matching cities */
for (i = 0; i < matches; i++) {
  PCRSGetGeoMatch(trip, i, buffer, BUFLEN, &numChars);
  printf("[%s]\n", buffer);
}

Railroad and Junction Lookup

HRESULT PCRSRRLookup(Trip trip, char *geoName, char *geoChar, int *numMatches)
HRESULT PCRSJunctionLookup(Trip tripID, char *rrin, char *rrOut, int *numMatches)
HRESULT PCRSGetRRMatch(Trip trip, int which, char *buffer, int bufSize, int *pNumChars)
HRESULT PCRSGetJunctionMatch(Trip tripID, int which, char *buffer, int bufSize, int *pNumChars)

The lookup functions work like the geocoding functions described above. PCRSRRLookup() and PCRSJunctionLookup() return lists of matching railroads and junctions, respectively, and return how many match your input. The number of matches found is returned in the pointer numMatches. Then, use PCRSGetRRMatch() or PCRSGetJunctionMatch() to retrieve each matching railroad or junction. Pass the index of the desired match and a buffer to store the information.

Geocode Conversion

HRESULT PCRSConvertGeoCode(char *geoName, char *geoCharFrom, char *geoCharTo, char *rr, char *buffer, int bufsize, int *pNumChars)

PCRSConvertGeoCode() is a geocode conversion function. The arguments geoCharFrom and geoCharTo are one of the following: (S = SPLC, E = ERPC, C = City/State (station name), F = FSAC, R = Rule260).

RR information is required for conversions to and from the FSAC code.

Geocode Conversion Example

#define BUFLEN 256
char buffer[BUFLEN];
if (0 == (srvRet = PCRSConvertGeoCode("384188", "S", "C", "", buffer, BUFLEN, NULL))) {
   printf("Conversion: \"384188\" (SPLC --> Station/ST)\n");
   printf("Result: %s\n", buffer);
}

/* ERPC code needs to be followed by state code with or without a blank */
if (0 == (srvRet = PCRSConvertGeoCode("GRUMBLER NT", "E", "C", "", buffer, BUFLEN, NULL))) {
   printf("Conversion: \"GRUMBLER NT\" (ERPC --> Station/ST)\n");
   printf("   Result : %s\n", buffer);
}

/* RR is required to and from the FSAC code conversion */
if (0 == (srvRet = PCRSConvertGeoCode("ABEE IN", "C", "F", "EVWR", buffer, BUFLEN, NULL))) {
   printf("Conversion: \"ABEE IN\" (Station/ST --> FSAC, RR: EVWR)\n");
   printf("Result: %s\n", buffer);
}

if (0 == (srvRet = PCRSConvertGeoCode("ADA", "R", "S", "", buffer, BUFLEN, NULL))) {
   printf("Conversion: \"ADA\" (R260 --> SPLC)\n");
   printf("Result: %s\n", buffer);
}

Example Output

Conversion: "384188" (SPLC --> Station/ST)
Result: LORENZO             IL
Conversion: "GRUMBLER NT" (ERPC --> Station/ST)
Result: GRUMBLER            NT
Conversion: "ABEE IN" (Station/ST --> FSAC, RR: EVWR)
Result: 70328
Conversion: "ADA" (R260 --> SPLC)
Result: 628240