PMX 1.2 Documentation
Last updated 1/22/08

The online version of this document is available at http://pmx.mile.com/docs.

The PMX (Prophesy Mileage Exchange) is a tool that allows third-party developers on a variety of operating platforms utilize Prophesy's industry-preferred mileage and routing engine to power mileage and routing calculations for their applications.

About This Document
This document is designed to help you install, configure, and make use of the PMX. Please read it carefully and take note of the information that applies to your situation. Also, please note that this document is a continually being updated and changed, so be sure to check back from time to time. Please notify us by email at pmx@mile.com with any errors you may find.

Basic Overview
The PMX resides on a Windows 2000/2003 Server attached to your LAN and provides your applications with access to the Prophesy 32-bit Mileage & Routing and FuelLogic systems. The PMX can be accessed in three different ways (each providing the same functionality), giving developers a great deal of flexibility.

Access via HTTP:
You may access the PMX by sending an HTTP request by either a GET or POST (with the proper parameter values) to the PMXCom.asp script on your Server. Your request will be processed and output files containing your mileage and routing reports (or fuel solutions) will be created. Using this method you are able to specify your mileage and routing parameters, your fuel solution parameters, and your output files. This method of connecting to the PMX requires that you are running IIS 5.0 or higher on your Windows server. The Fuel file (which gets installed to your PMX program directory) needs to be placed in your System32 folder. Typically this folder is located at c:\windows\system32.

Access via PMXPoll:
In addition to the HTTP request method, the PMX installs an executable file (PMXPoll.exe). The PMXPoll application will scan a directory of your choosing on the server for input files that you specify. When it finds an input file it then processes it, creates a mileage and routing report (or a fuel solution) and writes this output as files at a location you specify. The PMXPoll.exe application also accepts command line input, and will process that input into output just as its file scanning feature (mentioned above) does.

The different ways that you can connect to the PMX are described in their appropriate sections below.

What You Will Need
Below is a list of requirements for running the PMX on your LAN:

  • Server software configuration: Microsoft™ Windows 2000 Server; IIS (Internet Information Server) 5.0 or higher (if you wish to use the PMX via the HTTP request method)
  • Server hardware configuration: Pentium 1.0 GHZ or higher; 1024 MB RAM minimum; 500 MB free hard disk space recommended.
  • The server must be connected to your LAN and be able to communicate with it via TCP/IP.
  • A PMX installation CD from Prophesy.

    • Installation/Configuration

  • Login to your server as Administrator or equivalent.
  • If you are going to be utilizing the Fuel Solution portion of the PMX, install FuelLogic from the FuelLogic CD and reboot when prompted.
  • When the server has rebooted, run setup.exe from your PMX installation CD to begin the install.
  • By default the setup program will install the PMX to c:\program files\prophesy\pmx (unless you specify another directory).
  • Reboot your server.
  • The PMX has now been installed. Please refer to the sections below for instructions on using the different methods of connecting to the PMX.
    • Using the PMX: HTTP Request Method

    Requirements for HTTP Request Method:
    Your 2000/2003 Server must be running IIS 5.0 or higher to connect to the PMX using this method.

    The HTTP request method sends a request for a mileage or fuel solution to the PMX via HTTP.

    You may use POST or GET to submit the 6 required values to the PMXCom.asp script on the web server where the PMX was installed.

    The names of the values you must submit are: StopList, ParameterList, ErrorFile, and OutputFile, FuelSolution, FuelParameters, OutputType, and ReturnType.

    For an example of what these parameters and their values look like you should refer to the PMGComTest.asp file included in your installation.

    StopList
    The StopList parameter is the list of stops that make up the route you would like to run. The PMX will accept three different types of stops in any combination. Each stop in your StopList must be separated by an asterisk *.

  • City/State pair - City, two-character state abbreviation. (e.g. Boston, MA)
  • Zip Code - Five digit U.S. zip codes (e.g. 06002)
  • Latitude/Longitude - Exclamation point followed by the latitude and longitude (in decimal form). An optional description of the point may be added after the longitude between two tildes. The description may be up to 25 characters long (e.g. !42.0342 72.1184 ~Point One~). Note that the empty description ~~ is invalid. Instead, leave out the tildes altogether or place a space between them.
    • City names must follow the Prophesy naming conventions as follows:
  • All city names consisting of an ordinal direction (North, South, East, or West) as the first word in the name, followed by one or more other words will have the direction abbreviated to a single letter (N, S, E, or W). For example, North Haven, CT becomes N Haven, CT, but Easthampton, MA is not abbreviated because the name is a single word.
  • Similarly, cities consisting of two or more words where the first word is Fort, Mount or Saint will have the first word abbreviated Ft, Mt, or St. So, Fort Smith, AR becomes Ft Smith, AR, etc.
  • Finally in the case where there are two or more locations in the same state that have the same name, such as Bethlehem, PA, the ambiguity is resolved by appending a space, then the County name in parentheses, after the city name for all but the largest of the locations. Thus, Bethlehem, PA is the city just east of Allentown, whereas Bethlehem (Clearfield), PA is the small town in central Pennsylvania, northwest of Altoona.
  • Here are some example StopList values:
    Boston, MA*Hartford, CT
    Boston, MA*01027
    Boston, MA*01027*Atlanta, GA*!42.0342 72.1184

    • ParameterList
    The ParameterList parameter is the space-delimited list of options you would like applied to your PMX request. The available options are listed below.

    Option Description
    -a[###.##] Mileage adjustment percentage. Default 100.00, valid range 50.00 to 200.00.
    -b[y|n] Allow/disallow national border crossings. Default is disallow.
    -[c|p|u] Mileages produced are rating ("commercial"), driving ("practical") or user rating. Default is driving.
    -cm[#.###] Cost per mile. Applies only to driving mile calculations.
    -h[##.#] Minimum clearance along route in feet, rounded up to the next .5 feet. Default is 12.0.
    -[km|mi] Distance in kilometers or miles. Default is miles.
    -m[c|m|p] Stop entry mode. Central point, multi-point, or point to point. Default is multi-point.
    -ms[##] Reduce maximum speed to. Default is 65.
    -o[|b|f|r] Route optimization. None, one way best, one way fixed, or round trip. Default is none.
    -o[a|c|p] Mileage type used for optimization. Air miles, rating miles, or driving miles. Default is air miles.
    -p[d|t] Practical routes chosen by shortest distance or least time. Default is least time.
    -r[a|b|d|s|t] Report type. State breakdown only, single line plus state breakdown, detail (the default), summary, or single line per point pair.
    -sp Show parameters on report. Applies only to driving mile calculations.
    -s[s|w] Season. Summer or winter. Default is summer.
    -ta[#] Toll road avoidance factor. Scale 0 to 9. It is not a linear scale, use with care. Default is zero.
    -t[y|n] Enable or disable commercial vehicle restrictions. Default is -ty (enable restrictions).

    An example ParameterList value might look like:

    -pt -ty -mm

    ErrorFile
    The ErrorFile parameter contains the fully-qualified path to the file you want the PMX to create in the event that it cannot process your request. A valid ErrorFile value could be c:\error.txt or d:\errorfile.txt, etc.

    OutputFile
    The OutputFile parameter contains the fully-qualified path to the file you want the PMX to create which will contain your mileage report or fuel solution. A valid OutputFile value could be c:\out.txt or d:\outfile.txt, etc.

    Important: If you are requesting a fuel solution you must only specify the path and file name of the output file. Do not include the file extension. For example, c:\outfile, etc. A fuel solution results in 4 output files, which will automatically be given the following extensions: .FDM, .FRF, .FMC, .RPT. For the ErrorFile parameter, you always supply the full path and file name (including the extension).

    FuelSolution
    If you are requesting a fuel solution this parameter must be set equal to the number 1. Otherwise , it may be excluded or set to the number zero.

    FuelParameters
    This parameter is passed in as a pipe "|" delimited string of values. The values that make up this string, in this exact order, are:

    network id|report type|starting fuel level|tank capacity|minimum purchase|reserve amount|ending fuel level|average mpg|stop fee|always fill

    What the fuel parameters mean:

    Example FuelParameters value:

    0|0|150|250|80|50|100|5.5|1.0|f

    OutputType
    There are 3 valid values for this parameter.

    1 = Default output. Full report based on your ParameterList specifications.
    2 = Mileage only. Only a mileage total for the trip is returned.
    3 = Mileage and Time only. Mileage total and hours/minutes total is returned.

    ReturnType
    There are 2 valid values for this parameter.

    1 = Output is written to the OutputFile you have specified.
    2 = Output returned but not written to a file.
    3 = Output is both returned and written to the OutputFile specified.

    Submitting Multiple Trips per HTTP Request
    You may submit specify more than 1 trip in your StopList parameter by separating individual trips with the pipe "|" character. Since the StopList parameter is the only parameter that can be submitted with more than 1 value, the same ParameterList value will be applied to each trip in your StopList.

    If multiple trips are specified in the StopList, the PMX will sequentially number the resulting output/error files, starting with the number zero. This number will be appended to the end of the file name and extension you have specified in the OutputFile parameter.

    For example, you would specify 3 trips in your StopList parameter in this fashion:

    Boston, MA*Hartford, CT*New York, NY|Miami, FL*Atlanta, GA|Windsor, MA*Buffalo, NY*Boston, MA
    Assuming you had specified c:\temp\output.txt as your OutputFile parameter, the PMX would create the following output files:
    c:\temp\output.txt.0
    c:\temp\output.txt.1
    c:\temp\output.txt.2
    Here is an example of a 3 trip StopList that contains an error with the second stop:
    Boston, MA*Hartford, CT*New York, NY|Miamix, FL*Atlanta, GA|Windsor, MA*Buffalo, NY*Boston, MA
    Assuming your had specified c:\temp\output.txt as your OutputFile parameter, and c:\temp\error.txt as your ErrorFile parameter, the PMX would create the following output files:
    c:\temp\output.txt.0
    c:\temp\error.txt.1
     c:\temp\output.txt.2
    If you are requesting a Fuel Solution, remember that the PMX automatically applies the file extensions .RPT, .FDM, .FRF, and .FMC to the 4 files it creates for a Fuel Solution. For a Fuel Solution using the same StopList listed above, and assuming you had specified c:\temp\fueloutput as your OutputFile parameter, the PMX would output the following files:
    c:\temp\output.0.RPT
    c:\temp\output.0.FDM
    c:\temp\output.0.FMC
    c:\temp\output.0.FRF
    c:\temp\output.1.RPT
    c:\temp\output.1.FDM
    c:\temp\output.1.FMC
    c:\temp\output.1.FRF
    c:\temp\output.2.RPT
    c:\temp\output.2.FDM
    c:\temp\output.2.FMC
    c:\temp\output.2.FRF
    Using the PMX: PMXPoll Request Method
    The PMXPoll request method functions by having the PMXPoll.exe application (which can be installed as a service) scan a directory on the Server for input files. When it locates one or more valid input files it then processes them to create mileage reports and/or fuel solutions. The reports and/or fuel solutions are created as output files as defined in the pmxpoll.cnf file.

    The PMXPoll request method is an ideal way to connect to the PMX provided that 1 of these 2 conditions are true:

    Installing/Running PMXPoll
    PMXPoll can be run as a Windows service or as a normal application. To install PMXPoll as a service, you will need a copy of SrvAny.exe (found in the Windows Server Resource Kit). To use PMXPoll as a regular application just run PMXPoll.exe.

    Configuring PMXPoll
    To customize PMXPoll, you may edit the values in the pmxpoll.cnf file located in your PMXPoll program directory. If you haven't run the PMXPoll.exe application yet, or haven't started PMXPoll as a service, there won't be a pmxpoll.cnf file. To have PMXPoll generate a default pmxpoll.cnf file, run PMXPoll.exe. It is required that you exit and restart PMXPoll (or stop and start the service) after changes have been made to the pmxpoll.cnf file -- otherwise your changes won't take effect.

    The default pmxpoll.cnf file looks like this: 

    ###
# PMXPoll.cnf
# Created: 2/23/07 4:05:26 PM
###

###
# File Paths. Please specify the file paths for input, output, and error files.
# Please note that the file paths will just be the path to the file and must
# not contain the file name itself.
###

input-file-path = c:\temp\test
output-file-path = c:\temp\test
error-file-path = c:\temp\test

###
# File Names. Please specify the file names for input, output, and error files.
# The file names will be the name of the file without the file extension.
###

input-file-name = input
output-file-name = output
error-file-name = error

###
# File Extensions. Please specify the file extensions for the input, output, and
# error files. The file extensions will be the full extension preceeded by a
# period.
###

input-file-extension = .in
output-file-extension = .out
error-file-extension = .err

###
# Polling Frequency.
# This is the number of seconds between each poll by PMXPoll. If you wanted the
# PMXPoll to poll every second you would set it to 1. If you wanted it to poll
# every 1/2 second you would set it to .5, etc.
###

polling-frequency = 0.5

###
# Files to Batch.
# This is the number of files which PMXPoll will attempt to 'collect' before it
# begins processing them. Setting this to 1 would mean that PMXPoll would
# process each file as it finds it. Setting this to 10 means that PMXPoll would
# look for up to 10 files before it would begin processing them.
###

files-to-batch = 50

###
# Output Type.
# There are 3 possible values. 1 = default output, 2 = just miles, 3 = just miles
# and time.
###

output-type = 1

###
# Output File Type.
# This value only comes into play if you have specified a values of 2 or 3 for your
# output-type. A value of 1 means that in the case of a multitrip input file the
# PMX will create an individual output file for each trip. A value of 2 means that
# the PMX will create a single output file with the output for each trip
# on single lines.
###

output-file-type = 1

    .cnf File Fields/Values

  • input-file-path, output-file-path, error-file-path
    These values to be the paths where these files will ultimately reside. Each path needs to be in the form of X:\path (with no trailing slash), where X represents your drive appropriate drive letter.
  • input-file-name, output-file-name, error-file-name
    These values need to be the name by which files of each type will be recognized. These values are just the file names and must not contain a path or file extension. Example: input or output.
  • input-file-extension, output-file-extension, error-file-extension
    These values need to be the file extension of the given file (including the leading period). Example: .in or .out.
  • polling-frequency
    This value represents the number of seconds between each input file scan peformed by PMXPoll. This value must be between 0.25 and 60. A value of 0.25 would cause PMXPoll to scan for input files 4 times per second, while a value of 60 would cause PMXPoll to scan once a minute.
  • files-to-batch
    This value represents the number of files PMXPoll should attempt to "gather" before it begins to process them. If set to 50, PMXPoll would gather up to 50 files before beginning to process them.
  • output-type
    There are 3 possible values for output-type. 1 = default output (mileage w/routing instructions), 2 = just the mileage total, 3 = just the mileage total and the time total.
  • output-file-type
    This parameter is only valid if you have specified more than 1 trip in your input file. When this parameter is set to 1 the PMX will create an individual, sequentially-numbered output file for each separate trip. When this parameter is set to 2 the PMX will create a single output file with the output for each trip on a separate line.

    • Input File Format
    For PMXPoll to successfully process your input file, it must be in the correct format for the type of output you're requesting.

    For Mileage Requests:
    Each input file will consist of 2 lines, with each line ended with the carriage return and line feed characters. (ASCII 13 & 10). The first line will be the mileage parameters, and the third line will be the list of stops.

    For Fuel Solution Requests:
    Each input file will consist of 3 lines, with each line ended with the carriage return and line feed characters. (ASCII 13 & 10). The first line will be the fuel parameters, the second line will be the mileage parameters, and the third line will be the list of stops.

    Fuel Parameters
    This is a comma-delimited list using these values in the following order: Network Name, Report Type, Starting Fuel Level, Tank Capacity, Minimum Purchase, Reserve Amount, Ending Fuel Level, Miles Per Gallon, Stop Fee, Always Fill Tank
  • Network Name - The name of the fuel network or "" to use all truck stops.
  • Report Type - 0 = Text, 1 = Rich Text Format, 2 = HTML
  • Starting Fuel Level - Starting number of gallons
  • Tank Capacity - Maximum number of gallons
  • Minimum Purchase - The minimum number of gallons to be purchased at a stop
  • Reserve Amount - The lowest number of gallons the fuel tank is allowed to reach before stopping for fuel
  • Ending Fuel Level - Ending fuel inventory
  • Miles Per Gallon - Miles per gallon for the vehicle (format: #.#)
  • Stop Fee - Additional fee for stopping at a truck stop (format: #.#)
  • Always Fill Tank - Whether or not to always fill the tank to capacity when fueling (format: T or F)

    • Calling PMXPoll.exe With Command Line Parameters
    It is also possible to call PMXPoll.exe and specify up to five command line parameters that will produce either a fuel solution or a mileage report.

    Each command line parameter is separated by a dollar sign $.

    The order of the command line parameters for a fuel solution is:

    Fuel Parameters$Mileage Parameters$Stops$Output File (Path & File Name w/o File Extension)$Error File (Path & File Name w/File Extension)
    An example of the command line (including the executable and the command line parameters) for a fuel solution is:
    pmxpoll.exe 2,2,150,250,80,25,100,5.5,0.0,f$-p -by -pd$boston, ma*miami, fl$c:\temp\output$c:\temp\error.txt
    The order of the command line parameters for a mileage report is:
    Mileage Parameters$Stops$Output File (Path & File Name w/ File Extension)$Error File (Path & File Name w/File Extension)
    An example of the command line (including the executable and the command line parameters) for a mileage report is:
    pmxpoll.exe -p -by -pd$boston, ma*miami, fl$c:\temp\output.rpt$c:\temp\error.txt
    Help
    For help with any issues regarding installing, configuring, or using the PMX please send email to pmx@mile.com.
    ©2008 Prophesy Transportation Solutions, Inc. All rights reserved.