Rail-Connect Mapping

Note: Rail-Connect Mapping was discontinued after version 28.

The interface to the PC*Miler Rail-Connect mapping functions gives you control over when and how pins, routes, and lines are drawn, and allows data about a pin to be displayed in a dialog box when the pin is chosen.

All arguments are strings, and the separator between elements in stops, styles, options, and labels is a vertical bar (|). For example, Newark NJ|Chicago IL|191600 is a valid series of stops, and Red|5 is a valid style. The separator for an importance range is two periods (..). For example, 1..4 is a valid importance range, as is simply 4 (the trip appears at levels 4 and higher).

Functions for Creating a Map Window

long PCRSCreateMapWin(HWND parentHWnd, const char* title, int width, int height, HWND* newWin)

This function creates a new map window. The first argument is the handle to the parent window. If the first argument is NULL, the new window will be created as a child of the desktop window. A standalone overlapped map window will be created as a child to this parent window and the title, width, and height for the map window will be set. This map window always stays on top of the parent window and it has a title and border.

This function returns the valid handle to the map window if it creates the map window successfully. It returns NULL on error.

long PCRSCreateMapChild(HWND parentHWnd, HWND* newWin)

This function creates a new map window as a child of the parent window. In this case, the map window is not a standalone window. Instead, it gets created in the client rectangle of the parent window. The new map window does not have a title or border.

The first argument, which is the handle to the parent window, must not be NULL.

This function returns the valid handle to the map window, if it creates the map window successfully. It returns NULL in case of error or if the parent window handle is NULL.

A Delphi canvas, Visual Basic Form, or a Borland OWL TFrameWindow could all be parent windows.

To resize the map canvas, you should forward resize messages from the parent to the map window child using PCRSResizeMapChild.

long PCRSResizeMapChild(short redraw)

This function returns FALSE if the parent window does not exist. Otherwise, it resizes a map canvas to the size of the parent window created using PCRSCreateMapWin. Calling this function will make the map child resize itself to fit exactly inside the parent window.

long PCRSIsMapWinValid()

Returns FALSE if the map window was not created successfully or TRUE if it was created successfully and is ready for further use. It is a quick programmatic way to check if the map window is ready for use.

Pin Functions

long PCRSPlotPin(const char* layerID, const char* ID, const char* importance, const char* symbol, const char* location, const char* data)

Create or update a pin. The pin is uniquely identified by layerID and ID. If the given pin does not exist, it is created. If it does exist, all data for the pin is updated. The return code is negative if there is an error. If the layer identified by layerID does not exist, then a layer is created.

• The field ID can be any text string.
• The field importance determines a level of importance for the given pin. The importance of a pin determines at what level of detail the pin is drawn. There are six levels of detail.
• For pins, importance can be a number between 1 and 8. Importance level 1 is the most important; pins with importance level 1 are always shown. Pins with importance level 8 are only shown when the user is zoomed in very tight.
• If you do not care about importance, specify “1” for the importance argument.
• Importance can be specified as a range, such as 1..3. If a pin’s importance is specified as a range, then it will only be shown when the map’s level of detail falls into that range.
• Ranges can be useful when trying to reduce clutter on the map. For example, you could create two pins—one for each state—displayed at importance levels 1..3, and 200 pins marked with importance levels 4..6. This way, at the U.S. level, only the two pins are shown, and as you zoom in, the 200 pins appear.

The field symbol must specify a valid symbol. It can be an internal DLL type (such as Green Box 5, Red Box 15—indicates size), or a user-supplied path to a .BMP or .PNG file (e.g., c:\pins\myIcon.bmp).

The field location is a text string specifying a Station/State, i.e., a station name followed by a two-character state abbreviation (example: Houston TX).

The field data is an optional list of up to 8 values for PC*Miler Rail to store and display in an information dialog when the pin is clicked on. The values in the list are delimited by vertical bars.

long PCRSDeletePin(const char* layerID, const char* ID)

This function deletes the pin identified by ID in the layer layerID.

long PCRSDeletePinMap(const char* layerID)

This function removes the layer identified by layerID from the map. All pins in the layer are deleted.

PC*Miler Rail-Connect Icons

TIP: Size the canvas before beginning to draw.

A PC*Miler Rail-Connect icon is a text string composed of two parts: type and color. Available icons are listed in the map_opts.ini file found in the App folder of your PC*Miler Rail installation.

In addition to the icons, a Box or Circle can be plotted with a size argument (e.g., Red Box 10) which sets the box’s size in pixels.

You can also plot icons of your own design. To do so, pass the complete path to a .BMP or .PNG file to the PlotPin or PlotPinID functions. For example, if you pass the path C:\ALK Technologies\PCRWINXX\pins\icon.bmp to either function, you’ll see a new bitmap with the word ICON on it displayed on your map. Pins must be in .BMP or .PNG format.

Trip and Line Functions

long PCRSPlotTrip(const char *orig, const char *origRR, const char *origGeo, const char*dest, const char*destRR, const char *destGeo, long*pMiles, const char *routeName)

This function calculates and draws a trip on the map where routeName is the feature layer to add the new trip to; this name will be displayed in the map window. Use routeName to delete this trip, using PCRSDeleteTripByName.

• orig and dest: string containing origin/destination place code
• origRR and destRR: origin/destination railroad SCAC code (4-char abbrev.)
• origGeo and destGeo: City, SPLC, FSAC, ERPC, or Rule260
• pMiles: pointer into which calculated trip distance will be placed (in tenths of miles/kms)

long PCRSPlotTrip2(const char *orig, const char *origRR, const char *origGeo, const char*dest, const char*destRR, const char *destGeo, long*pMiles, const char *routeName, const char* routeType, const char* routeMethod)

See PCRSPlotTrip above.

Additional arguments:

• routeType: I (interactive, i.e., standard) or A (autoroutes)
• routeMethod: F (familized, for autoroutes) or N (not familized, for standard)

long PCRSPlotLine(const char* layerID, const char* ID, const char* importance, const char* symbol, const char* locations)

Where layerID is the feature layer to add the new line to, ID is its unique identifier, importance is a range of numbers denoting which levels of detail it will appear at, symbol is what color and width to use, and locations is the list of points (PC*Miler Rail place names) that make up the line.

All arguments are strings, and the separator between elements in symbols and locations is a vertical bar (|). For example, Houston TX|Chicago IL|191600 is a valid series of points, and Red|5 is a valid symbol. The separator for an importance range is two periods (..). For example, 1..4 is a valid importance range, as is simply 4 (the trip appears at levels 4 and higher). An importance level of 1 is the highest, meaning the line will always appear.

long PCRSFrameLine(const char* layerID, const char* ID)

This function frames the line created using PCRSPlotLine.

long PCRSAddRouteToMap(Trip trip)

This function can be used to add a predefined route (created with PCRSNewTrip) to the map using its unique trip ID. This requires that the trip ID be valid, that the trip is already properly populated, and has been successfully run.

long PCRSDeleteRouteFromMap(Trip trip)

This function deletes the trip created using PCRSAddRouteToMap.

long PCRSDeleteTripByName(const char * routeName)

This function removes the trip identified by routeName.

long PCRSDeleteAllTrips()

This function deletes all trips created using PCRSPlotTrip or PCRSPlotTrip2.

long PCRSDeleteLine(const char* layerID, const char* ID)

This function removes the line identified by ID in the layer layerID.

Layer Management Functions

The user can group pins, trips, and lines into “layers” or “pinmaps.” These layers can be modified by the user through DLL function calls.

long PCRSSetLayerVisibility(const char* layerID, BOOL show)

This function changes the visibility of the layer specified by layerID. If the show parameter is non-zero, the layer is visible. If the show parameter is zero, the layer is hidden. It is NOT deleted. Layers can be shown or hidden as often as desired.

long PCRSFrameLayer(const char* layerID)

Zooms the map to include all the pins in the pinmap layer layerID.

long PCRSDeleteLayer(const char* layerID)

Deletes the layer specified by layerID.

long PCRSZoomIn()

Zooms the map in by one zoom level.

—>

long PCRSZoomOut()

Zooms the map out by one zoom level.