TVStudy FAQ

This FAQ addresses some questions that are frequently asked about how TVStudy interacts with MySQL, handles CDBS data files, or how some of the underlying code functions.  For information on installing the software, see the TVStudy Installation and Upgrade Guide.  For information on using the software, see the TVStudy Manual.

1. What are the system requirements for running TVStudy, or why is TVStudy telling me that I do not have enough memory?
   • TVStudy’s requirements are at least 40GB of storage without any of the optional CDED or NLCD datasets, or closer to 70-80GB with those optional datasets. Additionally, TVStudy will refuse to run with less than 2GB RAM, but it has been observed that TVStudy is much less likely to encounter memory errors at 3GB or more. The FCC only provides downloadable packages for Mac OSX and 64-bit Linux.
2. On my Mac, MySQL does not start automatically on startup. Why is this and how can I correct it?
   • Beginning with Mac OSX 10.10, Apple changed how processes that are supposed to auto-start at boot-up are triggered, and MySQL lagged in being updated to support the change. As such, MySQL would fail to start on boot-up. More recent versions of MySQL appear to have fixed this issue, though the last time someone in the FCC attempted an in-place upgrade of MySQL on a Mac, everything in the database was lost, so be aware that may happen before attempting an upgrade of MySQL.
3. When I attempt to start TVStudy on Linux, I get the message, “Exception in thread "main" java.lang.UnsupportedClassVersionError: gov/fcc/tvstudy/AppManager : Unsupported major.minor version 51.0”. How can I correct this?
   • This message, or one like it, usually means that you have two versions of Java installed, and TVStudy is attempting to launch using the older one. To resolve this issue, remove the older version of Java from your system, using the normal method of removing such software.
4. After upgrading to TVStudy 2.3 and/or MySQL 8.0, I am unable to log into TVStudy with the host set to “localhost” as I have always used. How can I correct this?
   • If you have not upgraded to TVStudy 2.3, previous versions of TVStudy do not support MySQL 8.0, and should be upgraded accordingly.
     If you have upgraded to TVStudy 2.3, MySQL 8.0 has stopped working when “localhost” is used as the host in some cases. In these cases, you should change it instead to “127.0.0.1” which should allow you to log in successfully.
5. When I attempt to log into TVStudy, I get the message, “The database needs to be updated, but studies are currently in use.” How can I correct this?
   • Assuming your database is not currently in use by TVStudy by either yourself or another user, it is possible the database was left in an unclean state with locked studies. To unlock all of your studies and allow the update to proceed, in the Manage Database window, click “Unlock All,” and then “Update.” The update should complete successfully.
     If the problem is not resolved, you may need to drop the database and reinstall, as described in the next question.
6. When I attempt to log into TVStudy, I get the message, “The database is being updated by another application, or is damaged.” How can I correct this?
   • This can happen when a database update fails. If this happens, the simplest method of repair is to drop the database and rebuild from scratch. To do this, in the Manage Database window, click “Uninstall,” and then “Install.” Click “Open” and TVStudy should open successfully.
     
     If, after doing the above steps, the database fails to install correctly, you most likely do not have the file structure correct. Ensure that your data/ directory contains all of the appropriate files and that your file structure matches the ones found on pages 10 or 13, then repeat the steps in the above paragraph. 
     
     The database can also fail to install correctly when TVStudy is running from a location other than the directory which contains the other TVStudy directories such as data/. If so, simply close TVStudy and launch it again from the correct location.
7. When I attempt to log into TVStudy, I get a message about file versions. How can I correct this?
   • To help prevent messages like the one seen in question 5 above, TVStudy now implements a check to make sure that key data files are present and accessible prior to allowing TVStudy to launch, particularly the files found in the data/ directory. Ensure that your data/ directory contains all of the appropriate files and that your file structure matches the ones found on pages 10 or 13, then repeat the steps in the above paragraph. 
     
     This can also occur if TVStudy is running from a location other than the directory which contains the other TVStudy directories such as data/. If so, simply close TVStudy and launch it again from the correct location.
8. When I first start TVStudy, I get the message, “The study engine executable file is not properly installed. Editing may occur however no study runs will be performed.” Or, when I attempt to start a study, nothing happens and/or TVStudy says “Waiting for start…” How can I correct this?
   • This error means that the Java UI cannot find the TVStudy engine, or that the engine has failed to run. To test this, you will need to open your command line, navigate to the lib/ directory within your TVStudy installation, and attempt to run the engine directly with this command: "./tvstudy" (Don't type the quotation marks.)  
     • If you are running a newer version of Mac OS X, you may be prompted to approve the TVStudy executable to run. Once you do, that may be all you need to do to allow it to run successfully. You may need to repeat this process for pair_study_post if you are attempting to run a Pair Study.
     • If you receive an error about permissions, check that the permissions allow the file to be executed.
     • If you receive an error about the glibc version, you may need to recompile the software for your system.
     • If you are on Linux and receive an error message about libmysqlclient.so.21, you are missing the libmysqlclient21 package, which should be available for installation on most Linux distributions.
     • If you get text describing how to run the engine, then the Java UI cannot find the TVStudy engine. To correct this, be sure you are launching TVStudy via the tvstudy.jar file from within the root of the TVStudy installation directory.
9. On a particularly long study, I receive an error “MySQL server has gone away” and my study fails to complete. How can I correct this?
   • The MySQL server has a built-in time-out which logs the user out if no activity takes place after a certain period of time. This is kept in the my.cnf or similarly named file. To correct this issue, you will need to open the appropriate file and increase the “wait_timeout” variable, and then restart the MySQL server.
10. After upgrading my database in the latest version of TVStudy, I am now receiving an error message which includes the text, “Data truncation: Incorrect datetime value: '0000-00-00 00:00:00' for column 'db_date' at row 1”. How can I correct this?
    • While we have yet to track down the exact cause of this error, the solution is to Uninstall and then Install the database from the Manage Database window. Full documentation on accessing and using this window can be found on page 7 of the TVStudy 2.1 Manual.
11. I attempted to import the November 2015 CDBS extract provided by the FCC and got an error message that the app_tracking.dat and/or am_ant_sys.dat file(s) is/are missing. How can I correct this?
    • Versions of TVStudy older than 2.x did not require either of these files in order to import CDBS datasets. However, special versions of these files are not required. Simply download the currently-available copies of these two files, place them in the same directory as the FCC-provided CDBS extract, and TVStudy should then import the dataset successfully.
12. I attempted to import a CDBS dataset into TVStudy and got an error message about the application table or application.dat file. How can I correct this?
    • On December 2, 2014, the structure of the application.dat file in CDBS was modified. TVStudy was adjusted to support datasets newer than that date, but as a result no longer supports older datasets. In order to import older datasets, you will need to run the fix_application utility contained within the lib/ directory on the application.dat file in question. TVStudy should then import the dataset successfully.
13. When I attempt to set up a TV Interference Check study, no templates are available except for the default template, even though I have a drop-down menu offering to allow me to change templates. How do I use templates in TV Interference Check studies?
    • TVStudy 2.x has three levels of locking: Unlocked, “Lock template only”, and “Lock template and study settings”. In order to use a template for a TV Interference Check study, you must lock your template at the “Lock template only” level of locking. This is described in depth on pages 23-24 of the TVStudy 2.1 Manual.
14. When attempting to add stations to a scenario or run a pair study, I receive an error that TVStudy is “out of keys.” What does this mean, and how can I correct this?
    • A given study in TVStudy only supports up to 65,535 unique stations—across all scenarios. This means that if you only have one scenario, it will only support up to 65,535 entries; if you have two scenarios, you can have 65,535 in both as long as they are the same 65,535 entries. In addition, each time a station is replicated to a new channel, this also uses up a key. Even after you delete said entries or conclude your pair study, these entries remain cached in TVStudy. To remove them and gain back keys, simply select “Delete Unused Records” from the “Scenario” dropdown menu in your study.
15. After installing TVStudy 2.1 or newer, all of the results of my studies have 0 population in their results, even though I checked and the Census data is enabled in the study parameters. Why is this, and how can I correct it?
    • If you failed to properly replace the contents of the data/ directory with the contents of the 2017Feb_tvstudy_data_updates.tgz file, it is possible that the Census data was not imported successfully into TVStudy. To correct this, ensure the contents of the file are properly placed within the data/ directory, then Uninstall and Install the database from the Manage Database window. Full documentation on accessing and using this window can be found on page 7 of the TVStudy 2.1 Manual.
16. After running a number of studies on the Mac, I eventually am unable to run additional studies with the error: “Database connection failed: Lost connection to MySQL server at ‘sending authentication information’, system error: 32”. What does this mean, and how do I correct it?
    • This is a bug in MySQL and/or Mac OS which results from having opened too many files at once. The short-term solution is to restart the MySQL server; the longer-term solution is to adjust either the configuration of MySQL or the Mac OS file limit as described in this link: http://stackoverflow.com/questions/17813630/mysql-5-6-headaches-on-mac-osx
17. After generating the global grid, it appears to be shifted in longitude every several rows as you go up in latitude. Is this expected behavior?
    • TVStudy's algorithm to generate the global grid will attempt to keep the total area of each grid cell consistent as the grid shifts away from the equator in latitude. The origin of the global grid is at 0 latitude, 0 longitude. The cell latitude dimension is fixed; that is computed from the cell size parameter. The cell longitude dimension, however, can vary with latitude. The longitude dimension is fixed across pre-determined bands of latitude. The target in the algorithm is for the area of the cells to change by 2% from the south edge of a band to the north edge. The source code file "cell.c" has a complete description of the global grid algorithm; this file can be found under the dev/src directory.
18. I am attempting to run the Terrain Database Test and Verification Utility, but it is failing with the following error: Traceback (most recent call last):
    • 
      File "checkTerrain.py", line 48, in <module>
      if fcount('nlcd2011') > 3:
      File "checkTerrain.py", line 20, in fcount
      for f in os.listdir(path):
      OSError: [Errno 2] No such file or directory: ‘nlcd2011'
      Why is this, and how can I correct it?
      
      This error came about due to the addition of the optional 2011 NLCD data to the utility. In adding it, a bug was introduced because the code was failing to check for the existence of the nlcd2011/ directory prior to attempting to read from it, so the error indicates that the directory does not exist. A new version of the utility has now been uploaded to the TVStudy website which corrects this bug. Simply download it and replace the existing files and the utility should run successfully.

If you have a suggestion for a question to place in this FAQ, please email your idea to Mark Colombo at the FCC.