ISSEL GeoDetail User Guide
Updated 2004-11-24
This document describes how to use the GeoDetail software.
Table of contents:
Issel GeoDetail adds GeoLocation data to Pilot HitList databases from WhoIS based sources. The data is entered into existing tables in the HitList database and can therefore easily be used with existing reports.
First a HitList database has to be selected, either an Access 2000 database (.MWD extension) or a SQL Server database (through and ODBC connection). When a database is selected GeoDetail checks if the Geo fields are available. If not the user has the option to add them immediately. When the fields are added a HitList table containing IP-addresses is altered to accommodate Geo Location data but no data is actually added at this time. The alteration of the HitList table does not affect normal HitList operations in any way.
To actually add the GeoLocation data an Update is performed. The Update first checks that the Geo fields are available (offering to add them if they are not) and then starts processing the IP-addresses in the database. A status bar then shows how many IP-addresses there are to process and the progress of the processing. Once processing is completed the status bar disappears and the status massage shows Ready.
After processing the GeoLocation data is available for use in HitList reports. The Update process should be executed after every time the HitList database has been loaded with more log files.
Either Access 2000 or SQL Server HitList databases can be selected by first selecting the Database Type and then clicking the Select button.
If an Access database type was chosen a File Open dialogue will be shown filtered for HitList Access databases by default (.MWD file extensions).
If the SQL Server database type is chosen clicking on the Select button will open an ODBC logon dialogue. The dialogue contains a DSN pop-up menu which includes the available DSN connections. These ODBC connections must be created in advance using the ODBC Control Panel in Windows to be visible in the DSN menu. Please note that all DSN's are visible in the pop-up menu, not just connections to HitList databases.
To complete the connection to the SQL Server HitList database you have to fill in a valid user ID and Password which are both mandatory. The database field is not required, it depends on how the ODBC connection has been setup i.e. if the DSN includes a default database or not.
Trying to access a non-HitList database will generate an error message.
The last selected databases of each type are stored in GeoDetail and are available by selecting the database type. The database selected is the one that gets processed when an Update is activated.
To manage multiple databases of different types save the database settings as DSN connection files using the File menu. A database connection can then be established by opening a previously saved connection file instead of having to reselect it from scratch.
Database connection files can also be used for scheduling database updates.
Updates are performed against the selected database when the Update button is pressed. Updates can also be performed from the command line.
The Update process first checks that a valid HitList database has been selected. If the Geo fields are not already available it offers to add them. No update can be performed without the Geo fields in the database. Then GeoDetail asks if you want to go ahead with processing the IP-addresses in the database. If you answer Yes then it will first find out how many IP-addresses there are in the database which has not already been updated and then show the values together with the Status bar which indicates the progress of the processing.
At this time the Update button name also changes from Update to Cancel. From this moment the update process can be stopped at any time by pressing the Cancel button which stops the processing and changes the button name back to Update. Any IP's already processed are immediately committed to the database. Note that there may be a slight delay before GeoDetail reacts to the pressing of the Cancel button as it is sampled for approximately every 100 IP's processed. This may take a little while, particularly if the HitList database contains site names rather then raw IP-addresses.
The preferences can be opened from the Geo menu.
Suppress questions:
Checking this option stops GeoDetail from asking confirmation questions for
every operation. It will simply assume that you answered Yes to everything because
you know what you are doing. Don't use this option unless You Know What You
Are Doing!
Storage options:
This field contains a list of all the fields available in GeoDetail and allows
you to select which ones you want your particular HitList databases to be updated
with. Note that selecting more fields then you actually use for analysis will
make your database unnecessary large and may slow it down. Please note that
every IP-address does not have all the fields. However, all IP-addresses should
have:
Normally we would recommend that Country, Region, City, ISP and Organisation are selected. The rest of the fields should probably only be added for very specific demographic analysis.
Advanced options:
These options concerns the performance of GeoDetail and the database it is connected
to.
Check "Update last IP first" if you want GeoDetail to start updating the most recently seen IP-addresses first. This can be useful if you have a very big database (for example more then a million IP-addresses) and don't want to process all the IP's at the same time the first time you use GeoDetail. By canceling the update process after it has executed for a little while, all your reports covering the most recent time period should have Geo data available for most visitors where as reports covering time periods further back may not. This option forces the database to sort the IP-addresses which may slow it down so if you plan to always update all un-processed IP's then you can uncheck it to speed up performance a little bit.
The "ODBC time out" field allows you to set the time before the SQL server database commands which GeoDetail generates time out. This can be useful if you have a Very Big Database (millions of IP-addresses) and/or a slow database server. If that is the case GeoDetail may show error messages about ODBC time outs. By increasing this value to for example 60 seconds or 100 seconds or even further, that problem should disappear. Note that you should not set it too high since its main purpose is to detect errors or lockups and a very high value means it will take a long time to detect such problems while the system may seem very unresponsive.
There are two ways to remove Geo data from the HitList databases. None of these functions remove any of the standard HitList data, only the Geo data added by GeoDetail.
The "Delete data..." function in the Geo menu removes the Geo data (only) for all IP-addresses which visited the site in a certain time period. This is useful if you want to re-process the Geo data for a certain time periods for some reason, for example the installation of updated Geo databases (which are updated every month).
When the "Delete data..." function is selected a dialogue is opened where the date range can be selected. Note that only fields where dates are actually entered are used to determine which data to delete. For example, if only a "From" date is entered all the data FROM that date (including that date) will be deleted. If only a "To" date is entered all the data UP TO that date (including that date) will be deleted. If both fields are entered then the Geo data for IP's visiting the site between those dates (including the dates themselves) will be deleted.
The dates must be entered in the yyyy-mm-dd format, for example 2003-11-20, meaning the 20th of November 2003.
When the OK button is pressed a confirmation box will appear allowing you to double check that you entered the correct dates. Please note that the delete operation cannot be un-done.
The "Drop Geo..." function in the Geo menu removes ALL the Geo data AND the Geo fields and indexes from the HitList database, leaving a standard HitList database. Use with caution as there is no undo.
GeoDetail can be executed from the Windows command line with two different flags, '-s' and '-f'.
Calling GeoDetail with the '-s' flag runs it in "Silent" mode. GeoDetail starts up without displaying the user interface and executes an Update using the database which was last selected from the user interface. Once the update is completed the application is closed. For example:
C:\Program Files\GeoDetail> GeoDetail.exe -s
Calling GeoDetail with the '-f' flag runs it in "Silent" using a database from a specified connection file. The connection must have been saved previously. This way many different databases can be updated from the command line, for example:
C:\Program Files\GeoDetail> GeoDetail.exe -f=my_Geo_SQL_conn.txt
The command line functions are particularly useful for scheduling updates of the database so that they happened automatically but some care has to be taken:
Windows NT:
On Windows NT the AT command is used to schedule GeoDetail, for example:
C:\> at 04:00 /every:M,T,W,Th,F,S,Su C:\Progra~1\GeoDet~1\GeoDetail.exe -f=C:\Progra~1\GeoDet~1\my_Geo_SQL_conn.txt
This example assumes that GeoDetail was installed on the C-drive and that the connection file was saved in the GeoDetail application directory.
Windows 2000:
On Windows 2000 it is easiest to use the "Add scheduled task" wizard
in the Control Panels. Simply select the GeoDetail application and a suitable
time for it to run. Once the wizard has completed you can select the task from
the Control Panels menu and edit its properties. Add the '-f' parameter exactly
as described above after the field which calls the application, for example:
C:\Progra~1\GeoDet~1\GeoDetail.exe -f=C:\Progra~1\GeoDet~1\my_Geo_SQL_conn.txt
To purchase ISSEL GeoDetail contact ISSEL at sales@issel.co.uk sending the GeoDetail ID which can be found in "Register..." under the Help Menu. On receipt of your payment you will be sent a License Key. This key can be entered into Issel GeoDetail by clicking the Enter button directly below where the ID is found. On entering a correct license key a confirmation message will appear and the text at the top of the screen will now show that it is a licensed version.
The underlying Geo Data technology for Issel GeoDetail is supplied by MaxMind.
Copyright (C) 2002 MaxMind LLC
Pilot HitList is owned by Pilot Software.
Copyright (C) 2003 Pilot Software