How to... Design and Implement an Interface Dialogue for DMAP
This page sets out some general guidelines and suggestions for software developers who wish to implement an Interface Dialogue for DMAP in their Database or Biological Recording Software
DMAP Files to Export
The primary job of the routines implemented by the DMAP Interface is to export the distribution data and species names to files in the correct format for DMAP. The formats and contents of the Distribution Data (DIS or CSV) and Names Dictionary (NAM) files are fully documented in the DMAP Help system and that information is not repeated here.
File location:
The default installation directory for DMAP is C:\DMAPW, but users can specify an alternative directory when they install DMAP. To assist software developers with finding where DMAP is actually installed on a particular computer, DMAP writes this information in an INI file (16-bit DMAP) or the Registry (32-bit DMAP):
16-bit DMAP
The installation directory is written in the DMAPW.INI file which is located in the Windows directory of that particular computer. The DMAPW.INI file must be regarded as read-only, and the Section and Key to read for the installation directory is as follows:
[settings]
exe_path=C:\DMAPW\
32-bit DMAP
The location of the appropriate Registry Key and value is as follows:
HKEY_CURRENT_USER\Software\DMAPW\Settings\exe_path
To determine whether the 32-bit or the 16-bit version of DMAP is installed, it is suggested that the presence of the appropriate Registry Key is tested first, then if absent, the INI file is read instead.
The installation directory is the location of the DMAP program (DMAPW.EXE), and also the File Group File (DMAPFGP.TXT) which contains information about the File Groups set up in that installation of DMAP. It is also the default location for all DMAP data files (BDY, MPT, PAR, DIS, CSV and NAM) but users can specify alternative locations for these files when setting up their File Groups, so it is a good idea to provide a file browse facility for DIS (and/or CSV) and NAM files in the DMAP Interface Dialogue.
1. The Names Dictionary (NAM) File
The NAM file itself is optional because the species names can be placed in the Distribution Data file, as described in the DMAP Help system. There are, however, some advantages in producing a NAM file, for example, the data will be imported more quickly into DMAP if a NAM file is present. If the NAM file is present, it must contain the following items:
Items which must be present in the Names Dictionary File:
- Species codes {essential}
- Species names {essential}
When generating the NAM file, it is better to write just the codes and names of the species actually exported to the DIS file rather than all possible species.
2. The Distribution Data (DIS or CSV) File
Items which can be present in the Distribution Data File:
- Species codes {essential}
- Species names {optional}
- Co-ordinate data (Grid Reference or Lat/Long) {essential}
- Symbol codes {optional}
- Key text {optional}
Interface developers will need to decide which of these items are to be included in the exported file(s) and whether they are exported in CSV or DIS format. CSV format may be a bit easier to implement, but DIS format will give more flexibility and will be imported much faster by DMAP. Examples of how the DIS file can be generated can be found in the ready-made DMAP interfaces in the downloadable Excel Workbooks and Access Database on the Add-on Utilities page. The VBA code behind these interfaces is accessible and can be copied and modified.
Components of the DMAP Interface Dialogue
The following is a list of components which should be considered for implementing within the DMAP Interface Dialogue. The list is intended to be a series of suggestions and is not intended to be comprehensive nor definitive. The best policy is to implement a range of facilities which gives full access to as many of the features available within DMAP as possible whilst bearing in mind the mapping requirements of the users of the database.
1. Edit Boxes and Browse Buttons for specifying the names and locations of exported files
This should allow users to have full control over the names and locations of the exported Distribution Data and Names Dictionary files so that they can work with files in any of the DMAP File Groups which they have set up. A warning should be given if files are to be overwritten, with the option of cancelling the operation.
2. Dialogue items to allow selection of datasets and symbol assignments
A range of items should be considered here:
- Selection of single species or a selected group of species for export.
- A facility for allowing the export of data for ALL species in the database. This facility is particularly useful because it makes available to users a wide range of opportunities in DMAP.
- Selection of exported data on the basis of thresholds or ranges of dates and/or other important criteria. The export routine(s) associated with this facility will need to be programmed to assign symbols in an appropriate way in the Distribution Data file, and consideration should be given to exporting appropriate Key text describing the symbol assignments.
- If the database contains quantitative data, some means of exporting it in DMAP-compatible format. For example, quantities will need to be scaled by the export routine(s) and assigned to DMAP Quantity Symbols. Consideration should be given to exporting appropriate Key text describing the symbol assignments.
- A facility for users to specify there own symbol assignments to thresholds or ranges of dates and/or other important criteria.
3. A Button to launch DMAP
The routine implemented for this button should firstly call a function or procedure which changes the current path to that of the DMAPW directory and then calls a function or procedure which launches the DMAP program (DMAPW.EXE). The reason for firstly changing the current path is that DMAP looks for some of its data files in the DMAPW directory. The location of the DMAPW directory can be determined in the way described earlier on this page under the heading File location. Some further information about launching DMAP can be found in the topic How to... Start DMAP from a Database or Spreadsheet.
If you have any comments, suggestions or queries about these guidelines, Contact Alan Morton
Home Page