transportation modeler 9.0.0.0 distance engine user guide

Distance Engine User Guide JDA® Transportation Modeler

Release 9.0.0.0

Legal notice Rights to the content of this document

Copyright © 1995-2015 JDA Software Group, Inc. All rights reserved.

Printed in the United States of America.

Reproduction of this document or any portion of it, in any form, without the express written consent of JDA Software Group, Inc. ("JDA") is prohibited.

These materials are protected by the Copyright Act of 1976, as amended, as an unpublished work and the foregoing notice and legend shall not be deemed to constitute publication or an intent to publish thereunder. These materials are proprietary and confidential information of JDA and may be disclosed and used only as authorized in a signed, written agreement controlling such disclosure or use.

The fact that a particular name or logo does not appear on this notice does not constitute a waiver of any intellectual property rights that JDA has established in any of its products, feature or service names, or logos.

Modifications to the contents of this document

JDA reserves the right, at any time and without notice, to change these materials or any of the functions, features, and specifications of any of the software described herein. JDA shall have no warranty obligation with respect to these materials of the software described herein, except as provided in the JDA software license agreement with an authorized licensee.

Rights to the functionality of this document

Described functionality may not be available as part of a customer's maintenance agreement or the JDA Investment Protection Program. New features and products are subject to license fees. JDA warranty and support obligations apply only to the documentation as delivered by JDA, and are void if the documentation is modified or supplemented by anyone other than JDA. This document embodies JDA valuable trade secrets, is confidential to JDA, and must be kept in confidence and returned upon the expiration or termination of your JDA license agreement. You are not permitted to copy, extract, distribute, transfer, or share the contents of this document with anyone except authorized individuals within your organization.

Technical documentation

NOTICE: This design or technical documentation is supplied as a courtesy only and does not form part of the "Documentation" as defined in your JDA license agreement. This design or technical documentation is supplied in the English language only and is supplied "as is" and without warranties. JDA, at its discretion, may choose to offer this document in additional languages, but is under no obligation to do so. JDA undertakes no obligation to update this design or technical documentation.

Patents

This product may be protected by one or more United States and foreign patents. Please see the JDA Patents website (http://jda.com/JDAPatents).

http://jda.com/JDAPatents

Provide feedback on this document JDA values your opinion and strives to ensure that the documentation you receive is clear, concise, and provides the appropriate information required for you to use each JDA application efficiently.

If you would like to provide feedback on this document, you can submit your questions or suggestions to the JDA Documentation Management team (mailto:[email protected]) and they will be forwarded to the appropriate development teams for review and consideration in a future release.

mailto:[email protected]

Table of Contents

Chapter 1. Introduction ................................................................................................... 1 Related documentation ............................................................................................... 1 Get additional help from JDA ....................................................................................... 1

Chapter 2. Distance engine overview............................................................................... 3 Address validation and geo-coding ............................................................................... 3 Distance engine distance and time calculation ................................................................ 4 Distance engine creation tool ....................................................................................... 4

Raw data files ................................................................................................... 4 Input files ........................................................................................................ 4 Map files .......................................................................................................... 4 Output tables ................................................................................................... 5 Wizard files ...................................................................................................... 5 Access database ............................................................................................... 5 Executable files ................................................................................................ 5

Code integration to third party distance provider ............................................................ 5

Chapter 3. Distance engine creation wizard..................................................................... 7 Run the wizard with Transportation Planner ................................................................... 7 Run the wizard with Transportation Modeler .................................................................. 7 Distance engine data .................................................................................................. 7 The distance engine creation wizard ............................................................................. 8 Interview questions ................................................................................................... 8

Question 1: Location data source ........................................................................ 9 Question 2: Engine type ..................................................................................... 9 Question 3: Distance data source ...................................................................... 10 Question 4: Override data source ...................................................................... 10 Question 5: Node selection method ................................................................... 11 Question 6: Location aliases ............................................................................. 11 Question 7: Data preparation walkthrough .......................................................... 11 Question 8: Data validation .............................................................................. 11 Question 9: Advanced settings .......................................................................... 12 Interview conclusion ........................................................................................ 12 Advanced settings ........................................................................................... 12 Session file .................................................................................................... 16 Batch file ....................................................................................................... 17

Raw data preparation ............................................................................................... 18 Prepare your locations in Access ........................................................................ 18 Prepare your locations in flat files ...................................................................... 18 Prepare your nodes in Access............................................................................ 19 Prepare your nodes in flat files .......................................................................... 19 Automatically select nodes from Access locations ................................................. 20 Automatically choose nodes from flat file locations ............................................... 20 Prepare your distance road file in Access ............................................................ 20 Prepare your distance road file in flat files .......................................................... 21 Prepare your distance overrides in Access ........................................................... 22 Prepare your distance overrides in flat files ......................................................... 22 Access data preparation complete ..................................................................... 22 Flat file data preparation complete..................................................................... 23

Data validation ........................................................................................................ 23

To display validation data ................................................................................. 24 Validate the data ............................................................................................ 24 Country data validation .................................................................................... 24 State data validation ....................................................................................... 24 Location data validation ................................................................................... 24 Postal data validation ...................................................................................... 25 Alias data validation ........................................................................................ 25 Node data validation - manually selected nodes ................................................... 25 Node data validation - automatically selected nodes ............................................. 25 Roads in the same country data validation .......................................................... 25 Roads in different countries data validation ......................................................... 25 Override distance data validation ...................................................................... 26 Road distance data validation - distance provider ................................................. 26 Data validation complete .................................................................................. 26

Generate the distance engine .................................................................................... 26 Start process and status dialog ......................................................................... 26 Completion .................................................................................................... 27

Chapter 4. File and table formats .................................................................................. 28 Distance creation Access database ............................................................................. 28

COUNTRIES table ............................................................................................ 28 LOCATIONS table ............................................................................................ 29 DISTANCES table ............................................................................................ 29 LOCATION_ALIASES table ................................................................................ 30 GEOVALIDLOCATIONS table ............................................................................. 31 NODELOCATIONS table .................................................................................... 31 OVERRIDEDISTANCES table ............................................................................. 32 ROADDISTANCESWITHDIFFORIGDESTCOUNTRY table .......................................... 33 ROADDISTANCESWITHSAMEORIGDESTCOUNTRY table ......................................... 34

Distance creation raw data flat files ............................................................................ 35 Countryraw.txt file .......................................................................................... 35 Geovalidlocationraw.txt file............................................................................... 36 Nodelocations.txt ............................................................................................ 36 Roaddistancerawsamecountry.txt ...................................................................... 37 Roaddistancerawdifferentcountry.txt .................................................................. 37 Locationaliasraw.txt ........................................................................................ 38

Mapping files ........................................................................................................... 39 Distance Engine input files ............................................................................... 39 Distance Engine output tables ........................................................................... 46

Chapter 5. API description ............................................................................................. 49 Structure representing the location information ............................................................ 49 Server initialization functions ..................................................................................... 49

GEOCRTOpenDistanceTimeServer ...................................................................... 49 GEOCRTCloseDistanceTimeServer...................................................................... 49

Error logging functions ............................................................................................. 50 GEOCRTGetError ............................................................................................. 50 GEOCRTGetErrorString .................................................................................... 50

City latitude/longitude conversion functions ................................................................. 50 GEOCRTLocationNameToLatLong ....................................................................... 50 GEOCRTLatLongToLocationName ....................................................................... 51

Trip initialization functions ........................................................................................ 51 GEOCRTNewTrip ............................................................................................. 51 GEOCRTDeleteTrip .......................................................................................... 51

Distance/time calculation function .............................................................................. 51

GEOCRTCalcDistanceandTime ........................................................................... 51

Chapter 6. Java distance interface ................................................................................. 53 PC Miler distance engine ........................................................................................... 53 Interface parameters ............................................................................................... 53 Interface definition .................................................................................................. 54 Configure Transportation Modeler to use the Java distance interface ............................... 55 Configure Transportation Modeler to use a Transportation Manager distance engine .......... 56 Configure Transportation Modeler to use a PC Miler distance engine ................................ 57

Edit and run the runPCMilerDistanceServer batch file ............................................ 57 Edit the distance parameters in the Solver Options dialog box ............................... 58

Index ............................................................................................................................. 60

Introduction

Chapter 1. Introduction This guide provides a basic understanding of the custom distance engine and its procedures, examples for the distance engine creation tool, and an overview of the external distance engine DLL (also known as Java distance interface).

Related documentation For more information on Transportation Modeler, see:

• Transportation Modeler Release Notes: Provides information about any new or updated functionality in Transportation Modeler.

• Transportation Modeler Installation/Administration Guide: Provides information about how to install Transportation Modeler.

• Transportation Modeler User Guide: Provides details about the Transportation Modeler user interface, modeling data in Transportation Modeler, and how to use the application.

• Transportation Modeler Strategies and Parameters Guide: Provides descriptions of the functions that you can use with the Transportation Modeler strategy files. It also contains descriptions of the global parameters that you set to control Transportation Modeler.

• Transportation Modeler Getting Started: Introduces to the Excel Rating Tool user interface, entities, relationships, and outviews. It describes the Excel Rating Tool modeling process, including tariff construction, optimization and analysis of results.

• Transportation Modeler Access Rating Tool User Guide: Provides information about how to use the Access and Excel based rating tool.

• Transportation Modeler Stand-Alone Rate Editor User Guide: Provides information about how to use Stand Alone Rate Editor.

• Transportation Modeler Distance Engine User Guide: Provides information about how to use the Distance Engine generation tool.

Get additional help from JDA In addition to the provided documentation, many additional resources are available to help you understand and work with your JDA applications.

Note: The services provided may vary by application and implementation.

• JDA Support Services

JDA Support Services enhances your experience with JDA solutions throughout the lifetime of your relationship with JDA Software. Support Services provides many key values, including:

• Worldwide support provided locally for issue resolution, including functional and technical assistance

• Defined service levels and proactive escalation paths

• Special Interest Group (SIG) membership

• Access to new software releases

• Access to the JDA Customer Support website (http://support.jda.com/), which provides:

JDA Transportation Modeler Distance Engine User Guide 1 © 1995-2015 JDA Software Group, Inc.- Confidential

http://support.jda.com/

Introduction

• Self-service user administration

• Online knowledge base

• Online case management and user communities

• Product documentation and release announcements

• JDA Education Services

To enhance the return on your JDA solution investment, JDA Education Services provides options to optimize your experience and knowledge. JDA Education Services offers high-quality training with e-learning and instructor-led training opportunities. JDA Education Services also offers the JDA Certification Program, which defines a curriculum that maximizes your knowledge and qualifications for a specific job. Certification programs employ a blend of learning methods that end with an industry-recognized exam. See the JDALearn website (http://www.jdalearn.com) for more information.

• JDA Consulting Services

JDA Consulting Services provides a broad range of services, including:

• Process definition and improvement

• Change management

• Program and project management

• Functional and technical consulting

• Performance engineering

• Solution delivery

Every solution deployment begins with the JDA Enterprise Methodology, which encompasses both technology and implementation expertise. JDA Consulting Services works collaboratively with you to help your business realize the results you need, on time and on budget.

• JDA Cloud Services

JDA Cloud Services enables you to achieve faster deployment, rapid time to value, investment protection, and improved cost structure with JDA supply chain solutions. This allows you to focus on your core business while JDA manages the JDA applications. Areas of specialty include:

• Solution availability management

• Performance management

• Issue resolution

• Change management

• Security management

• Optimization and analytics management

For more information on any of the JDA Services, see the JDA Services website (http://www.jda.com/services/services/).


http://www.jdalearn.com/

http://www.jda.com/services/services/

Distance engine overview

Chapter 2. Distance engine overview This chapter provides a basic understanding of the distance engine generation tool and step-by-step instructions for using the distance engine creation wizard to generate the distance engine.

The distance engine is an address validation geo-coding engine as well as a distance calculation engine. This engine validates addresses, finds the latitude and longitude of addresses, and calculates distances and transit times between pairs of locations to support the routing process.

The distance engine supports two types: a node–based engine and custom–based (override) engine. Node–based engines use the power of nodal networks to calculate accurate over-the-road distances between any two locations. Node–based engines require the least maintenance effort over time. You can add any locations required for execution, planning, or modeling, and as long as the locations are validated, the distance engine returns a distance for the location-to-location pairs that use the new location. The distance returned is approximated based upon the distance between the nearest node to the origin location and the nearest node to the destination location. In this scenario, you need not create any additional distances.

Custom engines provide exact location to exact location distance overrides. If you wish to add a new location into your environment, you must add the location and the distances between that location and all other locations. You should regenerate the distance engine each time you add locations to the solution.

Override engines enhance origin–destination combinations where the node-to-node distances are slightly inaccurate due to approximate value considerations. To get a better result, generate a node–based engine first, then run the override engine. You can find that a small number of location pairs are improved with overrides. The JDA execution, planning, and modeling solutions support distance and transit time overrides.

Address validation and geo-coding The distance engine validates addresses and assigns geo-codes in the following order:

1. Match address using country code, state/province code, city name and postal code.

2. Match address using country code and postal code.

3. Match address using country code, state/province code and city name:

a. Find the closest location in the city using some postal code.

b. Find the closest location to the city center.

c. Find the closest location in the city using the latitude and longitude.

d. Find the first non-zero latitude and longitude location in the city.

4. Match address using country code, state/province code, alias city name and postal code.

5. Match address using country code, state/province code and alias city name:

a. Find the closest location in the city using some postal code.

b. Find the closest location to the city center.

c. Find the closest location in the city using the latitude and longitude.

d. Find the first non-zero latitude and longitude location in the city.

6. Find the closest location in the country using the latitude and longitude.

7. Find closest city node to the found location.



Distance engine distance and time calculation Distances and transit times between locations are calculated using a database of real distances and times (for example, from an external distance engine such as PC*Miler) and the transit times between nodes. The calculations are more accurate when more nodes are available for a given country.

The purpose of the distance engine logic is to find accurate distance and transit time values. The distance engine finds the closest nodes to the origin and destination locations, and then finds the distance and transit time values between these nodes. It then performs additional calculations for accurate over-the-road distance and transit time values. The distance engine performs the following:

• Returns overrides (custom distance and transit time values), if you have provided override distance and transit time values.

• Gets actual distance and transit time values between location nodes, calculates the ratio between locations to nodes using linear distance, and then applies it to actual distance and time.

Distance engine creation tool The distance engine creation tool allows you to generate the database for the distance engine, including nodes, without requiring an external distance engine.

You must provide source location data (and also distance data, if you are not using an external distance engine such as PC*Miler), which is converted into distance engine compatible format.

The distance engine creation tool converts data from delimited flat files (in a comma separated value (CSV) format) into an intermediate set of input files, and then into a set of tables that constitute a distance engine. You can populate the CSV files directly, or using an inbuilt Microsoft Access based raw data template. It is recommended to use the Access database, RawDataTemplate.mdb, as required data formats are properly defined in the database tables. Additionally, the Access database includes a macro to convert the Access tables to CSV files to be used in the distance engine generation step.

Raw data files The raw data files contain the location and distance data required to create a distance engine. For more information on these files and their required formats, see "Distance creation raw data flat files" (on page 35).

The default location for the raw data files is: ..\i2distanceengine\creationtool\rawcsv.

Input files The distance engine creation tool uses the raw data files to create a set of intermediate input files. These files arrange data into categories and, then into countries. For more information, see "Distance Engine input files" (on page 39).

The default location for the intermediate input data files is: ..\i2distanceengine\creationtool\importfiles.

Map files The map files define the structure to map the data from the input files to the output files. In each map file, you must use the 2-character code to represent the country for which you are generating the distance engine. For example, if you are generating files for Canada, the last line in each of your mappings files should read: CountryCodeA2 'CA'.

The default location for the map files is: ..\i2distanceengine\creationtool\mapfiles.

Note: JDA recommends not to edit these map files.



Output tables The distance engine is comprised of a set of tables. The distance engine creation tool uses the intermediate input files to generate these tables. For more information, see "Distance Engine output tables" (on page 46).

The default location for the output tables is: ..\i2distanceengine\creationtool\i2distanceengine.

Note: JDA recommends not to modify these output tables.

Wizard files The distance engine creation tool includes a python script wizard to use with Transportation Planner and a batch file wizard to use with Transportation Modeler. These wizards determine the data sources, validate the data, and generate the distance engine output tables. For more information, see "Distance engine creation wizard" (on page 7).

The default location for these wizard files is the \bin folder in the installation folder.

Access database The distance engine creation tool includes a Microsoft Access database to use in the distance engine creation process. JDA recommends using the Access database as the source for distance and location data, as it has macros that publish CSV file data when provided the minimal amount of required data. The Access database also has additional logic to help with the data preparation.

The default filename and path for this database is: ..\i2distanceengine\creationtool\access\RawDataTemplate.mdb.

Executable files The distance engine creation tool includes the following set of executable files:

• Geoimp.exe: Imports the source location data and generates fixed width files for state, postal location (city), postal code, nodes, as well as the fixed width distance and transit time file that maps the defined locations with distance and transit time information.

• Geoimp2.exe: This file is similar in functionality to Geoimp.exe, but is used by the wizard provided with the distance engine creation tool.

• Geocrt.exe: This file uses the fixed width files generated using geoimp.exe and creates the geo files (the binary files used by the JDA Transportation applications) for states, locations, location postal code, city, node, and custom distance and transit time.

Note: These files must be created in the specified order, as one output file depends on another.

• Geocrt2.exe: This file is similar in functionality to Geocrt.exe, but is used by the wizard provided with the distance engine creation tool.

Batchcreate.bat: This batch file automatically creates output folders outputimp and outputgeo under the c:\rootdata location and runs geoimp.exe and geocrt.exe.

Code integration to third party distance provider The distance engine creation tool supports distance data from a file source (CSV flat files or Access), or from a third party distance provider, such as PC*Miler. If you want to use a third party distance provider, you must create a geocrt interface to the distance provider application. This geocrt interface integrates the external distance provider in the geo creation process.



Following are the prerequisites for the external distance provider in order to integrate it in the geo creation process:

• It must provide interfaces to access the location, distance, and time data.

• It must provide the raw location data as per data requirements for geocrt or support interface to extract the same. The data requirements are specified in "File and table formats" (on page 28).

• It must support an API to calculate the distance between two locations using either the place name or latitude/longitude values.

• If you want the geocrt utility to generate nodes automatically from the location list or if you need to build the latitude/longitude values for locations, then the external distance provider must support a method to convert location name to latitude/longitude values. The method GEOCRTLocationNameToLatLong of the geocrt interface should be implemented correctly in the connecting DLL. For more information, see "API description" (on page 49).

If you are using code integration to a third party distance provider with the distance engine creation wizard, you need to specify connection information:

• Distance Calculator DLL: The path and file name of the distance server DLL for your third party distance provider application.

• Distance Calculator Connector DLL: The path and file name of the compiled DLL that is written as an interface to the distance provider's engine. The PCMConnect.dll file is provided as an example in the \i2distanceengine\creationtool folder.

For more information, see "Distance engine creation wizard" (on page 7).


Distance engine creation wizard

Chapter 3. Distance engine creation wizard The distance engine creation tool provides a wizard that is used to collect information about the data you are providing and how you want to use the tool to create the distance engine. This wizard is provided as a python script to be used with Transportation Planner and as a batch file for use with Transportation Modeler. The wizard content is the same for both implementations.

Run the wizard with Transportation Planner The wizard is provided as a python script (.py) with Transportation Planner implementation. The createI2DistanceEngine.py script is installed in the \bin folder within the Transportation Planner installation folder (the default path is c:\JDA\tp\9.0).

1. Select Transportation Planner Launcher from the Transportation Planner Start menu.

2. Run the createI2DistanceEngine.py script. You can optionally provide a session file name as an argument for the script. The session file contains the responses from a previous wizard session and automatically provides responses to the current session’s queries. For more information, see "Session file" (on page 16). The distance engine creation wizard is launched. For more information, see the Transportation Planner Implementation Guide.

3. Press Enter to start the process.

4. Perform the steps provided in "The distance engine creation wizard" (on page 8).

Run the wizard with Transportation Modeler The wizard is provided as a batch file (.bat) with your Transportation Modeler implementation. The createI2DistanceEngine.bat batch file is installed in the \bin folder within the Transportation Modeler install folder (the default path is c:\JDA\tmod\9.0).

1. Select i2 Distance Engine Creation Tool from the Transportation Modeler Start menu. The distance engine creation wizard is launched.

Alternate steps:

a. Open the command prompt window and browse to the \bin folder within the Transportation Modeler install folder.

b. Run the createI2DistanceEngine.bat batch file.

c. The distance engine creation wizard is launched.

2. Press Enter to start the process.

3. Perform the steps provided in "The distance engine creation wizard" (on page 8).

Distance engine data The distance engine creation tool converts data from delimited flat files (in a comma separated value (CSV) format), into an intermediate set of input files, and then into a set of tables that constitute a distance engine. You can import the CSV files directly, or using inbuilt Microsoft Access based raw data template. It is recommended to use the Access database, RawDataTemplate.mdb, as required data formats are properly defined in the database tables. Additionally, the Access database includes a macro to convert the Access tables to CSV files to be used in the distance engine generation step. The data formats for the files and tables are provided in "File and table formats" (on page 28).



Note: It is recommended to perform regular cleanup on the folders containing the raw data (by default, \rawcsv) and the intermediate input files (by default, \importfiles) before starting a new distance engine creation process. Data unintentionally left in these folders can be picked up by the tool and can generate unexpected results.

The distance engine creation wizard The distance engine creation wizard is comprised of following major sections:

• "Interview questions" (on page 8): The wizard contains nine questions. Your responses to these questions determine what data you provide and the way it is used in the distance engine creation tool to generate a distance engine. When these responses are done, the wizard prompts you with the following options:

• "Advanced settings" (on page 12): If you have answered 1.) Yes for the Advanced Settings question, you can edit these settings. The settings control paths and global format options.

• "Session File" (on page 16): You can optionally save a session file that stores the responses provided to the interview questions. If you run the wizard again, provide the path and filename of the session file as an argument to the wizard script. The wizard uses the contents of the session file as the responses to the interview questions and you automatically get proceed to the next step in the wizard.

• "Batch File" (on page 17): The batch file performs the final processing steps of the wizard. Use the batch file only when you are certain you have set up your data correctly as it does not provide help with data preparation or data validation.

• "Raw Data Preparation" (on page 18): Based on your responses to the interview questions, the wizard provides step-by-step instructions in preparing the raw data for distance engine creation. At the end of this section, your raw data must exist in a set of delimited flat files. By default, these are comma separated value (CSV) files.

• "Data Validation" (on page 23): If you select to run the optional data validation module, the wizard validates the raw data in your CSV files. It compares the format of your raw data with the mapping files that determine valid data formats.

• "Distance Engine Generation" (on page 26): The wizard converts the input data to the distance engine output tables.

As you proceed through the wizard, to access Help, type H or help and press Enter.

You can return to previous questions by typing B or Back.

Note: You cannot return or access help when you are editing the Advanced Settings.

Default paths indicated in the wizard are related to your Transportation Planner installation path (by default c:\JDA\tp\9.0) or Transportation Modeler installation path (by default c:\JDA\tmod\9.0).

The specific instructions to prepare your data for conversion to the distance engine are provided in the Raw Data Preparation section of the wizard. Your actions occur outside the wizard, for example within the Microsoft Access database provided with the tool, so you must not continue the wizard till you have completed the steps indicated.

Interview questions There are nine primary interview questions:

• "Question 1: Location data source" (on page 9)



• "Question 2: Engine type" (on page 9)

• "Question 3: Distance data source" (on page 10)

• "Question 4: Override Data source" (on page 10)

• "Question 5: Node selection method" (on page 11)

• "Question 6: Location aliases" (on page 11)

• "Question 7: Data preparation walkthrough" (on page 11)

• "Question 8: Data validation" (on page 11)

• "Question 9: Advanced settings" (on page 12)

The answers you provide determine what other steps in the process are made available to you by the wizard.

Question 1: Location data source The distance engine requires two major data elements: locations and the distances between locations. You can provide the locations source from the Access database provided with the distance engine creation tool, or use CSV files. Create the CSV files using Excel or insert them directly in a text editor. The Access database provided with the distance engine creation tool is the recommended source, as it has macros that publish CSV file data when provided with the minimal amount of required location data. The Access database also has additional logic to help you with data preparation.

What is your source of all location data? 1. Access (default). This is the recommended data source.

2. CSV files

Note: If you select CSV Files, you must provide distances in a non-Access location. For more information, see "Question 3: Distance data source" (on page 10).

Question 2: Engine type The distance engine is one of two types, node–based engine (recommended) or custom–based engine. Node–based engines use the power of nodal networks to calculate accurate over-the-road distances between any two locations. Node–based engines require the least maintenance effort over time. You can add any locations required for execution, planning, or modeling and, if they are validated, the distance engine returns a distance for the location-to-location pairs that use the new location. In this scenario, you need not create any additional distances.

Custom (or Override) engines only provide exact location to exact location distance overrides. If you wish to add a new location into your JDA execution, planning, or modeling environments, you must add the location and all distances between that location and all other locations. You need to regenerate the distance engine each time you add locations to the solution.

Override engines provide the ability to enhance origin–destination combinations in cases where the node-to-node distances are too inaccurate due to approximation considerations. When you generate a node-based engine, create an override engine and run it to improve the distances between the small numbers of location pairs. The JDA execution, planning, and modeling solutions support distance and transit time overrides.

Which type of engine would you like to create? 1. Node–Based (default). This is the recommended engine type.



2. Node–Based with Overrides

3. Overrides only

Question 3: Distance data source This question is displayed if you provide the answer as 1.) Node–Based or 2.) Node–Based with Overrides for "Question 2: Engine type" (on page 9). The following are the sources of distance data when creating a node–based engine:

• Data generated using the Access database provided with the distance engine creation tool.

• A CSV file.

• Code integration to a third party distance provider.

If you are using an Access or CSV file, the node-to-node distance data can be the largest set of data. You must define the distances between all selected nodes. If you have ten nodes, create ninety node-to-node distance records. This model of distance data increases exponentially, so one hundred nodes requires nine thousand nine hundred distance records. You can populate this data in Access (recommended) or in CSV files.

You can also create a coded interface from the distance engine creation tool to your distance provider's tool. You must be proficient in developing C++ code and in working with the coding language of the source distance data provider's application. The distance engine creation tool inserts your selected node pairs and requires distance and transit times. You must use this source if you plan to use auto-generated nodes.

Note: Node-pair distance creation can take a long time based on the total number of distance records or distance calls required.

What is your source of node to node distance data? 1. Access (default). This is the recommended data source.

2. CSV File.

3. Code Integration to Distance Provider.

Note: If you want the nodes to be auto generated, you must use the option Code Integration to Distance Provider. For more information, see "Question 5: Node selection method" (on page 11).

Note: If a valid Road.txt file exists in your intermediate input file folder (typically \importfiles), the distance engine creation tool utilizes this data instead of your third party distance provider, even if you select to use the third party distance provider. It is recommended that you clean up the rawdata and importfile folders when using the third party provider.

Question 4: Override data source This question is displayed if the answer provided for "Question 2: Engine type" (on page 9) is 2.) Node–Based with Overrides or 3.) Overrides Only.

There are two sources of distance data when creating location-to-location overrides (custom distances). You can use all your defined locations while specifying the origin and the destination for the distance and transit time.

What is your source of distance override data? 1. Access (default). This is the recommended data source.

2. CSV File



Question 5: Node selection method This question is displayed if the answer provided for "Question 2: Engine type" (on page 9) is 1.) Node–Based or 2.) Node–Based with Overrides.

Following are the methods used to select nodes:

• Select them manually from a subset of your location data. This method is recommended when you have time to analyze your geography and business network (that is, the DCs, origin and destination locations) in order to strategically select your nodes. You can either select nodes close to business locations, or create nodes for all defined locations if the full set of locations is not large.

• You can allow the distance engine creation tool to select the nodes for you (also called auto-generated nodes). The tool can accept additional inputs to determine locations for nodes such that there is a greater chance of getting full coverage across a given geography. For example, the nodes can be allocated based on postal code density. This approach reduces the approximation of real road distances and also provides distance coverage.

Note: You must create a coded interface to your third party distance provider if you plan to use auto-generated nodes. For more information, see "Question 3: Distance data source" (on page 10).

What is your method for node selection? 1. Select my own from my set of locations (default)

2. Have the tool select them from my set of locations

Question 6: Location aliases You can have operational data feeds which include multiple spellings for cities. For example, one feed may include 'Milan' while another uses 'Milano'. If this condition is applicable to your implementation, you must predefine the set of city aliases for a given location in your source of location data (Access or CSV file).

Do you want to create location aliases? 1. Yes

2. No (default)

Question 7: Data preparation walkthrough The distance engine creation tool provides functionality to walk you through the process of preparing the raw data. It is recommended that you run the data preparation module the first time you are creating a distance engine.

Do you want to run the raw data preparation module? 1. Yes (default)

2. No

Question 8: Data validation The distance engine creation tool provides data validation functionality that validates whether your prepared data is correctly imported before generating a distance engine. While writing your own interface to generate node–based distances from a third party distance provider, you must run the utility to test the interface you have written.



Would you like to run the data validation module? 1. Yes (default)

2. No

Question 9: Advanced settings The distance engine creation tool enables you to override default settings, which includes file paths, file names, and advanced parameters. If you are using Access as the data source for locations or distances or both, the macros in Access write the data to the default filenames and file paths.

Would you like to edit the advanced parameters? 1. Yes

2. No (default)

Interview conclusion After answering the interview questions, and selecting 1.) Yes to "Question 9: Advanced settings" (on page 12), you are prompted to set the "Advanced settings" (on page 12).

Additionally, the following files should be saved to record the current session for future use:

• "Session file" (on page 16)

• "Batch file" (on page 17)

Advanced settings These settings are displayed if "Question 9: Advanced settings" (on page 12) is answered 1.) Yes.

A series of advanced settings are displayed to control the creation of the distance engine. For each setting, you can accept the default value or enter an alternate value. For settings with multiple options, enter the number of the option you want to select.

Setting Description Default

Input Files Directory Specifies the path from which raw data input files are read. Press Enter to accept the default path, or enter an alternate path. If the directory does not exist, you are prompted to confirm creation of the new directory. For more information, see "Distance creation raw data flat files" (on page 35).

For Transportation Planner: ..\sce\i2distanceengine\creationtool\rawcsv For Transportation Modeler: ..\i2distanceengine\creationtool\rawcsv

Intermediate Files Directory

Specifies the path into which the distance engine creation tool writes the intermediate set of input files. Press Enter to accept the default path, or enter an alternate path. If the directory does not exist, you are prompted to confirm creation of the new directory. For more information, see "Distance Engine input files" (on page 39).

For Transportation Planner: ..\sce\i2distanceengine\creationtool\importfiles For Transportation Modeler: ..\i2distanceengine\creationtool\importfiles




Output Files Directory

Specifies the path into which the distance engine files are written. Press Enter to accept the default path, or enter an alternate path. If the directory does not exist, you are prompted to confirm creation of the new directory. For more information, see "Distance Engine output tables" (on page 46).

For Transportation Planner: ..\sce\i2distanceengine\creationtool\i2distanceengine For Transportation Modeler: ..\i2distanceengine\creationtool\i2distanceengine

Mapping Files Directory

Specifies the path containing files that define the structure for mapping data from the input files to the output files. Press Enter to accept the default path, or enter an alternate path. If the directory does not exist, you are prompted to confirm creation of the new directory. For more information, see "Mapping files" (on page 39).

For Transportation Planner: ...\sce\i2distanceengine\creationtool\mapfiles For Transportation Modeler: ..\i2distanceengine\creationtool\mapfiles

Geo Tools Directory Specifies the path containing the distance creation component files (for example, GeoCrt.exe and GeoImp.exe). Press Enter to accept the default path, or enter an alternate path. If the directory does not exist, you are prompted to confirm creation of the new directory.

For Transportation Planner: ..\sce\i2distanceengine\creationtool For Transportation Modeler: ..\i2distanceengine\creationtool

File Delimiter Character used as a delimiter between fields in the raw data files.

File Qualifier Character used as the qualifier for field values in the raw data files.

Skip First Record Indicates whether the first record in the file should be skipped. This value should be true if the first record in the file is a header record. Options are:

• false

• true

false

How should duplicate entries in the input data be handled

Indicates the response of the tool if it encounters duplicate entries:

• 1 - Remove all occurrences

• 2 - Leave first occurrence, remove all others

• 3 - Do not remove any occurrences

3 - Do not remove any occurrences

Filter Allows you to remove entries containing the specified string XXX.

null (no filter)




Filter By Maximum Record Length

Indicates whether fields are filtered based on a specified maximum field length. Options are:

• false

• true

false

Translation of input data characters

Indicates whether the imported text should be translated. The options are:

• 1 - No translation

• 2 - Translate to English character set (ASCII)

• 3 - Translate to English and upper case

1 - No translation

Distances In Miles Specifies the distance unit of measure for the input file. The options are:

• true - miles

• false - kilometers

true

Trace Level for GeoImp

Specifies the trace level for logging purposes. The higher the level, the more detail is recorded in the logs during GeoImp processing. The valid values are integers from 0 to 5.

3

Trace Level for GeoCrt

Specifies the trace level for logging purposes. The higher the level, the more detail is recorded in the logs during GeoCrt processing. The valid values are integers from 0 to 5.

3

Distance Calculator DLL

Specifies the path and file name of the actual distance server DLL for the third party distance provider application. Note: This parameter is displayed only if "Question 3: Distance data source" (on page 10) is answered 3.) Code Integration to Distance Provider.

Distance Calculator Connector DLL

Specifies the path and file name of the compiled DLL that you have written as an interface to your distance provider's engine. JDA provides PCMConnect.dll as an example in the \i2distanceengine\creationtool folder. Note: This parameter is displayed only if "Question 3: Distance data source" (on page 10) is answered 3.) Code Integration to Distance Provider.




Node Creation Starting Distance in Degrees Latitude/Longitude

Controls how closely nodes are clustered when nodes are automatically created. When the distance engine creation tool examines possible locations for nodes, candidate nodes must be located at latitude/longitude positions of this degree distance from the calculated center. Note: This parameter is displayed only if "Question 3: Distance data source" (on page 10) is answered 3.) Code Integration to Distance Provider and "Question 5: Node selection method" (on page 11) is answered 2.) Have the tool select them from my set of locations.

1.0

What is the node creation source?

Specifies the source for node creation when you are auto-generating nodes. The options are:

• 1 - Blank

• 2 - File: Uses the file specified in the Node Creation File parameter as the source for node data.

• 3 - Center: Calculates a center point according to the cluster of geovalid locations. Additional nodes must be at a specified distance from this center node. You can control this distance using Node Creation Starting Distance in the Degrees Latitude/Longitude parameter.

• 4 - Special

Note: This parameter is displayed only if "Question 3: Distance data source" (on page 10) is answered 3.) Code Integration to Distance Provider and "Question 5: Node selection method" (on page 11) is answered 2.) Have the tool select them from my set of locations.

2 - File

Node Creation File Specifies the path and file name of the file containing node creation data. Note: This parameter is displayed only if "Question 3: Distance data source" (on page 10) is answered 3.) Code Integration to Distance Provider.




What is the route type for road distances?

Specifies the type of route used to return distances from a third party distance provider (for example, PC*Miler). Also, if the route type is Practical, the distance engine creation tool opens the Road[A2].txt input file to generate the output road file. If the route type is Shortest, the tool opens the Roads[A2].txt input file. The options are:

• 1 - Practical

• 2 - Shortest

1 - Practical

What is the route lookup for road distances?

Specifies the method for lookup to return distances from a third party distance provider (for example, PC*Miler). This setting determines what data is passed to the distance engine for the origin and destination identifiers. The options are:

• 1 - Name

• 2 - Lat Lon

1 - Name

Origin Country Specifies the origin country from which to retrieve distances and transit times from a third party distance provider (for example, PC*Miler). If a country is specified, only that country is processed when creating the road network.

Destination Country Specifies the destination country from which to retrieve distances and transit times from a third party distance provider (for example, PC*Miler). If a country is specified, only that country is processed when creating the road network.

Session file When you are done answering the interview questions, you can save the interview responses as a session file. Provide the session file name as an argument when you run the distance engine creation tool the next time. The responses are supplied automatically and the tool continues from the conclusion of the interview portion of the wizard.

Save the session file Note: If you do not want to save the session file, enter S to skip the step.

1. Enter a path and filename for the session file, or press Enter to accept the default path and filename.



• The default for Transportation Planner is ..\sce\i2distanceengine\creationtool\sessionfiles\Sessionnnn.properties

• The default for Transportation Modeler is ..\i2distanceengine\creationtool\sessionfiles\Sessionnnn.properties

In both the cases, nnn is a unique number to identify the session.

Use the session file with Transportation Planner 1. Open the Transportation Planner Launcher.

2. Select the createI2DistanceEngine.py script.

3. Enter the session file path and filename in the Script Arguments field.

4. Click Run. The distance engine creation wizard is launched and it uses the contents of the session file to respond to the wizard questions.

Use the session file with Transportation Modeler 1. Open the command prompt window.

2. Navigate to the \bin folder in the Transportation Modeler install folder.

3. Enter createI2DistanceEngine.bat and the session file path and filename as an argument. The distance engine creation wizard is launched and it uses the contents of the session file to respond to the wizard questions.

Batch file You can save a batch file that contains the responses to the process questions provided during the interview session. You can use this file at a later time to automate the distance engine creation process.

Note: Use the batch file only when you are certain that you have set up your data correctly as it does not provide help with data preparation or data validation.

Save the batch file Note: If you do not want to save the batch file, enter S to skip the step.

1. Enter a path and filename for the batch file, or press Enter to accept the default path and filename.

• The default for Transportation Planner is ..\sce\i2distanceengine\creationtool\BatchCreateFixedWidthAndBinaries.bat

• The default for Transportation Modeler is ..\i2distanceengine\creationtool\BatchCreateFixedWidthAndBinaries.bat

Use the batch file with Transportation Planner and Transportation Modeler 1. Open a command prompt.

2. Navigate to the folder where you created the batch file. The default folder for

• Transportation Planner: ..\sce\i2distanceengine\creationtool

• Transportation Manager: ..\i2distanceengine\creationtool.



3. Enter the batch file name you created. By default, the filename is BatchCreateFixedWidthAndBinaries.bat. The batch file runs all the operations used to create the intermediate input files and generate the final distance engine output files.

Raw data preparation Note: This section of the wizard is displayed only if "Question 7: Data preparation walkthrough" (on page 11) is answered 1.) Yes.

This section of the wizard explains data preparation using the responses during the interview question section. Specific instructions are provided to prepare your data for conversion to the distance engine. Your actions are performed outside of the wizard, so you can continue the wizard when you complete the indicated steps.

Default paths indicated in this section are relative to your Transportation Planner installation path (by default, c:\JDA\tp\9.0) or Transportation Modeler installation path (by default, c:\JDA\tmod\9.0).

Press Enter to continue with the data preparation section of the wizard.

Prepare your locations in Access This section is displayed if "Question 1: Location data source" (on page 9) is answered 1.) Access.

1. Open the distance engine Access data repository, RawDataTemplate.mdb, located in:

For Transportation Planner: ..\sce\i2distanceengine\creationtool\access

For Transportation Modeler: ..\i2distanceengine\creationtool\access

2. Open the COUNTRIES table. The country information is already inserted in the table. If there is any country for your implementation that is not already defined in the COUNTRIES table, populate the country name, ISO3 country identifier, and ISO2 country identifier. The ISO3 identifier maps to the country associated with execution, planning, and modeling location descriptions. The ISO2 identifier is used by distance engine to identify locations, so the mapping must be complete and unique across countries.

3. Open the LOCATIONS table. Populate all available location data for all the countries associated with modeling, executing, or planning. Populate the CITY, STATE, COUNTRY, LAT, LON data. If you do not have state information, populate the state values with the ISO2 country data, which considers one state per country. Postal codes are optional, but if you have postal code information, populate it as it makes your location validation more accurate.

4. Insert one to many aliases per LOCATION record in the LOCATIONALIASES table. Insert an alias city to map to a valid location city/state/country.

Note: This step is displayed only when you select the option to create location aliases in the interview.

5. Press Enter to continue with the wizard after performing the previous steps.

Prepare your locations in flat files This section is displayed if "Question 1: Location data source" (on page 9) is answered 2.) CSV Files.

1. Navigate to:

For Transportation Planner: ..\sce\i2distanceengine\creationtool\rawcsv

For Transportation Modeler: ..\i2distanceengine\creationtool\rawcsv



2. Open countryraw.txt. The country information is already inserted in the file. If there is any country for your implementation that is not already defined in the file, populate the country name, ISO3 country identifier, and ISO2 country identifier. The ISO3 identifier maps to the country associated with execution, planning, and modeling location descriptions. The ISO2 identifier is used to identify locations, so the mapping must be complete and unique across countries.

3. Open geovalidlocationraw.txt. Populate all available location data for all countries associated with modeling, executing or planning. Populate the CITY,STATE,COUNTRY,LAT,LON data. If you do not have state information, insert the state values with the ISO2 country data, which considers one state per country. Postal codes are optional, but if you insert postal code information, it makes your location validation more accurate.

4. Open locationaliasraw.txt. Populate one to many aliases per location record in the location alias file. Insert an alias city to map to a valid location city/state/country.

Note: This step is displayed only when you select the option to create location aliases in the interview.

5. Press Enter on the wizard screen to continue with the wizard after performing the previous steps.

Prepare your nodes in Access This section is displayed if:

• "Question 1: Location data source" (on page 9) is answered as 1.) Access, and

• "Question 2: Engine type" (on page 9) is answered as 1.) Node–Based or 2.) Node–Based with Overrides, and

• "Question 5: Node selection method" (on page 11) is answered as 1.) Select my own from my set of locations.

In this section, select nodes by setting the IsNode flag for location records. Nodes are typically a subset of your locations.

According to the dispersion of locations, you can select all or only some of the locations as nodes. If you select a subset, be strategic about your selection. For example, you can have the nodes evenly spread across the geography. Alternately, you can align the business network set of origins and destinations to node points. Strategically placing more nodes results in more accurate distances. Selecting a larger number of nodes also increases the number of distance records and increases distance engine creation time.

Select nodes in Access 1. Open the LOCATION table.

2. Enable the IsNode field for each location you want to identify as a node.

3. Press Enter on the wizard to continue with the wizard.

Prepare your nodes in flat files This section is displayed if

• "Question 1: Location data source" (on page 9) is answered as 2.) CSV Files,

• "Question 2: Engine type" (on page 9) is answered as 1.) Node–Based or 2.) Node–Based with Override, and




In this section, select nodes inserting the locations you want to use as nodes in the nodelocations.txt file. Nodes are typically a subset of your locations.

According to the dispersion of locations, you can select all or only some of the locations as nodes. If you select a subset, be strategic about your selection. For example, you can have the nodes evenly spread across the geography. Alternately, you can align the business network set of origins and destinations to node points. Strategically placing more nodes results in more accurate distances. Selecting a larger number of nodes also increases the number of distance records and increases distance engine creation time.

Select nodes in CSV files 1. Open the nodelocations.txt file.

2. Enter the subset of location records to define as nodes from your geovalidlocation.txt file.


Automatically select nodes from Access locations This section is displayed if:

• "Question 1: Location data source" (on page 9) is answered as 1.) Access,


• "Question 5: Node selection method" (on page 11) is answered as 2.) Have the tool select them from my set of locations.

In this case, the distance creation tool creates nodes automatically. You must enable the IsNode field for all locations as all locations are valid for automatic node selection.

Automatically choose nodes from flat file locations This section is displayed if:

• "Question 1: Location data source" (on page 9) is answered as 2.) CSV Files,


• "Question 5: Node selection method" (on page 11) is answered as 2.) Have the tool select them from my set of locations.

In this case, the distance creation tool creates nodes automatically. You must define all locations, which are in your geovalidlocation.txt file, in nodelocations.txt.

Prepare your distance road file in Access This section is displayed if:


• "Question 3: Distance data source" (on page 10) is answered as 1.) Access.



Provide the full qualifier of the node location used as an origin and the node used as a destination to create node-based distance and transit times. Enter a distance and a transit time between each pair of nodes. Leave the IsOverride field unselected for all of your node-based distance and transit times. This data is the raw data that creates your road files. Road files contain the distances and transit times between the pairs of nodes.

Create the distance and transit times 1. Open the DISTANCES table in your Access database.

2. Enter the origin and destination nodes (the City, State, Country are the minimum requirements). Ensure that the node location definitions exactly match the City/State/Country values defined in the LOCATION table where the IsNode field is enabled.

3. Enter the distance (as km or miles) and transit time in minutes.

4. Ensure that IsOverride is not selected (disabled) for all inserted node-based distance records.

5. Press Enter to continue with the wizard.

Prepare your distance road file in flat files This section is displayed if:


• "Question 3: Distance data source" (on page 10) is answered as 2.) CSV File.

Provide the full qualifier of the node location used as an origin and the node used as a destination to create node-based distance and transit times. Insert a distance and a transit time between each pair of nodes. This data is the raw data that creates your road files. Road files contain the distances and transit times between the pairs of nodes.

You must organize your data into the following files:

• roaddistancerawsamecountry.txt: Contains distance records where the node pairs reside in the same country. For example, you can have node-based distance records that apply for node to node movements in France and node-based distance records that apply for node to node movements in Germany. Both of these sets of records exist in the same file called roaddistancerawsamecountry.txt.

• roaddistancerawdifferentcountry.txt: Contains distance records where the node pairs reside in different countries. For example, you can have node-based distance records that apply for node to node movements between France and Germany. All of these country-to-country movements exist in the same file called roaddistancerawdifferentcountry.txt.

Create the distance and transit times 1. Open the appropriate road distance file, roaddistancerawsamecountry.txt or

roaddistancerawdifferentcountry.txt.

2. Enter the origin and destination nodes (the City, State, Country are the minimum requirements). Ensure that the node location definitions exactly match the City/State/Country values defined in the nodelocationraw.txt file.





Prepare your distance overrides in Access This section is displayed if:

• "Question 2: Engine type" (on page 9) is answered as 2.) Node–Based with Overrides or 3.) Overrides only, and

• "Question 4: Override data source" (on page 10) is answered as 1.) Access.

You have selected to include distance overrides in your distance engine. Define an override between any two valid locations defined in your locations table, whether the location is a node or not. Enter the full qualifier of the node location used as an origin and the node used as a destination. Insert a distance and a transit time between each pair of locations. Enable the IsOverride field in the DISTANCES table for all of your override-based distance and transit times. This is the raw data that creates your custom files. Custom files contain the override distances and transit times between pairs of locations.

1. Open the DISTANCES table in your Access database.

2. Enter the origin and destination nodes (the City, State, Country are the minimum requirements). Ensure that the node location definitions exactly match the City/State/Country values defined in the LOCATION table.


4. Enable the IsOverride field for all node-based distance records.


Prepare your distance overrides in flat files This section is displayed if:

• "Question 2: Engine type" (on page 9) is answered as 2.) Node–Based with Overrides or 3.) Overrides only, and

• "Question 4: Override data source" (on page 10) is answered as 2.) CSV File.

You have selected to include distance overrides in your distance engine. Define an override between any two valid locations defined in your locations table, whether the location is a node or not. Enter the full qualifier of the node location used as an origin and the node used as a destination. Insert a distance and a transit time between each pair of locations. This data is the raw data used to create your custom files. Custom files contain the override distances and transit times between pairs of locations.

1. Open the overridedistancesraw.txt file.

2. Insert the origin and destination nodes (the City, State, Country are the minimum requirements). Ensure that the node location definitions exactly match the City/State/Country values defined in the nodelocationraw.txt file.

3. Insert the distance (expressed consistently as km or miles) and transit time in minutes.

4. Press Enter on the wizard to continue with the wizard after performing the previous steps.

Access data preparation complete This section is displayed if:

• "Question 1: Location data source" (on page 9) is answered as 1.) Access, or

• "Question 3: Distance data source" (on page 10) is answered as 1.) Access, or



• "Question 4: Override data source" (on page 10) is answered as 1.) Access.

You have created some or all of your raw data in Access. To complete your raw data preparation, run the macro called ExportDatatoFile in your Access file. It creates or overrides some additional preparation tables and then exports the data to CSV files. The distance engine creation tool can then create the distance engine.

Set the target paths in the export to CSV file macro Before you run the ExportDatatoFile macro, change the fully qualified target path for the CSV files. This step is required if you are using the macro with an implementation when:

• The product is installed in a location other than the default location (c:\JDA\tp\9.0\ or c:\JDA\tmod\9.0), or

• Generated CSV files reside in a folder other than the default location.

Set the target path for the CSV files 1. Open the macro ExportDatatoFile in Design View.

2. For each of the seven ImportExportText action, change the export path such that the table will be exported to the correct location. For example, if you have installed Transportation Modeler to c:\mytmod instead of c:\JDA\tmod\9.0, you can replace "\JDA\tmod\9.0" with "mytmod"..

3. Save the macro.

Flat file data preparation complete This section is displayed if:

• "Question 1: Location data source" (on page 9) is answered 2.) CSV Files, or

• "Question 3: Distance data source" (on page 10) is answered 2.) CSV File, or

• "Question 4: Override data source" (on page 10) is answered 2.) CSV File.

You have created some or all of your raw data in CSV files. To complete your raw data preparation, ensure that your raw files reside in the following locations and are properly named based on the example files in the directories:

For Transportation Planner: ..\sce\i2distanceengine\creationtool\rawcsv

For Transportation Modeler: ..\i2distanceengine\creationtool\rawcsv

Data validation This section is displayed if:

• "Question 8: Data validation" (on page 11) is answered 1.) Yes.

The next set of actions allows the tool to perform data validation on your prepared raw data. You must export your data from Access or create your data in CSV files before running data validation.

For each of the steps in data validation, press Enter to continue the validation step, or type S to skip the step.



To display validation data 1. The wizard displays input data to validate the mapping. By default, the first ten lines of the input

data are displayed for verification. Press Enter to accept the default or enter one of the following values to control the number of lines to display:

• n:To read more than or less than ten lines, enter the number of lines to read.

• -1:To read all lines of the input.

• 0:To skip the display of input data.

2. If the data maps as you expected, press Enter to continue the validation. If not, you must either:

• Fix the mapping file, or

• Re-run the data preparation step to create the raw data correctly. Type D to re-run the "Raw data preparation" (on page 18) section of the wizard.

3. When the mapping file or raw data has been corrected, type R to re-run this validation step.

Validate the data 1. By default, the wizard validates the first ten lines of the input data. Press Enter to accept the

default or enter one of the following values to control the number of lines to display:

• n: To read more than or less than ten lines, enter the number of lines to read.

• -1: To read all lines of the input.

• 0: To skip the display of input data.

2. If errors are detected, the wizard displays the line number in the raw data and provides information about the invalid data. You can either:

• Type S to skip this step,

• Press Enter to re-run this step, or

• Re-run the data preparation step to create the raw data correctly. Type D to re-run the "Raw data preparation" (on page 18) section of the wizard.

3. If no errors are detected, press Enter to continue.

Country data validation Data validation analyzes country information. This step validates the data in CountryRaw.txt maps to country data using the mappings in COUNTRY.MAP.

State data validation Data validation analyzes state information. This step validates the data in GeoValidLocationRaw.txt maps to state data using the mappings in STATE.MAP.

Location data validation Data validation analyzes location information. This step validates the data in GeoValidLocationRaw.txt maps to location data using the mappings in PLACE.MAP.



Postal data validation Data validation analyzes postal code information. This step validates the data in GeoValidLocationRaw.txt maps to postal code data using the mappings in POSTAL.MAP.

Alias data validation Run only if:

• "Question 6: Location aliases" (on page 11) is answered 1.) Yes.

Data validation analyzes city alias information. This step validates the data in locationaliasraw.txt maps to location alias data using the mappings in ALIAS.MAP.

Node data validation - manually selected nodes You can run this page if:



Data validation analyzes manually selected node information. This step validates the data in nodelocationraw.txt maps to node data using the mappings in NODE.MAP.

Node data validation - automatically selected nodes Note: This validation step is currently not supported.

Roads in the same country data validation You can run this page if:


• "Question 3: Distance data source" (on page 10) is answered as 1.) Access or 2.) CSV File.

Data validation analyzes distance information for roads with both origin and destination in the same country. This step validates the data in roaddistancerawsamecountry.txt maps to distance data using the mappings in ROADSAMECOUNTRY.MAP.

Roads in different countries data validation You can run this page if:


• "Question 3: Distance data source" (on page 10) is answered as 1.) Access or 2.) CSV File.

Data validation analyzes distance information for roads with origins and destinations in the different countries. This step validates the data in roaddistancerawdifferentcountry.txt maps to distance data using the mappings in ROADDIFFERENTCOUNTRY.MAP.



Override distance data validation You can run this page if:

• "Question 2: Engine type" (on page 9) is answered as 2.) Node–Based with Overrides or 3.) Overrides only.

Data validation analyzes override distance information. This step validates the data in overridedistancesraw.txt to override distance data using the mappings in CUSTOMDISTANCETRANSITTIME.MAP.

Road distance data validation - distance provider Note: This validation step is currently not supported.

You can run this page if:


• "Question 3: Distance data source" (on page 10) is answered as 3.) Code Integration to Distance Provider.

Data validation tests interface to distance provider. The test verifies whether a pair of nodes can be passed through the interface and return a distance and a transit time to the distance engine creation tool. Ensure that your interface is ready to be tested and distance provider engine is ready to accept a call.

Data validation complete When your data is successfully validated, you can proceed to create the distance engine.

Press Enter to continue the distance engine creation process.

Generate the distance engine You are notified as each step is completed. The road file generation step is a lengthy process in the distance engine creation process. This step can take several minutes to many hours based on the number of distance calls. The tool notifies you if there are any problems during the generation.

Start process and status dialog 1. Press Enter to start the distance engine creation process.

2. The status messages are displayed. For example:

Creating the country file. The output file is called country.txt.

Creating the state fixed width file. The output file is called state<CountryCodeA2>.txt.

Generating the postal location (city) fixed width file. The output file is called postal<CountryCodeA2>.txt.

Generating the postal code (zipcode) fixed width file. The output file is called code<CountryCodeA2>.txt.

Caution: During the road file and distance override steps of the creation process, the following error message can be displayed:

An unsupported operation was attempted.



This is normal. The error is generated during the road file creation step if your raw data has no postal code information and, therefore, it cannot map postal data. The postal data is not required for successful road file generation.

The error is generated during the distance override step if your raw data contains no distance override records.

When the error message is generated, enter Y to continue with the distance engine creation process.

3. Click Done.

Completion After the distance engine generation has completed successfully, you can use your distance engine for your modeling, planning, and execution requirements. For more information, see the JDA Transportation Planner documentation.


File and table formats

Chapter 4. File and table formats This chapter provides information on the formats of the tables in the Access database provided with the distance engine creation tool. It also provides the required formats of the input files used to create the distance engine tables, and the generated output tables.

The distance engine creation process includes the following steps:

1. Create raw location and distance data flat files in delimited file formats using the following ways:

1. Enter the data using the formats described in "distance creation raw data flat files" (on page 35).

2. Populate the data to the Microsoft "distance creation access database" (on page 28) and export them to flat files using the included macro.

2. Use the Distance Engine Creation Wizard to convert the raw data to the required "distance engine input files" (on page 39).

3. Use the Distance Engine Creation Wizard to convert the input files to the "distance Engine output tables" (on page 46).

Distance creation Access database The Access database provided with the distance engine creation tool contains tables, in which you can populate distance engine input data,

• "COUNTRIES table" (on page 28)

• "LOCATIONS table" (on page 29)

• "DISTANCES table" (on page 29)

To use location aliases, you must also populate:

• "LOCATION_ALIASES table" (on page 30)

During the distance engine creation process, macros in the Access database generate a set of additional tables based on data provided earlier in the process:

• "GEOVALIDLOCATIONS table" (on page 31)

• "NODELOCATIONS table" (on page 31)

• "OVERRIDEDISTANCES table" (on page 32)

• "ROADDISTANCESWITHDIFFORIGDESTCOUNTRY table" (on page 33)

• "ROADDISTANCESWITHSAMEORIGDESTCOUNTRY table" (on page 34)

COUNTRIES table The records for the standard set of countries and their respective codes are pre-inserted in this table.

Field Name Data Type Length Description

Country Code Name

Alphanumeric 40 Name of the country.




Country Code ISO2

Alphanumeric 2 The unique two-character code by which the distance engine identifies the country.

Country Code ISO3

Alphanumeric 3 The unique three-character code by which the country is identified in location descriptions used in execution, planning, and modeling.

LOCATIONS table Use this table to populate all the locations defined for countries used in execution, planning, and modeling.

Field Name Data Type Length Description Required

PostalCode Alphanumeric 10 The postal code value for the location. This field is optional, but if you have this information, it is recommended to include it to make locations and associated distances accurate.

No

State Alphanumeric 2 The two-character value for the state. If you do not have state information, populate this value with the Country Code ISO2 value.

Yes*

City Alphanumeric 32 The city value for the location. Yes

Latitude Number The latitude value of the location. Yes

Longitude Number The longitude value of the location. Yes

Country Code ISO2

Alphanumeric 2 The two-character code by which the distance engine identifies the country.

Yes

IsNode Boolean 3 Indicate which locations are to be used as nodes. If enabled, the location is used as a node.

Yes

DISTANCES table Use this table to populate the distances and transit times between pairs of locations. For each distance and transit time record, provide the qualifiers (City/State/Country) of the locations to be used as the origin (From) and the destination (To) as they are defined in the "LOCATIONS table" (on page 29).




PostalCodeFrom Alphanumeric 10 The postal code value for the origin location. It is optional.

No

StateFrom Alphanumeric 2 The state value for the origin location.

Yes

CityFrom Alphanumeric 32 The city value for the origin location.

Yes

PostalCodeTo Alphanumeric 10 The postal code value for the destination location. It is optional.

No

StateTo Alphanumeric 2 The state value for the destination location.

Yes

CityTo Alphanumeric 32 The city value for the destination location.

Yes

Distance(Km*10) Integer The distance between the origin and destination. You can enter Kilometers or Miles, but the distance unit of measure must be consistent throughout the table.

Yes

TransitTime(Min) Integer The transit time between the origin and destination. Enter the value in minutes.

Yes

CountryISO2From Alphanumeric 2 The two-character country code (the ISO2 value) for the origin location.

Yes

CountryISO2To Alphanumeric 2 The two-character country code (the ISO2 value) for the destination location.

Yes

IsOverride Boolean If this field is disabled, the distance and transit time record is a node-based file entry and the origin and destination locations must be nodes (as specified in the LOCATIONS table). If this field is enabled, the origin and destination locations can be any valid locations from the LOCATIONS table.

Yes

LOCATION_ALIASES table If you use aliases for a location, use this table to populate the mappings of these aliases to locations as defined in the "LOCATIONS table" (on page 29). You can define one or more aliases for each location in the LOCATIONS table.




CityAlias Alphanumeric 32 The alias that the distance engine can map to an existing location.

Yes

State Alphanumeric 2 The state value of the actual location as defined in the LOCATIONS table.

Yes*

City Alphanumeric 32 The city value of the actual location as defined in the LOCATIONS table.

Yes

CountryCode ISO2 Alphanumeric 2 The two-character country code of the actual location as defined in the LOCATIONS table.

Yes

GEOVALIDLOCATIONS table This table contains the locations that are valid, but are not defined as nodes.


PostalCode Alphanumeric 10 The postal code value for the location. It is optional, but if you have this information, it is recommended to include it to make locations and associated distances accurate.


City Alphanumeric 32 The city value for the location.

Latitude Number The latitude value of the location.

Longitude Number The longitude value of the location.

Country ISO2 Alphanumeric 2 The two-character code by which the distance engine identifies the country.

NODELOCATIONS table This table contains the locations that are valid, and are defined as nodes.


PostalCode Alphanumeric 10 The postal code value for the location. It is optional, but if you have this information, it is recommended to include it to make locations and associated distances accurate.


City Alphanumeric 32 The city value for the location.




Latitude Number The latitude value of the location.

Longitude Number The longitude value of the location.

Country ISO2 Alphanumeric 2 The two-character code by which the distance engine identifies the country.

OVERRIDEDISTANCES table This table contains the distances and transit time records defined as overrides.


PostalCodeFrom Alphanumeric 10 The postal code value for the origin location. This field is optional.

No


Yes


Yes

PostalCodeTo Alphanumeric 10 The postal code value for the destination location. This field is optional.

No


Yes


Yes


Yes


Yes


Yes


Yes




IsOverride Boolean If this field is disabled, this distance and transit time record is a node-based file entry and the origin and destination locations must be nodes (as specified in the LOCATIONS table). If this field is enabled, the origin and destination locations can be any valid locations from the LOCATIONS table.

Yes

ROADDISTANCESWITHDIFFORIGDESTCOUNTRY table This table contains the distance and transit time values for those origin and destination pairs where the origin is in a different country than the destination.



No


Yes


Yes


No


Yes


Yes


Yes


Yes


Yes


Yes





Yes

ROADDISTANCESWITHSAMEORIGDESTCOUNTRY table This table contains the distance and transit time values for those origin and destination pairs where the origin is in the same country as destination.



No


Yes


Yes


No


Yes


Yes

Distance(Km*10) Integer The distance between the origin and destination. You can enter in Kilometers or Miles, but the distance unit of measure must be consistent throughout the table.

Yes


Yes


Yes


Yes





Yes

Distance creation raw data flat files You must populate a set of delimited flat files as the source of your location and distance data:

• "Countryraw.txt file" (on page 35)

• "Geovalidlocationraw.txt file" (on page 36)

• "Nodelocations.txt" (on page 36)

• "Roaddistancerawsamecountry.txt" (on page 37)

• "Roaddistancerawdifferentcountry.txt" (on page 37)

If you create location aliases, you also must populate:

• "Locationaliasraw.txt" (on page 38)

Note: If you are using the Access database provided with the distance engine creation tool, a macro in the database converts the Access tables to these delimited flat files for you. For more information, see "Distance creation Access Database" (on page 28).

The order of the fields within the files must match the order specified in the descriptive table in this document.

Countryraw.txt file A standard set of countries and their associate codes are pre-inserted in this file.


Country Code Name

Alphanumeric 40 Name of the country

Country Code ISO2

Alphanumeric 2 The unique two-character code by which the distance engine identifies the country.

Country Code ISO3

Alphanumeric 3 The unique three-character code by which the country is identified in location descriptions used in execution, planning, and modeling.



Geovalidlocationraw.txt file Use this table to populate all the locations defined for countries used in execution, planning, and modeling but are not node locations.


PostalCode Alphanumeric 10 The postal code value for the location. If you have this information, it is recommended to include it to make locations and associated distances accurate. This field is optional.

No


Yes*




Country Code ISO2


Yes

Nodelocations.txt Use this table to populate all the locations defined for countries used in execution, planning, and modeling, and that are node locations.


PostalCode Alphanumeric 10 The postal code value for the location. If you have this information, it is recommended to include it to make locations and associated distances more precise. This field is optional.

No


Yes*




Country Code ISO2


Yes



Roaddistancerawsamecountry.txt Use this file to define the distance and transit time values for those origin and destination pairs where the origin is in the same country as the destination.



No


Yes

CityFrom Alphanumeric 32 The city value for the origin location. Yes


No


Yes


Yes

Distance(Km*10) Integer The distance between the origin and destination. You can enter in Kilometers or Miles, but the distance of unit of measure must be consistent throughout the table.

Yes


Yes


Yes


Yes

IsOverride Boolean If this is disabled, the distance and transit time record is a node-based file entry and the origin and destination locations must be nodes (as specified in the nodelocationraw.txt file). If this field is enabled, the origin and destination locations can be any valid locations from the geovalidlocationraw.txt file.

Yes

Roaddistancerawdifferentcountry.txt This table contains the distance and transit time values for those origin and destination pairs where the origin is in the same country as the destination.





No


Yes

CityFrom Alphanumeric 32 The city value for the origin location. Yes


No


Yes


Yes

Distance(Km*10) Integer The distance between the origin and destination. You can enter in Kilometers or Miles, but the distance unit of measure must be consistent throughout the table.

Yes


Yes


Yes


Yes

IsOverride Boolean If this is disabled, the distance and transit time record is a node-based file entry and the origin and destination locations must be nodes (as specified in the nodelocationraw.txt file). If this field is enabled, the origin and destination locations can be any valid locations from the geovalidlocationraw.txt file.

Yes

Locationaliasraw.txt If you use location aliases, use this table to populate the mappings of these aliases to locations as defined in the LOCATIONS table. You can define one or more aliases for each location in the LOCATIONS table.


CityAlias Alphanumeric 32 The alias that the distance engine maps to an existing location.

Yes




State Alphanumeric 2 The state value of the actual location as defined in the geovalidlocationraw.txt file.

Yes*

City Alphanumeric 32 The city value of the actual location as defined in the geovalidlocationraw.txt file.

Yes

CountryCodeISO2 Alphanumeric 2 The two-character country code of the actual location as defined in the geovalidlocationraw.txt file.

Yes

Mapping files The map files provide the required formats for the raw data files and are used during the data validation part of the distance engine creation process. The map files are:

• COUNTRY.MAP

• STATE.MAP

• PLACE.MAP

• POSTAL.MAP

• ALIAS.MAP

• ROADSAMECOUNTRY.MAP

• ROADDIFFERENTCOUNTRY.MAP

• CUSTOMDISTANCETRANSITTIME.MAP

Distance Engine input files Input File

Name Description Output Table Name Description

"Country.txt" (on page 40)

Country "Country.dat" (on page 47)

Country output. There is only one country file.

"State[A2].txt" (on page 40)

State "State.[A2]" (on page 47)

State output per country

"Postal[A2].txt" (on page 41)

Location address "Location.[A2]" (on page 47)

Location output per country

"Code[A2].txt" (on page 42)

Latitude and longitude by postal code

"Loc_Post.[A2]" (on page 47) , "City.[A2]" (on page 47)

Postal Code/Latitude/Longitude output and City output per country

"Node[A2].txt" (on page 42)

Node (city, latitude and longitude)

"Node.[A2]" (on page 47)

Node output per country

"Road[A2].txt" (on page 43)

Distance and transit times within a country

"Road.[A2]" (on page 47)

Distance and transit times output per country



Input File Name Description Output Table Name Description

"Road.txt" (on page 44)

Distance and transit times between countries

"[A2_FROM]_[A2_TO].rd" (on page 48)

Distance and transit times output for from country and to country.

"Alias[A2].txt" (on page 45)

Location aliases "Alias.[A2]" (on page 48)

City alias table. It is optional.

"Custom.txt" (on page 45)

Override distance and transit times

"Custom.rd" (on page 48)

Custom distance and time table. It is optional.

The following table lists the input files and their corresponding output tables.

Country.txt The corresponding binary output table for this input file is "Country.dat" (on page 47).

The following table describes the required format for country.txt.

Field Description Length (# characters) Type Notes

Country Name 40 Alphanumeric

Country Code ISO A2 2 Alphanumeric Must be unique.

Country Code ISO A3 3 Alphanumeric Must be unique.

Country Car Code 3 Alphanumeric

Country Code FIPS 2 Alphanumeric

Country Minimum 2 Alphanumeric The minimum length of postal codes for this country.

Country Maximum 2 Alphanumeric The maximum length of postal codes for this country.

Country Remove 2 Alphanumeric The number of characters in the postal code that can be removed from the end.

Region Name 20 Alphanumeric The name of the region in which this country is found, from the region list.

Country ISO Number 3 Numeric

End of Record 2 The end of record marker, consisting of a line feed and carriage return.

State[A2].txt The format of the state/province input file state[A2].txt (where A2 is the two-character Country Code A2 value from the Country file) is described in the following table.

The corresponding output table is state.[A2], where A2 is the two-character Country Code A2. One state/province table is created per country.




State/Province Name 20 Alphanumeric Must be unique.

State/Province Abbreviation

6 Alphanumeric Must be unique.

State/Province Code A4

4 Alphanumeric Must be unique.

State/Province A2 2 Alphanumeric Must be unique.

Delta 2 Alphanumeric The minimum number of zip or postal codes to consider for node building. Used in the creation of city nodes for distance and time calculations.

Flags 2 Numeric

End of Record 2 The end-of-record marker, consisting of a line feed and carriage return.

Postal[A2].txt The format of the location address input file postal[A2].txt (where A2 is the two-character Country Code A2 value from the Country file) is described in the following table.

The corresponding output table is location.[A2], where A2 is the two-character Country Code A2. One location address table is created per country.

If latitude and longitude are missing in the location file, you can create postal latitude/longitude data with a separate process. For more information, see "Code[A2].txt" (on page 42).


State/Province Code 2 Alphanumeric Must be a valid state/province code. The combination of state/province code, city name, and postal code must be unique.

City Name 32 Alphanumeric The combination of state/province code, city name and postal code must be unique.

Postal Code 10 Alphanumeric The combination of state/province code, city name and postal code must be unique.

Latitude 10 Numeric A ten-digit number with four decimal places assumed [(+/-)999999999].

Longitude 10 Numeric A ten-digit number with decimal specified [(+/-)999999.9999]. Only four decimal places are stored even if more decimal places are specified.





Code[A2].txt To fix missing latitude and longitude in the location address file (for more information, see "Postal[A2].txt" (on page 41)), create an input postal/latitude and longitude file using the format described in the following table.

The postal address input file is code[A2].txt, where A2 is the two-character Country Code A2 value from the Country file.

The corresponding output table is loc_post.[A2], where A2 is the two-character Country Code A2. One location postal table is created per country. For each country, a new unique postal latitude/longitude table is created, and:

• Locations defined with incorrect latitude/longitude are fixed.

• If same postal codes in the location table have different latitude and longitude values, then the first valid location is considered.


Postal Code 10 Alphanumeric

Must be unique.



End of Record 2 The end of record marker, consisting of a line feed and carriage return.

Node[A2].txt The format of the city node input file node[A2].txt (where A2 is the two-character Country Code A2 value from the Country file) is described in the following table.

The corresponding output table is node.[A2], where A2 is the two-character Country Code A2. One city node table is created per country.

Note: The city node table can be created using data from external distance engines and by using the Node[A2].txt input file.


State/Province Code 2 Alphanumeric Must be a valid state/province code. The combination of state/province code and city name must be unique.




City Name 32 Alphanumeric The combination of state/province code and city name must be unique.




Road[A2].txt The format of the distance and transit time input file road[A2].txt (where A2 is the two-character Country Code A2 value from the Country file) is described in the following table.

The corresponding output table is road.[A2], where A2 is the two-character Country Code A2. The distance and transit time output table is created using city nodes generated from the input file "Node[A2].txt" (on page 42) and output table "Node.[A2]" (on page 47)).

One distance and transit time table is created per road[XX].txt input file.

Note: The distance and transit time table can be created using data from external distance engines and by using the Road[A2].txt input file.


From State/Province Code

2 Alphanumeric Must be a valid state/province code. The combination of From state/province code, From city name, To state/province code, and To city name must be unique.

From City Name 32 Alphanumeric The combination of From state/province code, From city name, To state/province code, and To city name must be unique.

To State/Province Code

2 Alphanumeric Must be a valid state/province code. The combination of From state/province code, From city name, To state/province code and To city name must be unique.

To City Name 32 Alphanumeric The combination of From state/province code, From city name, To state/province code and To city name must be unique.

Distance 7 Numeric The distance between the From and To locations. Distance must be expressed in 1/10 of miles.

Time 7 Numeric The transit time between the From and To locations. Time must be expressed in minutes.





Road.txt The distance and transit time input file road.txt provides data for distance and transit times between countries. It has the format described in the following table.

The corresponding output table is [A2_FROM]_[A2_TO].rd, where A2 is the two-character Country Code A2 representing each country (From and To).


From Country Code A2

2 Alphanumeric

The two-character code representing the From country. Must be a valid country code defined in "Country.txt" (on page 40). The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.


2 Alphanumeric

Must be a valid state/province code. The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.

From City Name 32 Alphanumeric

The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.

To Country Code A2 2 Alphanumeric

The two-character code representing the To country. Must be a valid country code defined in "Country.txt" (on page 40). The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.


2 Alphanumeric

Must be a valid state/province code. The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.

To City Name 32 Alphanumeric

The combination of From country code, state/province code, city name, and To country code, state/province code, and city name must be unique.





Time 7 Numeric The transit time between the From and To locations. Time must be entered in minutes.


Alias[A2].txt The format of the city alias input file Alias[A2].txt, where A2 is the two-character Country Code A2 value from the Country file, is described in the following table.

The corresponding output table, Alias.[A2], is used to handle different spellings of city names or different languages. One city alias table is created per country.


State/Province Code 2 Alphanumeric Must be a valid state/province code. The combination of state/province code and city name must be unique.

City Name 32 Alphanumeric The combination of state/province code and city name must be unique.

Alias State/Province Code

2 Alphanumeric The combination of alias state/province code and alias city name must be unique.

Alias City Name 32 Alphanumeric The combination of alias state/province code and alias city name must be unique.


Custom.txt The custom distance and transit time table allows you to modify distance and transit times between specific locations.

The input file is Custom.txt, and has the format described in the following table.

The corresponding output table is custom.rd.


From Country Code A2

2 Alphanumeric

The two-character code representing the From country. Must be a valid country code defined in "Country.txt" (on page 40). The combination of From country code, state/province code, city name, postal code, and To country code, state/province code, city name, and postal code must be unique.





2 Alphanumeric

Must be a valid state/province code. The combination of From country code, state/province code, city name, postal code, and To country code, state/province code, city name, and postal code must be unique.

From City Name 32 Alphanumeric

The combination of From country code, state/province code, city name, postal code, and To country code, state/province code, city name and postal code must be unique.

From Postal Code 10 Alphanumeric


To Country Code A2 2 Alphanumeric

The two-character code representing the To country. Must be a valid country code defined in "Country.txt" (on page 40). The combination of From country code, state/province code, city name, postal code, and To country code, state/province code, city name and postal code must be unique.


2 Alphanumeric

Must be a valid state/province code. The combination of From country code, state/province code, city name, postal code, and To country code, state/province code, city name and postal code must be unique.

To City Name 32 Alphanumeric


To Postal Code 10 Alphanumeric



Time 7 Numeric The transit time between the From and To locations. Time must be entered in minutes.


Distance Engine output tables These tables contain the actual distance engine. They are the final output of the distance engine creation process.



Country.dat Country.dat is the output table based on country data in the input file "Country.txt" (on page 40).

State.[A2] State.[A2] is the state/province table generated from "State[A2].txt" (on page 40), where A2 is the two-character Country Code ISO2. One state/province table is created per country.

Location.[A2] Location.[A2] is the location address table generated from "Postal[A2].txt" (on page 41), where A2 is the two-character Country Code ISO2. One location address table is created per country.

If latitude and longitude values are missing in the location table, you can create postal latitude/longitude data with a separate process. For more information, see "Code[A2].txt" (on page 42) and "Loc_Post.[A2]" (on page 47).

Loc_Post.[A2] To fix missing latitude and longitude values in the location address table (for more information, see "Postal[A2].txt" (on page 41) and "Location.[A2]" (on page 47)), you can create an input postal/latitude and longitude file "Code[A2].txt" (on page 42), where A2 is the two-character Country Code ISO2 value from the Country table.

The corresponding output table is loc_post.[A2]. For each country, a new unique postal latitude/longitude table is created, and:

• Locations defined with incorrect latitude/longitude values are fixed.

• If same postal codes in the location table have different latitude and longitude, then the first valid location is considered.

City.[A2] City.[A2] is the city table generated from "Postal[A2].txt" (on page 41) and "Node[A2].txt" (on page 42), where A2 is the two-character Country Code ISO2 value. One city table is created per country.

Node.[A2] Node.[A2] is the city node table generated from the input file "Node[A2].txt" (on page 42), where A2 is the two-character Country Code ISO2 value from the Country table.

One city node table is created per country.

Note: The city node table can also be created using data from external distance engines and by using the node[A2].txt input file.

Road.[A2] Road.[A2] is the distance and transit-time table generated from the input file "Road[A2].txt" (on page 43), where A2 is the two-character Country Code ISO2.

One distance and transit-time table is created per road[XX].txt input file.

Note: The distance and transit-time table can also be created using data from external distance engines and by using the Road[A2].txt input file.



[A2_FROM]_[A2_TO].rd [A2_FROM]_[A2_TO].rd is the output table generated from the input file "Road.txt" (on page 44), which provides data for distance and transit times between two different countries.

A2 is the two-character Country Code ISO2 representing each country (From and To).

Alias.[A2] The city alias output table, Alias.[A2], is generated from "Alias[A2].txt" (on page 45), where A2 is the two-character Country Code A2 value from the Country table. City aliases are used to handle different spellings of city names or different languages. One city alias table is created per country.

Custom.rd The custom distance and transit-time table allows you to modify distance and transit times between specific locations.

Custom.rd is the output table generated from the "Custom.txt" (on page 45) input file.


API description

Chapter 5. API description This section provides information on implementing the APIs necessary to connect geocrt.exe to your external distance engine. When you use geocrt, provide the name of the DLL implementing the APIs as a command line parameter.

Note: This information is available in the geocrtinterface.h header file provided with the distance engine creation tool. The file is located in the distance engine creation tool folder (by default, ..\i2distanceengine\creationtool).

The DLL must export the following APIs:

• Server initialization functions

• Error logging functions

• City latitude longitude conversion functions (optional )

• Trip initialization functions

• Distance/time calculation function

Structure representing the location information struct GEOLocation{

char Street [200];

char City [200];

char State [200];

char Postal [32];

char Country [40];

};

Server initialization functions GEOCRTOpenDistanceTimeServer • Name: GEOCRTOpenDistanceTimeServer

• Purpose: Initialize the server.

• Parameters:

• argc,argv : The command line options that are used to start GEOCRT.

Returns the ID of the server Connection. Returns -1 on failure.

int GEOCRTOpenDistanceTimeServer( int argc, char* argv[]);

GEOCRTCloseDistanceTimeServer • Name: GEOCRTCloseDistanceTimeServer

• Purpose: Close the active server connection

• Parameters: None


API description

Returns 0 on success. Returns -1 on failure.

int GEOCRTCloseDistanceTimeServer();

Error logging functions GEOCRTGetError • Name: GEOCRTGetError

• Purpose: Returns the last error number on exception


Returns Error Number. Returns 0 in case there is no error.

int GEOCRTCloseDistanceTimeServer();

GEOCRTGetErrorString • Name: GEOCRTGetErrorString

• Purpose: Returns the corresponding error text for a given error number

• Parameters:

• iErrorCode (IN): Valid error code

• pacErrorBuff (OUT): Valid text buffer for the string

• iBuffLen (IN): Length of the text buffer

Returns number of bytes that are copied to the buffer. Returns -1 for error.

int GEOCRTGetErrorString(int iErrorCode, char *pacErrorBuff, int iBuffLen);

City latitude/longitude conversion functions Note: The following two functions are optional. You can use them if you need to generate latitude/longitude while generating Nodes, or if you need to use option 3 to generate latitude/longitude in geocrt.exe.

GEOCRTLocationNameToLatLong • Name: GEOCRTLocationNameToLatLong

• Purpose: Converts the location name to latitude and longitude

• Parameters:

• tLocationname (IN): Location name structure

• pdLatitude (OUT): Latitude in degree,minute,seconds format [ +/- ########## ]

• pdLongitude (OUT): Longitude in degree,minute,seconds format [ +/- ########## ]

• iBuffLen (IN): Length of the text buffer

Returns -1 for error.

int GEOCRTLocationNameToLatLong(const GEOLocation& tLocationname, double

* pdLatitude, double * pdLongitude);


API description

GEOCRTLatLongToLocationName • Name: GEOCRTLatLongToLocationName

• Purpose: Converts the latitude and longitude to a location name

• Parameters:

• dLatitude (IN): Latitude in degree,minute,seconds format [ +/- ########## ]

• dLongitude (IN): Longitude in degree,minute,seconds format [ +/- ########## ]

• ptLocationname (OUT): Location name

Returns -1 for error.

int GEOCRTLatLongToLocationName( const double dLatitude, const double dLongitude, GEOLocation *ptLocationname );

Trip initialization functions GEOCRTNewTrip • Name: GEOCRTNewTrip

• Purpose: The method to be invoked before any distance/time computation. An entry procedure to set the options. GeoCrt invokes this method before calling calculate distance.

• Parameters: None int GEOCRTNewTrip();

GEOCRTDeleteTrip • Name: GEOCRTDeleteTrip

• Purpose: The method to be invoked after completing the distance /time computation. An exit procedure to clean up the options set using GEOCRTNewTrip. GeoCrt invokes this method after calling calculate distance.


int GEOCRTDeleteTrip();

Distance/time calculation function GEOCRTCalcDistanceandTime • Name: GEOCRTCalcDistanceandTime

• Purpose: Calculates the distance and time for a provided pair of locations.

The DLL handles the route type, such as PRACTICAL, and SHORTEST.

• Parameters:

• pacOrigLoc (IN): Origin Location.

Location string is in the format (Street,city,state,postal,country) or it contains latitude longitude information in the degree, minute, seconds, direction format (DDDMMSSP, DDDMMSSP).


API description

• pacDestLoc (IN): Destination Location.

Location string is in the format (Street,city,state,postal,country), or it contains latitude longitude information in the degree, minute, seconds, direction format (DDDMMSSP, DDDMMSSP).

• lMinutes (OUT): Minutes (to be passed as a reference)

Returns the distance between two points in miles. Returns -1 for error.

double GEOCRTCalcDistanceandTime(const char *pacOrigLoc, const char *pacDestLoc, long *lMinutes);


Java distance interface

Chapter 6. Java distance interface The Transportation Modeler Java distance interface enables you to create your own Java code to integrate with any distance provider. The JavaDistanceInterface.dll defines a Java interface that supports both 32-bit and 64-bit implementations.

The implementation of the Java distance interface for use with Transportation Manager is TMOrbClient.jar, which implements all of the classes, functions and parameters. All classes in this implementation are named the same as the defaults and it requires minimum configuration. To use JavaDistanceInterface(32) with TMOrbClient.jar to connect to a TM distance engine over Java Corba sockets, you must use the DSC Host in the distance engine setup in a machine with a running DSC.

When using an external distance engine with Transportation Modeler, define "Interface Parameters" on the Distance tab of the Transportation Modeler Solver Options dialog box. The distance engine is determined by the external DLL name setting. When you install on 32-bit system architecture, the external DLL name is TMDistanceInterface. When you install on 64-bit system architecture, the external DLL name is JavaDistanceInterface.

PC Miler distance engine The PC Miler distance engine is supported through use of the tp-pcmiler.jar. Run the interface through use of an editable batch file, runPCMilerDistanceServer.bat where you can set the path to the ALK PCMiler jar file, the path to your installation of Java, the port to use, the Route Mode and the location naming convention. Define "Interface parameters" on the Distance tab of the Transportation Modeler Solver Options dialog box.

Interface parameters To use Java for the interface, specify the JavaDistanceInterface dll (either JavaDistanceInterface32 for 32-bit implementations or JavaDistanceInterface for 64-bit implementations), and use the external parameters (1-5) to customize it to your implementation:

Parameters 1 and 2 control JVM creation. These parameters are applicable only when there is no JVM installed previously. A JVM exists before JavaDistanceInterface initialization if:

• Using Interactive Optimizer or Transportation Modeler, and have run with XML file generation (Write Metadata).

• Using the Shipment Consolidation Engine (SCE). If you are using JavaDistanceInterface within SCE, parameters 1 and 2 are not used.

Parameter Number Parameter Required? Default

1 JVM initialization file

optional None

2 Classpath Required for Transportation Modeler if XML file generation has not been run. optional for other products

./lib/cis.jar;./lib/cis-util.jar;./lib/TMOrbClient.jar;

3 Init Class Name optional com.i2.tmtools.orb.dsc.DscClient



Parameter Number Parameter Required? Default

4 Distance Class optional com.i2.tmtools.orb.distsrv.DistSrvClient

5 Return Class optional com.i2.tmtools.orb.distsrv.DistResult

Parameter 1 allows you to use a properties file to define all of the JVM options for JVM initialization. The path is similar to working directory of application. The default is none.

Parameter 2 allows you to specify a classpath to be used for JVM initialization. This parameter is required for Transportation Modeler. The classpath is similar to the Transportation Modeler executable (TMod.exe). As Transportation Modeler installs the cis-util.jar and log4j.jar CIS files, you can set the path for these jars in the folder under Transportation Modeler:

./lib/cis-util.jar;./lib/log4j.jar;./lib/TMOrbClient.jar;

Interface definition • Init class: The initialization class with method signature (Ljava/lang/String;)Z. Enter a string,

where the string is the DSC host, on the class defined as Parameter3 and it returns a boolean. Init class must have a function as:

static bool init(String)

The string provided is the DistanceHost from your distance engine setup (in setup.xml or the Options dialog for Transportation Modeler and Interactive Optimizer for Transportation Manager).

• setDivision function [optional]: This function is setDefaultDivision, with method signature (Ljava/lang/String;)V. Enter a string, where the string is the division on the incoming plan on the class defined as Parameter4 and it returns void.

• getDistance/Time function: This function is getDistanceAndTime, with signature (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZZ)L<param 5>. Enter three strings and two booleans and it returns an object of class Parameter 5.

The distance class must have a function as:

static <retclass> getDistanceAndTime(String, String, String, bool bool)

The returned object is retclass (as defined by external 5) or null for a failure. The parameters for this function are:

Parameter Number Type Description

1 String Origin location as: GEO:country|state|city|zip|block number|unit number|street|lat|lon

2 String Destination location as: GEO:country|state|city|zip|block number|unit number|street|lat|lon

3 String Distance engine to use: if an override distance engine is defined on a tariff, this string is defined there. Otherwise blank.

4 Boolean Origin isOverride, Whether the origin location has the lat/lon override flag set to true.



Parameter Number Type Description

5 Boolean Destination isOverride, Whether the destination location has the lat/lon override flag set to true

• a return class: Defined as Parameter5. The return class must have the following functions:

• int getDistance(): Must return the distance between the origin and destination, in 1/10 miles. It does not accept any parameters.

• int getTime(): Must return the time between the origin and destination, in minutes. It does not accept any parameters.

Configure Transportation Modeler to use the Java distance interface The configuration information enables you to connect Transportation Modeler with a distance engine using the Java distance interface. Connecting Transportation Modeler to a Transportation Manager distance engine or to a PC Miler distance engine are specific cases of this configuration. For more information, see "Configuring Transportation Modeler to use a Transportation Manager Distance Engine" and "Configuring Transportation Modeler to Use a PC Miler Distance Engine".

Note: While using the 64-bit version of Transportation Modeler with the Java distance interface, use the Oracle JRockit 64 bit version of Java to load the JavaDistanceInterface.dll. Modify your system path to point to Oracle JRockit 64 bit. For example: The path needs to be edited to read:

C:\jrockit1.6.0_24_64\jre\bin\jrockit

1. Select the Distance tab and set the Distance Engine to Manager (External) from the Transportation Modeler Solver Options dialog box.

2. Enter the External DLL Name and Distance Host for the distance engine.

3. Enter the "Interface parameters" as required for your distance engine implementation.

The entered settings are updated in the Transportation Modeler registry. The settings in the following table are used to connect to a Transportation Manager distance engine:

Registry Section Key Name Type Description Values

HKEY_CURRENT_USER\Software\JDA Software\JDA Transportation Modeler\9.0\Rating Engine Settings

Transportation Manager DSC Host Name

String Key

Name of the DSC host machine.

Enter the name of the machine that is acting as your DSC host. The value can be localhost if applicable.

HKEY_CURRENT_USER\Software\JDASoftware\JDA Transportation Modeler\9.0\Optimizer



Registry Section Key Name Type Description Values

External Distance Engine DLL

String Key

Name of the C++ dll.

If blank (default), TMDistanceInterface is considered. For example, enter JavaDistanceInterface32 for 32-bit Transportation Modeler or JavaDistanceInterface for 64-bit Transportation Modeler.

External Distance Engine Parameter 1

String Key

The JVM initialization properties file

The default is empty.


String Key

The classpath to be used when setting up Transportation Modeler to use the Java distance interface.

The classpath is related to the Transportation Modeler executable (TMod.exe). For example:

./lib/cis-util.jar;./lib/log4j.jar;./lib/TMOrbClient.jar;

Note: Transportation Modeler installs the cis-util.jar and log4j.jar CIS files, so the path in the example refers to the location under Transportation Modeler.


String Key

Initialization class The default is com/i2/tmtools/orb/jni/DscClient


String Key

Initialization class The default is com/i2/tmtools/orb/jni/DistSrvClient


String Key

Initialization class The default is com/i2/tmtools/orb/jni/DistResult

Configure Transportation Modeler to use a Transportation Manager distance engine Note: While using the 64-bit version of Transportation Modeler with the Java Distance Interface, use the Oracle JRockit 64-bit version of Java to load the JavaDistanceInterface.dll. Modify your system path to point to Oracle JRockit 64-bit. For example, The path needs to be edited as: C:\jrockit1.6.0_24_64\jre\bin\jrockit



1. Set the Distance Engine to Manager (External) in the Transportation Modeler Solver Options dialog box.

2. Enter the External Engine Settings (TM/Java) parameters as displayed in the following table:

Parameter Required? Value

External DLL Name

Required If blank (default), TMDistanceInterface is considered. Enter JavaDistanceInterface32 for 32-bit Transportation Modeler or JavaDistanceInterface for 64-bit Transportation Modeler.

Distance Host Required <hostmachine>:<hostport>

where <hostmachine> is the name of the host machine <hostport> is the port on the host machine

Parameter 1 JVM initialization file

Optional None

Parameter 2 Classpath

Required for Transportation Modeler if XML file generation has not been run. Optional for other products

./lib/cis-util.jar,./lib/log4j.jar;./lib/tp-pcmiler.jar;

Parameter 3 Init Class Name

Optional com/i2/tmtools/orb/jni/DscClient

Parameter 4 Distance Class

Optional com/i2/tmtools/orb/jni/DistServClient

Parameter 5 Return Class

Optional com/i2/tmtools/orb/jni/DistResult

3. Click OK.

Configure Transportation Modeler to use a PC Miler distance engine Perform the following steps to use an external PC Miler distance engine with Transportation Modeler:

Edit and run the runPCMilerDistanceServer batch file Edit the runPCMilerDistanceServer.bat file 1. Navigate to the \bin folder under your Transportation Modeler installation folder.

2. Edit runPCMilerDistanceServer.bat and set the following values:

• ALK PCMiler jar path: The path to the alk.jar. For PCMiler version 22.1, the path is C:/Program Files/ALK Technologies/PCMWW221/Connect/Java.new/alk.jar.



• Java path: The path to install Java.

• Port: The port that the distance server must use.

• Route Mode: It controls distance calculations when using PC Miler. Valid values are:

• 0: (default) Practical

• 1: Shortest

• 2: National Network

• 3: Avoid Tolls

• 4: Air Distance

• 5: POV

• 6: 53

• Location Naming Convention: It defines a location name as input to PC Miler based on data such as the latlon, zip code (postal code), city and state, or full address. Valid values are 0, 1 and 2:

• 0: LatLon/Zip/City

If defined, LatLon is used, otherwise, if defined, Zip is used, otherwise, if defined, City, State is used. This is the default.

• 1: LatLon/Zip/City

If defined, LatLon is used, otherwise, if defined, Zip is used, otherwise, if defined, City, State is used. This is the default.

• 2: Full Address/LatLon

If defined, full address (including street name and number) in addition to Zip or City,State is used, otherwise, if defined, LatLon is used.

3. Save the batch file.

Run the runPCMilerDistanceServer.bat file 1. Open a DOS command prompt window and navigate to the \bin folder under Transportation

Modeler installation folder.

2. Enter runPCMilerDistanceServer.bat. The batch file runs.

Edit the distance parameters in the Solver Options dialog box 1. Set the Distance Engine to Manager (External) in the Transportation Modeler Solver Options dialog

box.

2. Enter the External Engine Settings (TM/Java) parameters as displayed in the following table:


Engine required Manager (External)

External DLL Name

required JavaDistanceInterface




Distance Host required <hostmachine>:<hostport>

where <hostmachine> is the name of the host machine <hostport> is the port on the host machine

Parameter 1 JVM initialization file

optional None

Parameter 2 Classpath

Required for Transportation Modeler if XML file generation has not been run. optional for other products

./lib/cis-util.jar,./lib/log4j.jar;./lib/tp-pcmiler.jar;

Parameter 3 Init Class Name

optional com.i2.logistics.tp.tools.pcminterface.PCMClient

Parameter 4 Distance Class

optional com.i2.logistics.tp.tools.pcminterface.PCMClient

Parameter 5 Return Class

optional com.i2.logistics.tp.tools.pcminterface.PCMResult

3. Click OK.


Index A A2_FROM]_A2_TO].rd [A2] • 44, 48 alias.A2] • 45, 48 aliasA2].txt • 48

format of aliasA2].txt • 45

C city.A2] • 47 country.dat • 40, 47 custom.rd • 48 custom.txt • 48

format of custom.txt • 45 distance data

source • 4

D distance data

source • 4 distance engine

external • 4 overview • 3

F files

map • 4 road A2_FROM]_A2_TO].rd • 48 custom.rd • 48

P postalA2].txt • 47

format of postalA2].txt • 41

R road.A2] • 43, 48

format of roadA2].txt • 43

S state.A2] • 40, 47 stateA2].txt • 47

format of stateA2].txt • 40

T third party distance provider • 5

requirements • 5 PC*Miler • 4


transportation modeler 9.0.0.0 distance engine user guide

Documents

document jda

jda warranty

jda application

jda documentation manageme

jda license agreement

jda software license

jda patents website

jda valuable trade secrets