Before your application can use any server functions, it must connect to and initialize the DLL. 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. But do not repeatedly open and close the server. Open the server on startup and close the server on exit.

A note on error message reporting from PC*MILER Rail-Connect:  All functions in the server API return the status of the called function via a Win32 return type of HRESULT, which is a 4 byte integer (a.k.a. long) in the current Windows implementation. A return value of zero indicates success, a return value less than zero indicates an error, with the return value being the error code itself.  This return value (if less than zero) can then be passed to the server utility function PCRSGetErrorString() for a text description of the most recently encountered server error.

The function PCRSInitSrv() will initialize the DLL, check your PC*MILER Rail licenses, load the PC*MILER Rail rail database, and ready the engine for routing calculations. PCRSInitSrv() must be called before any other functions in the DLL, with the exception of error handling code. The prototype for the function PCRSInitSrv() is:

PCRSCleanupSrv() must be the last DLL function called when you’re finished using the server.  This function will destroy any remaining trips that you haven’t deleted with PCRSDeleteTrip(), and unload the PC*MILER Rail rail database. After calling PCRSCleanupSrv(), you must call PCRSInitSrv() again to reinitialize the DLL before calling any other functions. Here is the prototype:

HRESULT PCRSCleanupSrv()

This is how your application should start and stop the server engine:

#define BUFLEN 256

int DemoRun()
{
   HRESULT srvRet;
   char buffer[BUFLEN];

   /* Start the server; error handling block is shown here */ 
   if (0 != (srvRet = PCRSInitSrv("MyApp", "C:\\pcrwin25\\pcrsrv.ini")))
   {
      // Server Init Error:
      if (0 > PCRSGetErrorString(srvRet, buffer, BUFLEN, NULL))
         printf ("Server Err: (Can’t get error string)");
      else
         printf ("Server Err:  %s", buffer); 
return srvRet;
   }

   /* Do other processing here. */
   /* Use the server: calculate trips, etc.... */

   /* Shut down the server */
   if (0 != (srvRet = PCRSCleanupSrv()))
   {
      // Server Shutdown Error:
      <error handling block, as above>
   }
   return 0;
}

For efficiency, you should start the server when your application initializes and shut down the server 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, as each connection can manage up to eight simultaneous trips. 

Once the server is initialized, you can then calculate distances, create trips, and generate reports, or create a map window and perform mapping.