Overview

The Status to Case Rec Conversion Tool is a small program that takes legal descriptions from the LR2000 Status database and converts them to an acceptable format for upload into the LR2000 Case Rec database. The tool has not been packaged into an executable or installer due to restrictions on such software on the BLM network, therefore some additional software is required to run the tool.

Required Files and Software

Useful Resources

  • Python - https://docs.python.org/2/
  • SQLite3 - https://docs.python.org/2/library/sqlite3.html
  • SQLite - https://www.sqlite.org/docs.html
  • Tkinter - https://docs.python.org/2/library/tkinter.html
  • PEP 8 - https://www.python.org/dev/peps/pep-0008/
  • Python File Structure

    The python file is split into three distinct parts, the first being the header section containing file encoding data, file description, and module imports. Next, in the second section we have the database handler code that does most of the actual work and interacts with the convert.sqlite database file. This section is entirely contained in the ConvertDB class. The last section of the code includes a few simple classes that define the default behavior of certain GUI elements and the main GUI handler class ConvertGUI which handles all interaction with the user. We'll refer to these last two sections as the back-end and front-end respectively.

    Back-End

    In this section we'll discuss the responsibilities of the back-end and give a few examples of ways to change or add functionality to the conversion process.
    The responsibilities of this section are as follows:
    For specific information on which functions handle which requests as well as detailed explanations of code blocks, see the source code. However, we will go over a few of the more important changes you may want/need to make with the tool here.

    Adding or Updating Conversion Rules

    This work is done completely within the getexportdata function within the ConvertDB class. This function takes a serial number as its only parameter (besides the implicitly passed self parameter). Given this serial number, the function queries the database and pulls all legal descriptions for that serial number from the database. Then we run each legal description through a set of rules to convert it to Case Rec format. These rules are all applied within the main for loop, to add a rule simply add a new block of code in this section that runs the rule on whichever survey types necessary. Each rule is identified and described using a short block comment directly above the block of code that implements the rule. You should add this block whenever you add a new rule. To update a rule, find the rule that applies to the survey type you wish to update, then carefully read the block to understand what the rule is doing. Once you understand how the rule works, simply make the necessary changes or additions to the block.

    Front-End

    The responsibilities of this section are as follows:
    Again, much of this functionality is well documented in the source code for you to inspect and update. We'll talk about some of the more important changes or updates you may want/need to make to the user interface here.

    Adding or Updating Elements on the GUI

    The GUI is built using a simple (somewhat limited) default Python module called Tkinter. See the documentation linked in the Useful Resources section of this document for more information on how to properly use the module. The basic process for adding a GUI element is as follows:
    1. Choose the widget you wish to add.
    2. Optional: If you plan to use this widget multiple times with specific default settings, you may want to create a subclass of the widget and set the defaults there (See ConLabel, ConButton, ConEntry classes).
    3. Create and place the widgets within the initgui function of the ConvertGUI class. If necessary connect these widgets to a function here as well.
    4. If the functionality you wish to add requires interfacing with the database, create a function within the ConvertDB class that does the database work and returns the necessary data to your function located in the ConvertGUI class. The function within the ConvertGUI class should not be accessing the database.

    SQLite3 Database Structure

    The database has a very simple structure. The only table we use in the database is called Status. This table contains the legal descriptions that are initially uploaded from the Status LR2000 export file. We simply use this database to pull legal descriptions from during the conversion process. The table definition can be found below.
    Status Table Definition
    Name SQLite3 Type Description
    LegalID TEXT Auto-generated unique identifier. 
    AdminSt TEXT 2-character Admin State
    GeoSt TEXT 2-character Geo State
    SerialNum TEXT Full Serial Number
    MeridianCd TEXT 2-digit Meridian Code
    Township TEXT 5-character Township (ex. 0010S)
    Range TEXT 5-character Range (ex. 0150E)
    Section TEXT 3-digit Section
    SurType TEXT Survey Type
    SurNum TEXT Survey Number
    SurSuff TEXT Survey Suffix
    Aliquot TEXT Aliquot Description

    Troubleshooting

    During regular use of the tool users may run into errors or crashes (outside of the errors displayed in the export text file). When these errors occur, it is very likely that an error message will be printed out to the console. Make it clear to the users that if they want to report an issue they will need to include this error message as it is very useful in determining where in the code something went wrong. It is also very useful to have both a production and development version of the tool, that way you can test solutions to bugs in a development environment before releasing updates to the user.