Starting and Stopping the Rail Server

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. Do not repeatedly open and close the server—open the server on startup and close the server on exit.

Note on error message reporting: 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 0 indicates success.
• A return value less than 0 indicates an error, with the return value being the error code itself.
• This return value (if less than zero) can 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, except for error handling code.

Prototype:

HRESULT PCRSInitSrv(const char *callerName, const char *iniFile)

• callerName is the (arbitrary) name of the calling application.
• iniFile is the path and name of the PCRSRV.INI file.

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.

Prototype:

HRESULT PCRSCleanupSrv()

Example: Starting and Stopping the Server

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.