APPENDIX 11: GUIDELINES FOR APPLICATION DESIGN

This appendix contains guidelines for application designers, listed in no particular order. These guidelines are intended only to be a limited selection of helpful suggestions, not a comprehensive set of instructions for application design. Terms highlighted in bold typeface have entries in the Glossary.

1. DESIGN PROCEDURES TO REVIEW AND (WHEN APPROPRIATE) TO REPORT REJECTS TO GSS: As an integral part of the application, set up procedures to examine geographic data that have been rejected by Geosupport, and to report appropriate rejects to GSS. Only those rejected data that, after examination, do not appear attributable to user errors should be reported to GSS. In addition, users should also report cases in which the input information was not rejected, but the output data that Geosupport has returned to the application appear to be erroneous for the given location (such as an incorrect ZIP code or incorrect cross streets). User feedback is essential to GSS’s efforts to keep Geosupport accurate and up to date.
   
   

2. USE THE GEOSUPPORT COPY LIBRARIES: : If the application is being written in a programming language supported by Geosupport’s COPY facility (currently, COBOL, PL/1, IBM Mainframe Assembler Language, C or NATURAL), do not code layouts of the Geosupport work areas directly into the application program source code. Instead, write the program to access the Geosupport COPY facility. This will cause the program to automatically obtain the most current standard source code work area layouts at compile time. This approach eliminates tedious and error-prone line-by-line coding of the Geosupport work area layouts by the application programmer, insures the use of the most current layouts, and facilitates trouble-shooting by insuring the use of standard data names for Geosupport data items.
   

3. DESIGN FOR GEOGRAPHIC RETRIEVAL CONSISTENCY: If an application is required to retrieve data from the application’s own files by geographic location, it should be designed so that it performs such retrieval consistently, that is, independently of variations in specifying geographic locations. This is accomplished by obtaining certain items from Geosupport, storing them in the application file, and using them as part of the retrieval key. For example, for retrievals by address, use B5SCs instead of street names in the retrieval key. For building-level retrievals, store BINs in the application file and use them rather than addresses or tax lot identifiers as the retrieval key.
   

4. DESIGN BATCH PROCEDURES TO RE-SYNCHRONIZE APPLICATION FILES WITH NEW GEOSUPPORT RELEASES: Geographic information changes over time. For example, changes are possible in the election districts, tax lot identifiers or police precincts associated with addresses, in the street codes assigned to street names, in the streets incident upon intersections, etc. During application design, consider which data items obtained from Geosupport and stored in application files should be updated to reflect changes in new Geosupport releases, and design procedures to perform such updating. In particular, if street codes are to be stored in an application file, store them in the form of B10SCs (but use only the B5SC portions for geographic retrieval), and develop a fully automated batch resynchronization procedure utilizing the Street Code Change File (see Chapter IV.4).
   

5. (1) USE THE APPROPRIATE STREET NAME FOR THE TASK: To sort a file by geographic location, always use street names normalized in sort format (see Chapter III.3). For display purposes, obtain preferred street names (see Chapter IV.6), and display them normalized in compact format (see Chapter III.3).
   

6. WHENEVER POSSIBLE, ALLOCATE 32 BYTES FOR STREET NAME FIELDS; DO NOT SPECIFY AN SNL VALUE UNLESS THE APPLICATION SPECIFICALLY REQUIRES SHORTER STREET NAME FIELDS (for example, to fit within a limited amount of space in a report, screen or transparent envelope window). The default SNL value, 32, insures that all valid input street names can be successfully normalized.
   

7. TO VALIDATE ADDRESSES, USE FUNCTION 1A RATHER THAN FUNCTION 1 OR 1E. Function 1A does a far better job of validating whether a building having a given address actually exists.
   

8. TO IMPROVE EXECUTION EFFICIENCY, use Function 1 instead of Function1E unless the application requires the political district geography that only Function 1E provides. (Function 1 performs fewer I/O operations.)
   

9. NEVER DESIGN NEW APPLICATIONS TO USE VESTIGIAL FEATURES OF GEOSUPPORT (see Chapter I.5).
   

10. ESCHEW FREE-FORM ADDRESS PROCESSING (see Chapter V.3) UNLESS IT IS UNAVOIDABLE. Whenever possible, pass the house number and the street name of an address to Geosupport in the separate WA1 input fields for those items. Design application files so that the house number and street name of an address are stored in separate fields.
    

11. REVIEW THE SET OF WARNING AND REJECT CONDITIONS THAT CAN BE ISSUED BY EACH FUNCTION THE APPLICATION WILL BE CALLING. Determine whether any of these conditions warrant custom handling in your application. Appendices 1 and 4 of this document are useful in this regard.
    

12. DESIGN INTERACTIVE APPLICATIONS TO USE THE SIMILAR NAMES FEATURE. (See Chapter III.5.) Whenever Geosupport rejects an input street name and returns similar names, display the list of similar names on the screen and allow (but do not require) the operator to select one of them using the cursor. If the operator selects a similar name, re-submit the Geosupport call automatically using the similar name in place of the rejected input name.