I.1 Introduction

The Geosupport System is an integrated system of software and data files that processes New York City geographic locations. Input locations can be accepted in various forms, including addresses, place names, street intersections, blockfaces, street stretches and property parcels (tax lots). Geosupport standardizes and validates the input location and provides related geographic information, such as the community district, census tract and census block, ZIP code, tax block and tax lot, police precinct, cross streets, City Council district and spatial coordinates. In addition, Geosupport provides user-written applications with the means to retrieve data from the user’s own files by geographic location in a consistent manner.

The Geosupport System was developed and is maintained as a service to all agencies of the City of New York by the staff of the Geographic Systems Section (GSS) of the Department of City Planning’s Information Technology Division. GSS has been enhancing the Geosupport software and updating the system’s data files continually since the system’s introduction in 1983.

This document, the Geosupport System User Programming Guide, is a comprehensive technical description of the system and how to access it. The document is intended to be read primarily by technical users such as computer application designers, software analysts and programmers. (Knowledge of IBM mainframe application programming is assumed.) Note that as of Version 19.3 Geosupport enhancements are being implemented and supported only in non-mainframe environments, e.g. Desktop Edition, GeoX, .net, and Linux.

Geosupport is installed on IBM mainframes at the city computer centers listed in Appendix 7, where it is used by most city agencies as an integral component of many of their major data processing applications. An employee of each computer center’s custodial agency, generally a systems programmer, has been designated as the Geosupport System Administrator (GSA) for that computer center. The GSA is responsible for installing or coordinating the installation of new Geosupport file releases and software versions received from GSS. At some computer centers, the GSA makes certain customizing modifications to Geosupport during installation, such as changing the data set names (DSNs) of Geosupport files to conform to local file naming conventions. The GSA is also the first responder for users encountering system-related Geosupport problems, and interacts with GSS staff as needed to resolve such problems. However, the GSA is not necessarily familiar with Geosupport from a user application perspective, and is not responsible for assisting users with application-related problems or design issues.

In general, Geosupport is accessible without restriction to anyone having a valid account at any of the computer centers where it is installed; no special passwords or security procedures are required beyond the normal data center logon procedures. In addition to running on IBM (and IBM-compatible) mainframes, GSS has developed Geosupport Desktop Edition for running in the Windows environment. There are also several methods by which Geosupport running on a city mainframe can be accessed by applications running on other hardware platforms, including 3270 emulation and access through the city’s Intranet. Geosupport is also available via GeoX, Linux, .net and Java. This User Programming Guide can be used when programming in any of these environments.

For many user applications, only a subset of Geosupport’s functions, features and data items are relevant. In addition, many Geosupport options have defaults which are appropriate for most applications. Thus, even though Geosupport is a large-scale, multi-feature system, the user effort required to design an application to access it is often relatively modest.

Geosupport has an Application Programming Interface (API) that enables it to be accessed directly from a user-written batch or CICS application program. (Geosupport cannot be run in the VM environment.) The Geosupport API supports application programs written in any programming language that can issue a standard IBM external program call. COBOL, PL/1, the various types of IBM mainframe assembler languages (hereafter referred to generically as ‘Assembler’), NATURAL and C are five such languages. In addition, Geosupport has one batch and two interactive ‘stand-alone’ utility programs that enable users to satisfy many geographic processing needs without having to write custom application programs.

The ability of user-written applications to access Geosupport via its API enables users to avoid the burden of duplicating complex, specialized geographic processing routines within their own applications. The Geosupport API affords users total design control of their own applications, with their own input and output files, printed reports and screen formats; users develop those applications in their conventional data processing environments, using the programming languages they deem best suited to those applications.

The Geosupport batch utility program is called the Geosupport Batch Address Translator (GBAT). GBAT requires no user programming; to run GBAT, the user simply sets up a batch job containing JCL and GBAT control records. There are two Geosupport interactive utility programs, both of them CICS transactions. The principal interactive utility is called the Geographic Online Address Translator (GOAT), which provides general inquiry capabilities for almost all Geosupport functions. There is also a specialized interactive utility called Address / Intersection Map Zones (AIMZ), which displays a set of map identification numbers corresponding to an input address or intersection.