Online Information
Frequently Asked Questions for DEVELOPERS of the MassGIS Data Viewer
Q: What are the individual files of the Viewer for?A: A typical Viewer is a set of files. Here is what the set would look like for the latest version of the Viewer available on CD or from the MassGIS web site:
sav30mg2.apr - the "starter" project. This project sets the environment variables and then opens the main project (av30mg2.apr). This project is only relevant on Windows operating systems.
av30mg2.apr - the main ArcView project. On Windows systems, this usually is not to be opened directly, because the environment variables will not have been set. This IS the project to open if you are using a UNIX system (because the environment variables are already set up in the user's .profile)
full.odb - the file that holds the Viewer's GUI information. This file is created from the CreateGUIs script.
themeinv.dbf - the "theme inventory" file - a database file that holds information on themes and their characteristics such as legend, scale dependency, etc. This table populates the "A" button menu choices.
zoominv.dbf - the "zoom inventory" file - a database file that holds information about extents. This table populates the "Z" button menu choices.
inquiry.dbf - a database table that lists attributes of the themes in the themeinv.dbf. This table can indicate which attirubtes are to be hidden, and which are label items.
environ.txt - a file needed for Windows operating systems which sets the environment variables to data and legend files.
errata.txt - a file that holds information about known problems and bugs in the Viewer release.
whatsnew.txt - a file that describes what is new in the Viewer since the last release.
Q: Give me a brief overview of how the Viewer can be customized.
A: There are ways to customize the Viewer that only require editing tables, and do not require editing scripts. For example, if the developer would like an initial extent of the Charles River watershed instead of the entire state outline, the zoominv.dbf table should be edited. The Active column value indicates which record is the initial extent. Place a "D" in this column for the record that you wish to be the initial extent.
You should have only one initial extent. The same concept exists for initial themes. You can have one or more initial themes. These themes are marked in the themeinv.dbf table with a "0" (zero) in the Active column. Once any of the themeinv.dbf, zoominv.dbf, or inquiry.dbf tables are edited, you need to "Reset the Project" under the "View" menu. This reads the information from those tables into dictionaries. Once the project has been reset, you will see the results of your table edits in the "A" and "Z" buttons.
The Viewer can also be modified by editing the existing scripts or adding new scripts. The documentation file "developr.doc/developr.txt" (Microsoft Word or ASCII versions) contains useful information on the format of the themeinv.dbf, zoominv.dbf, and inquiry.dbf tables, and other tips for modifying the Viewer. This file is located at the MassGIS web site and is distributed with the Viewer in the docs directory. There are a lot of ESRI sample scripts contained in the online help that do useful things. There are also many ESRI extensions supplied with ArcView 3..1.1+ which can be customized by altering scripts. Also heck out the online help for an overview of programming in Avenue.
Q: What is the best way to add customizations to the Viewer?
A: The Customize box is an easy way to add customizations, but it is not the best way. The GUI for the Viewer is stored in the full.odb file. When ArcVIew starts up, it sets up its' native GUI, then the Viewer GUI gets laid on top of this version. The Customize dialog box creates a default.apr file which gets consulted in making a GUI. The default.apr file can cause problems. If you have used the Customize box to change the Viewer GUI (i.e. add a button or menu choice), the next time you "Reset the Project" under the "View" menu, your change will be lost. Resetting the project does not take the default.apr file into account. A user would want to reset the project if they edited either the theme inventory(themeinv.dbf), zoom inventory (zoominv.dbf), or inquiry files, in order to make the edits take effect. Also, when the next version of ArcView is released, it will use your default.apr <instead> of the native default.apr. So, your interface will have your customizations but you won't have the new ArcView functionality.
What is the best thing to do regarding customizations. As things currently stand, your best bet would be to put your changes into the CreateGUIs script and run this script to create a new full.odb. Putting your changes into the CreateGUIs script also documents all the changes that you made to the project in terms of adding buttons, tools, and menu choices. As soon as you run the CreateGUIs script your changes become effective - you do not need to "Reset the Project" (although you should save before exiting).
Contact me if you need help figuring out how to put your customizations into the CreateGUIs script and I'll be glad to help get your new features in the right place.
Another tip is to try to use environment variables in your scripts. If you write a script and hard code the path to your coverage or table, you may have to change that path in the future - as many times as it appears in the script(s). If you use an environment variable, all you have to do is update the environment variable once - either in the environ.txt (Windows) or the .profile (UNIX), and once in the themeinv.dbf file. For example,
If I want to refer to a coverage in a script that is located in /afreeman/data/mycoverage, instead of using this exact path, I could define an environment variable $MYDATA = /afreeman/data. I'd refer to the coverage as $MYDATA/mycoverage. Then, if I moved the data to /anotheruser/data/mycoverage, I'd just have to change the environment variable $MYDATA from /afreeman/data to /anotheruser/data. Using environment variables helps transfers of your projects and scripts from one machine to another, within your organization, or if you share your script with others outside your organization. You should try to keep your environment variables simple. Do not use strange characters if you want them to work on multiple computer platforms. Digital UNIX, for example, will not allow dashes.
Q: So, you've added a new button to the Viewer. The button runs your script called DoStuff. Now MassGIS comes out with a new version of the Viewer. You need to re-add your button to the new version of the Viewer.
A: The first thing to do is open up your old version of the Viewer and write out your modified scripts to text files onto the hard drive. In this case, you would want to write out the DoStuff script (new) and the CreateGUIs script (modified). Now, open the new version of the Viewer. Create a new script document and load from a text file your DoStuff script. Now you've got your new script into the new Viewer. Now, you need to re-customize the CreateGUIs script to have your changes. Open a new script document and load <your> modified CreateGUIs from the old Viewer. Compare the new CreateGUIs script and the old, modified CreateGUIs script. In most cases you will simply need to cut and paste your modified code out of the old version and insert it into the new version in the same place. You can delete the old version when you are finished. Now run the modified new version of CreateGUIs to create a new full.odb file.
Suppose you had modified several other Viewer scripts. You wrote these out to text files from the old Viewer. Then you start up the new Viewer. You must remember not to simply replace the new Viewer scripts with your modified versions because those scripts may have been updated since the last version and you would be losing information. To find out if a script has been updated, look at the documentation at the top of the script, or consult the MassGIS Data Viewer Script Calls Diagram and check the color code for that script. If the script has not been modified since the last version you <may> just replace it with your modified version. If the script has been modified, you'll have to insert your changes into the new script.
Q: When I edit a table, I can't seem to get the last change I make in a cell to "take". Why?
A: ArcView seems to require that you move the cursor out of any cell that has been edited, or else it won't save the change you made in that cell.
Q: When I use the a UNIX machine and make a change to a .dbf table and save it it doesn't get written to the disk (and the changes don't appear after I "Reset the Project"). Why?
A: The .dbf table is not always written to disk on the Alpha. If you suspect this is the case, you can force the table to be written to disk by choosing "File/Export". I would recommend writing the table out to a new name. For example, File/Export the zoominv.dbf table the test.dbf. Then delete the old zoominv.dbf and rename test.dbf to zoominv.dbf. If you File/Export a table to the same name the table can get corrupted.
Q: My user worked on the Viewer project for a while and then saved it as myproj.apr. The next session of ArcView, the user opened myproj.apr directly, but the project did not open correctly. Why is this?
A: The problem is that the starter project was not run, and therefore the environment variables were not set.
One way to get around this problem is to always open the sav30mg2.apr file, close the main Viewer project, and then open myproj.apr. Since the environment variables are set for your entire ArcView session, you can close the main Viewer project and open another project and still have the correct environment variables.
Another customization option is as follows: The sav30mg2.apr file does 2 things: Set the environment variables and open the main project (av30mg2.apr). The sav30mg2.apr file can be edited to NOT open the main project. In this case it will set the environment variables and wait for the user to open any project using the File/Open menu choice. To edit the sav30mg2.apr project, hold down the Control key while the project is opening. You want to edit the SetEnvVar script. Comment out the line near the bottom of the script:
Project.Open("av30mg2.apr".AsFileName) with a single quotation mark in front of the line. Compile the script by clicking on the running man button. Now save the project. You can name this project anything you like, perhaps setenvvar.apr is more meaningful. Instruct your users to open this project first every time, and then open their own projects.
Q: What documentation exists about the MassGIS Data Viewer?
A: There are many pieces of documentation - here are a few:
What: install (.doc or .pdf) - information on installing the Viewer and MassGIS data.
Where:What: ex1pic (through ex5pic) (.doc or .pdf) - an introduction to ArcView and the ViewerOn CDs under /31/data/docs and /data/docs MassGIS Web Site: http://www.mass.gov/mgis/install.pdf
Where:What: developr (.doc or .pdf) - explanation of Viewer's .dbf tables and how to extend the ViewerOn CDs under /31/data/docs and /data/docs MassGIS Web Site: http://www.mass.gov/mgis/gisedu2.htm
Where:On CDs under /31/data/docs and /data/docs MassGIS Web Site: http://www.mass.gov/mgis/devlp30.htm
Back to Online Information Index | Data Viewer Main Page | ArcView 3.x Versions Main Page
Last Updated 1/17/2003
EOEA Disclaimer | Privacy Policy