User Tools

Site Tools


desktop

Locator Desktop User Guide

The desktop version of Locator can be run on any version of Microsoft Windows. The application has built-in help and tool tips that show how to use it. This document has more detailed instructions, much of it similar to the built-in help, with videos and other tutorial material.

Installing

To install Locator download the 'setup.exe' from Locator Downloads. If this is the first time you have used locator on your computer double-click and follow the instructions. If you already have a version of locator on your computer then follow the Upgrading instructions instead.

When the installation is complete Locator will be started automatically. A Locator alert will be displayed that explains what to do next. The installer puts a Locator icon on the desktop and an entry in the Windows Start Menu. You can use either to start Locator.

When the installation is completed go to the Tools > Preferences > Edit menu and enter the settings you want. It is important to do this before using any other Locator functions. See the Preferences topic for more details.

Upgrading

To upgrade your version of Locator to the most recent you must use the following steps. Read through these before going ahead.

  1. Export your user data using these commands from the Locator main menu:
    1. Tools > License > Export,
    2. Tools > Locations > Export and
    3. Tools > Preferences > Export.
  2. Uninstall Locator using Start Menu > All Programs > SCADALink Locator > Uninstall from Windows. You can also use the Programs and Features item in the Control Panel. See the Uninstalling topic for details.
  3. Download the most recent version of Locator from the Locator website and install it by double-clicking the download. See the Installing topic for details.
  4. Import your user data using these commands from the Locator main menu:
    1. Tools > License > Import,
    2. Tools > Locations > Import,
    3. and Tools > Preferences > Import.

Your new Locator will have all locations, preferences, and the license that you previously used. Check Help > About to verify you have installed the new Locator version and that the license is the type you had previously. Use the Find tab to verify all locations have been imported. Use Tools > Preferences > Edit to verify your preferences are set.

Purchasing

A production and trial license are available. Both use the same version of the software which is freely available for download.

The trial license is free but has a thirty day or 10 conversions limit. You do not need to contact Sales to use a trial license. A trial license does not have to be registered.

To obtain a production license you must contact Sales and purchase one. Payment can be made by telephone using credit card or purchase order.

The downloadable software and further information are available on the website.

After payment is made you can then register the application. See the Registering topic for more details.

Registering

You need to register the license before Locator can be used in a production mode. If you do not register then Locator will automatically start in trial mode. A trial license does not require registration.

Start Locator by double-clicking the Locator icon on the desktop or by using the Start Menu.

To obtain a production license you must first contact Sales and make a payment. This can be done by telephone using credit card or purchase order. See the Purchasing topic for more details.

  • 1-403-243-5135 ext 2 (UTC-7, Mountain 8:00am to 5:00pm M-F)
  • sales@scadalink.com

Registering for Production Use

  1. Start Locator.
  2. Click 'Tools > License > Create'.
  3. Use the file chooser to navigate to a directory where you want to output the unauthorized license.
  4. Click 'Save' to put the license file on disk.
  5. Attach the license to an email message.
  6. The subject line should be 'Locator Production Use' but can be anything you want.
  7. The email needs to be sent to 'support@scadalink.com'.
  8. The request will be processed immediately by support staff members.
  9. An authorized license will be emailed back to you. Save it to disk.
  10. Click 'Tools > License > Import'.
  11. Use the file chooser to navigate to the directory where you saved the authorized license.
  12. Select the license file and click 'Open'.
  13. Locator is now registered. You do not have to restart for the registration to take effect.
  14. Use the Help > About menu item to verify the license details. The type of license and license duration will be displayed.

Registration Assistance

Technical Support

Telephone and email support are available at no cost for as long as you own the product and during the evaluation period. The technical support team can be contacted using the following methods.

Software updates can be downloaded and used for no extra cost after your initial purchase.

Starting the Program

There are two methods that can be used to start Locator. The first method is to double click the 'Locator' icon on the desktop. The second method is to use Start Menu > All Programs > ScadaLink Locator > Locator.

Using the Help Menu

The Help menu is at the top of each page.

  • Contents: Displays the Help Viewer. This provides a comprehensive set of documentation that can be browsed or searched. See the Using the Help Viewer topic for details.
  • Support: Displays information about how to get support.
  • Wiki: Your default browser will open the Locator Wiki. This has documentation and videos explaining how to use Locator.
  • About: Displays information about Locator such as the version number, date it was built, the type of license (trial or production), and the duration of the license.

Using the Help Viewer

The help window is used to view help topics that are listed in a table of contents. To open the help window click the 'Help' menu item on the main window and then click 'Contents'. Click a topic in the Contents tab to view it.

A history of browsed topics is retained. The left green arrow is used to go back to a previous topic. The right green arrow is used to go to the next topic.

Using Tool Tips

Tool tips are information text boxes that are displayed when the mouse hovers over some part of the user interface.

Tool tips are available where acronyms are used. For example, on the main window there is a 'DD' label. When the mouse hovers over this label the text 'Decimal Degrees' is displayed. Some tools tips have substantial amounts of text. For example, the label for the entry of LSDs on the main window has a tool tip that describes each field of the LSD in detail. This also occurs on each window where LSDs are entered or viewed.

Tools tips are available for each button on all windows. A description of the action of the button is displayed.

License

A license can be created, exported, and imported.

  • Create: A license is created using Tools >License >Create. Once created, the license needs to be authorized. See the Registering topic for more details.
  • Export: A license can be exported to a file using Tools > License > Export. The license can only be used on the computer it was created. The license needs to be exported prior to upgrading to a newer release. The license should be saved in the event that the hard drive on your computer fails.
  • Import: A license is imported from a file using Tools > License > Import. The license takes effect immediately so Locator does not need to be re-started.

Locations

Tools > Locations is used to import and export locations stored in the database. There are a number of reasons why you might want to do this:

  • Backup your database to ensure no loss of data in the event of a hard drive failure.
  • Upgrade from your current version of Locator to a newer version.
  • Bulk load data from another application into the Locator database.
  • Share data with another user of Locator.
  • Edit data in a specialized application like a spreadsheet or text editor.
  • Generate reports with a specialized report generator.

Prior to importing any locations into the database it is highly recommended that you make a copy of the database using Windows Explorer.  This is a commonly used and well understood method that ensures safety of your data.  You may want to consider doing this periodically.

Database Copy

The database is stored in the 'locator-db' folder.  

To locate this folder right-click the Locator icon on your desktop.  Select the 'Properties' menu item.  Take note of the 'Start In' folder.  

To make a copy of the database use Windows Explorer to navigate to the 'Start In' folder.  Right-click the 'locator-db' folder and select 'Copy'.  Navigate to the file system where you want to store the database backup.  A network drive or USB drive is a safe place to put this.  Right-click and select 'Paste'.   A copy of 'locator-db' will be made.  

The file size is  at least 400 MB so you may want to consider using an archive tool like 7-Zip or WinZip to compress the file.  The 7-Zip Ultra compression mode will compress to less than 20 MB.  7-Zip is a free, open source application.

The file size generated with this method is large because both user data and system data is copied.  The system data has surveyed coordinates for all sections in the four western provinces of Canada.  The method described next only copies the user entered data and this is therefore much smaller in size.

Locations > Export

This will output the locations in CSV format to a file of your choice.   CSV files are text files with comma separated values.  These files can be edited with a text editor like NotePad or NotePad++ or opened with a spreadsheet application like Microsoft Excel or Open Office Calc.   After exporting you should view the CSV file to ensure all your data has been exported.

Locations > Import

Make sure you have made a database copy (see the 'Database Copy' section above) before you do this. This is optinal but will help you easily recover your oiginal data. The imported locations are added to the database. This may result in a duplicate if a location that is imported is already in the database. You can eliminate duplicates after the import is complete by using Find > Delete. You can also remove any possible duplicate in advance using this method. You can also edit the locations file and remove them from the file before importing. 

To import use the file chooser to navigate to the folder containing the files that were previously exported.

See the Locations File topic for a detailed description of the fields in the file.

CSV Format

If you modify or add locations you will need to understand the comma-separated value format.  This is a widely used format.  Each line of text consists of values separated by commas.  There are no spaced before and after each comma.  The first line has a list of field names.  These correspond to database field names.  Each line of text after the first consists of a set of text and numeric values separated by commas and terminated by a newline character.  The rules for these lines are:  

  • If a field has no value then do not put anything between the commas or put two quotes together between the commas.
  • If a field is numeric there is no need for quotes but quotes are permitted.
  • If a field is a text field and has no commas embedded in it then quotes are not needed but are permitted.
  • If a field is a text field and has one or more commas then it must be delimited by quotes.
  • Do not add more fields or remove existing fields.
  • Do not change the order of the fields.
  • The quote character is the double-quote character, “.
  • The grid type, surface grid latitude, and surface grid longitude are mandatory.
  • The '^' is used as a separator in the comments field and the URL field.

The spreadsheet applications, Microsoft Excel and LibreOffice Calc, will input and output data in this format.  If you need to modify locations or add new locations you should consider using one of these applications.  If you use NotePad or NotePad++ then you need to be careful to obey these rules when making changes to the files.

Do not create a file from scratch yourself.  Instead, do an export then modify the file.  This will ensure you have an example of the correct format and that all the field names on the first line are present and in the correct order.  Do not change the names of the files.

The official CSV specification is RFC 4180 and is available on the Internet at http://tools.ietf.org/html/rfc4180.  There is an entry for 'comma-separated values' at http://www.wikipedia.com.

Locations File

A locations file is a CSV file used to import and export locations using Tools > Locations. Each location is represented by one line of text in the file.

An example of a locations CSV file can be created using Tools > Locations Export. It is a good idea to use this as a starting point before you transform your data into Locator format.

This example is from the free trial Locator download.

locations.csv
COMPANY,FIELD,GRID_TYPE,LE,ES,SGRID,SLAT,SLNG,DGRID,DLAT,DLNG,LOC_TYPE,LOC_QUAL,LOC_NAME,COMMENT,ENTRY,ACCESS,ELEV,PRESSURE,ALAT,ALNG,AELEV,GLAT,GLNG,GELEV,USER_ID,URL
"Company A","Alberta","DLS",,,"11-07-013-05W4",50.07152768,110.67858604,"",NaN,NaN,"Gas Well","","Company A -- 11-07-013-05W4 -- Gas Well","This location is near Medicine Hat, AB.^This is a second line of comment.^This is a third line.","North",1,1000.0,90.260,NaN,NaN,NaN,NaN,NaN,NaN,"support@scadalink.com","www.scadalink.com"
"Company B","Manitoba","UWI",,,"101/04-06-011-26W1/4",49.88871566,101.03160624,"",NaN,NaN,"Oil Well","1","Company B -- 101/04-06-011-26W1/4 -- Oil Well 1","This location is near Virden, MB.","East",1,500.0,95.910,NaN,NaN,NaN,NaN,NaN,NaN,"support@scadalink.com","http://www.scadalink.com"
"Company C","Saskatchewan","DLS",,,"08-25-015-14W3",50.28638137,107.79505549,"",NaN,NaN,"Office","","Company C -- 08-25-015-14W3 -- Office","This location is near Swift Current, SK.","South",1,750.0,93.085,NaN,NaN,NaN,NaN,NaN,NaN,"support@scadalink.com","http://www.scadalink.com"
"Company D","British Columbia","BCNTS",,,"A-020-B/093-P-16",55.76041667,120.24062500,"",NaN,NaN,"Compressor","","Company D -- A-020-B/093-P-16 -- Compressor","This location is near Dawson Creek, BC.","West",1,1200.0,88.000,NaN,NaN,NaN,NaN,NaN,NaN,"support@scadalink.com",""

A typical method of creating a locations file is to export it from a spreadsheet. The cells can be filled in the spreadsheet. A locations file can also be constructed using a text editor or by running a script.

The following table shows each field in the order they appear on each line of text in the file. For more information about each field see the Edit tab. Also see the Editing Locations topic.

The 'Unused Setting' is the value you should use if you do not want to enter a value for the field. If a cell in the table is blank then you can enter nothing between the two commas that delimit that field.

GRID_TYPE must be entered. Either SGRID or an (SLAT, SLNG) pair must be entered. If both are entered then SGRID is used to calculate SLAT and SLNG. If GRID_TYPE is set to 'UWI' it is good practice to enter LE and/or ES but this is optional.

Field Identifier Field Name Data Type Unused Setting
COMPANY Company CHAR(40) ”“
FIELD Field CHAR(40) ”“
GRID_TYPE Grid type (DLS, BCNTS, or UWI) CHAR(5) “DLS”
LE Location exception CHAR(3)  
ES Event sequence CHAR(3)  
SGRID Surface grid CHAR(40)  
SLAT Surface latitude (e.g. 51.258913) DOUBLE
SLNG Surface longitude (e.g. 112.56312) DOUBLE
DGRID Downhole grid CHAR(40) ”“
DLAT Downhole latitude DOUBLE NaN
DLNG Downhole longitude DOUBLE NaN
LOC_TYPE Location type CHAR(40) ”“
LOC_QUAL Location type qualifier CHAR(40) ”“
LOC_NAME Location name CHAR(80) ”“
COMMENT Comment VARCHAR(4000) ”“
ENTRY Entry direction (North, East, West South) CHAR(5) ”“
ACCESS Access level (0=private,1= public,2= semi-private) DECIMAL(1) 0
ELEV Elevation (m) DOUBLE NaN
PRESSURE Pressure (kPa) DOUBLE NaN
ALAT Actual latitude DOUBLE NaN
ALNG Actual longitude DOUBLE NaN
AELEV Actual elevation DOUBLE NaN
GLAT GPS latitude DOUBLE NaN
GLNG GPS longitude DOUBLE NaN
GELEV GPS elevation DOUBLE NaN
USER_ID User ID CHAR(80) ”“
URL List of URLs VARCHAR(400) ”“

Preferences

Preferences can be edited, exported, and imported.

  • Edit: Preferences are set using Tools > Preferences > Edit.
  • OK Button: click to save the settings.
  • Set to Default Button: Click to reset the settings to default values.
  • Export: Preferences are exported to a CSV file using Tools > Preferences > Export.
  • Import: Preferences are imported from a CSV file using Tools > Preferences > Import.

The User Identifier property is normally your email address. However your company may choose to use a different naming convention.

The Map File properties are the names of the files where map coordinates are stored whenever you click the map button and indicate GPX, GPI, nRoute, or MobilePC output. Click the file chooser button to navigate to the folder where you want to put your map output data. Typically this folder is where a subsequent map viewer application would read the data. The file chooser uses default filenames but you can modify this if you want. When you click the Save button an empty file with this name will be created. The full pathname is displayed in the text box. As an alternate method of entry you can enter or modify the full pathname directly in the text box.

The Map Symbol property is the symbol name of the icon that is displayed for locations by your map viewer or GPS device. For Garmin devices choose one of the Garmin symbol names. The initial setting provided is for a green dot. If you have a Garmin GPS device or use a Garmin map viewer like nRoute or Mobile PC then you do not need to change this setting. If you use other GPS devices or map viewers then you should use the names published by the vendor. Some vendors do not use the symbol name field at all. Google Earth is an example. Such vendors will ignore the value provided. The drop-down list has a set of commonly used Garmin symbols. If you want to use a symbol not in the list you can enter the name of it. You can also select no symbol from the drop-down list or delete the contents of the text field. A map viewer will then normally use a default symbol.

Status Bar

A message in red is often displayed at the bottom of the main window. This is a status area that has warnings, errors, and informative messages. It is cleared when the mouse is moved.

Alerts

The alerts tab is used to display warnings, errors, and general information. When a message is displayed the tab turns red and the tab is brought to the foreground. To reset to the normal colour you need to click the tab.

There is a popup menu to manage the alerts. Right click in the alerts text area. The popup menu can be used to clear all text, select all text, or copy all selected text to the clipboard. Specific text can be selected using the standard windows method.

Coordinate Conversion

Coordinate conversions are available to convert to and from a number of grids:

  • Dominion Land Survery (DLS). These grid coordinates are commonly known as LSDs.
  • Latitude/Longitude. In decimal degrees, degrees/minutes/seconds, and degrees/minutes.
  • British Columbia National Topographic System (BCNTS).
  • Universal Well Identifier (UWI).

The convert tab is used for these conversions. This has two panels. The input panel is used to enter coordinates. The output panel is used to select the type of output coordinates and display the results of the conversion.

  • Input: The input panel has tabs for each of the coordinate systems. Coordinates can be entered using drop-down lists or text boxes. The text boxes are useful for copy and paste from other applications or from the output text boxes to the input. Each text box has a label below that can be used as an aid to data entry. Hovering the mouse over a label will cause a tool tip to be displayed that has details of the data entry format. If a text box has a value then that value is used rather than the value in the drop-down lists. If you want to use the drop-down list method then first delete all characters from the text box.
  • Output: The output panel has a set of check-boxes to select the type of output coordinates. Some are checked by default. Some are disabled because that type of conversion is not permitted for the input tab selected.
  • Convert Button: To convert the input coordinate to the output click the Convert button. Each time the Convert button is clicked and a conversion occurs the result is displayed in the output panel and also in the Results panel.
  • Clear Button: To clear all fields click the Clear button.
  • Map Button: See the Creating Maps topic for details.
  • Status Bar: See the Status Bar topic for details.

Finding Locations

The Find tab is used to search for locations that match a set of criteria.

  • Input: The input panel is used to enter the search criteria. The wildcard character '*' can be used in any text field (but not the date modified field) to indicate that any string of zero or more characters will match. The string  'a*', will match any string that starts with 'a'. The string '*a*b' will match any string that contains the letter 'a' and ends with the letter 'b'. The string '*b' will match any string that ends with 'b'.
  • Output: The table has the matched locations. The columns in the table are resizable. Table rows can be selected using the standard windows method.
  • Status Bar: The number of locations found is displayed in red in the status area at the bottom of the window.
  • Find Button: When the Find button is clicked the search is started and the results are displayed in the output panel.
  • Clear Button: When the Clear button is clicked the search criteria in the input panel is reset and and the table is removed from the output panel.
  • Delete Button: When the Delete button is clicked the locations selected are deleted from the database.
  • Map Button: See the Creating Maps topic for details.
  • Edit: To read or update a location, select the location in the table, then click the Edit tab. To create a new location based on an existing location, select a location in the table then click the Edit tab. To create a new location not based on any existing location, deselect all locations in the table (or click the Clear button), then click the Edit tab. If you have selected an entry in the table and want to do this then just click the Clear button in the edit panel to start with an empty form. See the Editing Locations topic for details.
  • Convert: To convert coordinates of a location in the table, select the location, click the Convert tab, then click the Convert button. See the Coordinate Conversion topic for details.

Editing Locations

The edit tab is used to create, read, update, and delete locations.

If the edit tab iis clicked after the convert tab has been used to do a conversion then all fields in the edit panel are cleared. The location type and location grid are set to the last conversion used. If there is no last conversion, as happens when Locator is first started, then the edit panel is not modified.

If the edit tab is clicked after the find tab, and an entry in the find panel output table has been selected, then that entry is used to populate all the fields in the edit panel. If more than one entry is selected then the first is used to populate the edit panel. If no entry is selected then the edit panel is not modified.

  • Grid Type: When the Grid Type is selected the Surface Grid and Downhole Grid are converted to that format. If these fields are empty then any values they are set to must be in the format specified by Grid Type.
  • Grid: When the Surface Grid or Downhole Grid fields are set and the cursor moved off that field and clicked elsewhere then the Surface Lat/Lng and Downhole Lat/Lng fields will be computed.
  • Location Name: To set the Location Name click the yellow sweeper. The Location Name is set to the concatenation of the Company, Grid, and Location Type. These are separated by dashes. The Location Name can be edited after the yellow sweeper is clicked. The Location Name can also be set to any value, without using the yellow sweeper,  by editing the text.
  • Elevation and Pressure: When the Elevation field is set and the focus is shifted to another field the Pressure field will be calculated. The Elevation unit is 'm' and Pressure unit is 'kPa'. The Elevation needs to be in the range 0 to 5000 m. The formula used is Pressure = 101.56 - 0.0113 * Elevation.
  • URL: To go to a URL click the green arrow. The default browser is opened with the URL in the text box. A list of URLs can be entered in the text box. Press the return key after entering a URL to enter it into the list. Use the drop-down list to view all the URLs. To delete a URL select it in the drop-down list and click the red scissors. All entries in the list will be saved when the location is stored using the 'Save' button. See the URL Format topic for details.
  • Save Button: When the Save button is clicked the User field is set to the name of the user in the preferences and the location is saved. The last modified date is set in the database record to the current date and time.
  • Clear Button: When the Clear button is clicked all fields are reset. The Grid Type is set to 'DLS'. The Data field is set to 'Public'. The User field is set to the value in the preferences.
  • Delete Button: When the Delete button is clicked the location is removed from the database.
  • Map Button: See the Creating Maps topic for details.

URL Format

The Edit tab has a URL field that can be used to create, read, update, and delete URLs.  A list is retained.  Each entry in the list follows the industry standard URL format.  There are four types:  web link, file name, folder name, and ftp address.

A full web link has the form 'http://www.scadalink.com'.  

This can also be entered as the short form 'www.scadalink.com'.

A full file name has the form 'file:c:/folder/fiilename.ext'.  This can also be entered as the short form 'c:/folder/filename.ext'.   A full folder name has the form 'file:c:/folder'.  This can also be entered as the short form 'c:/folder'  If only a drive letter is used then enter 'c:/' to navigate to the top directory.  If 'c:' is used then a default folder that corresponds to the applcation working directory is used.

A full ftp address has the form 'ftp://address@hostname'.  The 'ftp' prefix must always be used.

The back-slash '\' and forward-slash '/' are equivalent and can be interchanged anywhere within a URL.

Creating Maps

Maps can be created by clicking the Map button on any window. Google Maps, GPX files, and GPI files can be output. To select which of these to output you need to right click the Map button then left click one of the entries. A radio button will show which has been selected. Next time the Map button is left clicked the selection made previously will be used. It is therefore only necessary to left-click tthe Map button to output a map.

Google Maps supports multi-point output. However the number of points is limited to about 20. The exact number depends on the amount of data there is for a location.

GPX files and GPI files can have an unlimited number of points. If a GPX or GPI map is output the status bar will indicate how many points were output.

GPX and GPI are industry standard formats that can be used by many GPS devices and map viewing applications.  GPX and GPI files can be loaded into a Garmin GPS device. GPX files can be used directly by map viewers such as nRoute, Google Earth, and ArcGIS Explorer. There are many other devices and applications that can use this format. GPI format can be used by the Garmin Mobile PC application either on a computer or a Garmin GPS device.

The name of the map output file and the type of map symbol used for locations is specified in Tools > Preferences. See the Preferences topic for details.

Uninstalling

To remove Locator from your system navigate to Start Menu > All Programs > SCADALink Locator. Click Uninstall and follow the instructions.  

desktop.txt · Last modified: 2016/08/27 17:25 by admin