Trip Administration

Create State or Country Lists

The functions below can be used to build a list of states and countries where data is available in PC*Miler:

• PCMSStateList returns the number of U.S. states, Canadian provinces, Mexican estados, and Central American and Caribbean countries included in the North America region.
• PCMSStateListItem prints the name and state code for the given index into the user-supplied buffer, delimited by tabs.
• PCMSCountryList returns the number of countries in the region entered.
• PCMSCountryListItem populates a buffer with the name and FIPS country code for a country.

Check Software Information and Connections

The function PCMSAbout returns the PC*Miler Connect version number, the current number of active PC*Miler Product users on the network, the maximum number of simultaneous users that are allowed with the current license, and the data version.

Initialization and Cleanup

Before your application can use any API functions, it must connect to and initialize PC*Miler Connect. After it finishes, it must shut down the server connection. You must close the server before your application exits or Windows won’t free the resources used by the DLL, nor will it unlock the current license.

TIP: Do not repeatedly open and close the server. Open the server on startup and close the server on exit. The server should be opened only once per application instance.

Open Connect

PCMSOpenServer will initialize PC*Miler Connect, check your PC*Miler licenses, load the PC*Miler highway database, and ready the engine for routing calculations. PCMSOpenServer must be called before any other functions in PC*Miler Connect, with the exception of error handling codes.

Close Connect

PCMSCloseServer must be the last function called when you’re finished using the engine. PCMSCloseServer will destroy any remaining trips you haven’t deleted with PCMSDeleteTrip, and unload the PC*Miler highway database. After calling PCMSCloseServer, you must call PCMSOpenServer again to reinitialize PC*Miler Connect before calling any other functions.

Example: Starting and Stopping Connect

void UsePCMILER
{
  PCMServerID server;
  /* Pass neither instance handle, nor parent window */
  server = PCMSOpenServer(0, 0);
  /* Do other processing here. */
  /* Use the server: calculate trips, etc.... */
  /* Shut down the server */
  PCMSCloseServer(server);
}

For efficiency, you should start Connect when your application initializes and shut it down when your application exits, rather than every time you want to compute a route. Also, you should only need to open one connection per application. Once the engine is initialized, you can then calculate distances, create trips, and generate reports.

Set or Get the Region

The default region in PC*Miler Connect is North America. If PC*Miler Worldwide data is licensed and installed, you can use the PCMSNewTripWithRegion function to create a new PC*Miler trip within a specified world region, and the PCMSGetDefaultRegion function to view the default region.

To get information on the number of regions in the data, use PCMSGetNumRegions. PCMSGetRegionName returns the name of the region.

Ways to change the default region include:

• Editing the PCMSERVE.INI file
• Changing the region setting in the PC*Miler user interface

If using the PCMSERVE.INI to change a setting, the change will only take effect after the application is restarted. Changes made in the .INI file take precedence over settings in the PC*Miler user interface.

Error Handling

Error handling routines are the only PC*Miler Connect functions callable without a server ID. They can be used to diagnose why the engine didn’t initialize.

Other PC*Miler Connect functions return -1 on errors. To find out what went wrong with the function call:

• PCMSGetError determines the cause of the error. It returns the number of the last error the engine caught.
• PCMSGetErrorString gets the associated error text from PC*Miler Connect’s resources.
• PCMSGetErrorEx generates a string indicating at which stop in the trip the error occurred.

Mexican Postal Codes

U.S. ZIP codes and Mexican postal codes share a similar format. PCMSERVE.INI settings and an API are available to ensure the entered ZIP/postal code matches the desired location. Settings in the PCMSERVE.INI (found in the C:\Windows folder) are described below.

Using the .INI Setting

UseUSPostCodes=True/False

UseMexPostCodes=True/False

The possible setting combinations are:

• UseUSPostCodes=False and UseMexPostCodes=False – Defaults to the U.S. ZIP with no routing to Mexican postal codes.
• UseUSPostCodes=True and UseMexPostCodes=False – Same as above.
• UseUSPostCodes=True and UseMexPostCodes=True – Defaults to the U.S. ZIP, must pass an estados code to get Mexican location (e.g. “50510, EM”).
• UseUSPostCodes=False and UseMexPostCodes=True – Only Mexican postal codes are available; in the U.S. only city-state pairs will be valid (e.g. “Chico, CA”).

Using the API

The PCMSZipCodeOption function can be used in the same way to select whether to use U.S. or Mexican postal codes.

TIP: An API call overrides both the PCMSERVE.INI setting and the setting in the PC*Miler user interface (this is true for all APIs).

Set the NL Abbreviation

The function PCMSSetNLAbbreviation allows you to choose whether to set the abbreviation ‘NL’ to geocode to Newfoundland and Labrador locations in Canada or to Nuevo Leon locations in Mexico. Use MX for Nuevo Leon, or CN for Newfoundland and Labrador.

This can also be set as a default value in the [Options] section of the .INI file.

Convert Special Characters

PC*Miler Connect includes functions that convert strings containing diacriticals such as accents and stress marks to usable characters. These functions work only for special characters on a standard keyboard; PC*Miler does not handle Japanese or Chinese characters. To work with these characters, use PCMSLookUp.

PCMSAnglicize returns the stop name string without special characters. For example, if geocoding the address “Charny, QC; 1021 École” fails, you should consider calling this function first.

PCMSSetAnglicize is a global setting that turns the conversion of diacriticals on or off. Some environments and compilers do not have a simple way to convert UTF-8 to a string that is usable or properly displays on a screen or printer. Using this function can alleviate problems and crashes that are caused by strings that are unusable due to diacriticals. This setting can also be controlled in the PCMSERVE.INI file.

[ConnectOptions]
Anglicize=true

PC*Miler Connect functions affected by PCMSSetAnglicize

Convert Currency

The function PCMSSetExchRate enables accurate toll cost calculation in Canadian dollars. Users who are working with PC*Miler Connect without the PC*Miler user interface can use this function to change the default exchange rate between U.S. and Canadian dollars. (The Tolls add-on must be license and installed.)