geographic determination library - pitney bowes

Geographic Determination Library i

Geographic Determination Library Reference Manual for Windows, z/OS

Version 40.04

Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Precisely, 2 Blue Hill Plaza, #1563, Pearl River, NY 10965.

© 1994, 2020 Precisely. All rights reserved.

Precisely is a wholly-owned subsidiary of Syncsort Incorporated. See www.precisely.com for information about our valuable trademarks.

The following trademarks are owned by the United States Postal Service®: CASS, CASS Certified, DPV, eLOT, FASTforward, First-Class Mail, Intelligent Mail, LACSLink, NCOALink, PAVE, PLANET Code, Postal Service, POSTNET, Post Office, RDI, SuiteLink, United States Postal Service, Standard Mail, United States Post Office, USPS, ZIP Code, and ZIP+4. This list is not exhaustive of the trademarks belonging to the Postal Service.

USPS Notice: Precisely holds a nonexclusive license to publish and sell ZIP+4 databases on optical and magnetic media. The price of the Precisely product is neither established, controlled, nor approved by the U.S. Postal Service.

Precisely is a non-exclusive licensee of USPS® for NCOALink® processing. Prices for the Precisely products, options and services are not established, controlled or approved by USPS® or United States Government. When utilizing RDI™ data to determine parcel-shipping costs, the business decision on which parcel delivery company to use is not made by the USPS® or United States Government.

Spectrum Geocoding Datasets used within Precisely applications are protected by various trademarks and by one or more of the following copyrights:

Copyright © United States Postal Service. All rights reserved.

© 2020TomTom. All rights reserved. This material is proprietary and the subject of copyright protection and other intellectual property rights owned by or licensed to TomTom or its suppliers. The use of this material is subject to the terms of a license agreement. Any unauthorized copying or disclosure of this material will lead to criminal and civil liabilities.

© 2020 HERE

Copyright © United States Census Bureau

The Master Location Data (MLD) product is a produced work that referenced the Microsoft US Building Footprints dataset. This dataset is available at https://github.com/Microsoft/USBuildingFootprints and is licensed under the Open Database License (ODbL). The license is available at https://opendatacommons.org/licenses/odbl/.

https://www.precisely.com/

https://github.com/Microsoft/USBuildingFootprints

https://github.com/Microsoft/USBuildingFootprints

https://opendatacommons.org/licenses/odbl/

https://opendatacommons.org/licenses/odbl/

Contents

Precisely Reference Manual for Windows 3

Chapter About the Library 5Geo-variance Buffer Generation 5Comparison Operations 6Linear Distance 6Percentage Overlap 6Basic Usage 6Spatial Attributes 7Contacting Technical Support 8

Chapter Basic Concepts 9Geographic Determination 9High-level Overview 9Handles 11Shapes 12Coordinates 12Distances 12

Chapter Installation 14Installation Requirements 14License Renewal 15Windows Installation Procedure 15

Chapter C Function Reference 17Function Formats 17Quick Reference 18Initialization Functions 18File Operation Functions 18GDL-Specific Functions 18Comparison Operation Functions 19Shape Operation Functions 19Conversion Functions 20

Chapter Using the Geographic Determi-nation Library 50

Developing a GDL Application 50Using GDL on Windows 50Using GDL on z/OS 50How GDL Works 51Getting Started 51Program Flow 52

Contents

Geographic Determination LibraryReference Manual for Windows 4

Include Files for C Development 52Include Files for Visual Basic Devel-opment 53Include Files for COBOL Develop-ment on z/OS Systems 53Samples 53

Chapter COBOL Procedure Reference 54Data Types 54Quick Reference 55Initialization Procedures 55File Operation Procedures 55GDL/zOS-Specific Procedures 55Comparison Operation Procedures 55Shape Operation Procedures 56

Summary of Return and Input Values 95GDL Return Values 95GDL File Types 97

GDL Shape Types 97GDL Shape Variables 97GDL Variables 97

Spatial Import 98

Formats Supported in GDL 99Autodesk Mapguide Format 99ESRI BNA Format 99ESRI Shapefile Format 99MapInfo® MIF/MID Format 100Spatial+ GSB Format 100

COBOL Copybook 101GDLCOPY 101

CHAPTER 1

About the Library

The Geographic Determination Library (GDL) is designed to be used in conjunction with Precisely’s address standardization and geocoding library, GeoStan. By accessing the actual run-time values created by GeoStan, GDL can generate a dynamic geo-variance buffer around the geocode. From there GDL can then perform several spatial comparison operations to generate a numeric confidence value. GDL does not process Canadian addresses.

The GDL library functions and procedures are accessible via a library, DLL, or copybook depending on the platform on which you are developing.

GDL is also distributed as an object module for z/OS users and provides variables in working storage for calls to GDL.

Presented below is a quick overview of the geo-variance buffer generation process and a description of the types of analyses along with their return values. This overview is intended to provide the reader with a summary and should not be taken as a complete list of the possible uses for GDL.

Geo-variance Buffer Generation

GeoStan performs geocoding based on address data. A geocode, i.e., the particular latitude/longitude coordinates associated with an address, can have one of four basic levels of quality associated with it. This quality level is determined by the address information provided and the data available in a data look-up table.

About the Library

Geographic Determination Library Reference Manual 6

GDL uses this quality level to create a polygon or geo-variance buffer around the geocoded point. This polygon describes the maximum probable geographic variance that point may have. For example, an address level geocode may have a variance of +/-165 feet East/West and +/-50 feet North/South. The geo-variance polygon outlines the boundary of this 33,000 square foot area. Once this buffer has been calculated, it can be compared to other spatial objects for accurate determinations.

Comparison Operations

Spatial objects describe various types of either topographic items (such as mountains, streets, or buildings) or geographic features (conceptual areas such as municipal boundaries, auto rating territories, or statistical analysis areas). These features can be described mathematically as points, lines, or polygons and are saved in a spatial file. GDL is able to access these spatial files and the objects they contain to perform two basic types of comparison operations: linear distance and percentage overlap.

Linear Distance

GDL can return a distance value in feet that describes either how close or far away a given point or line is from a geo-variance buffer. For example, the distance from a house to a fire station or the distance from the edge of a potential mudslide area to a specific building.

Percentage Overlap

Once GDL has created a geo-variance buffer, it is able to calculate if the buffer overlaps with another polygon and, if it does, how much it overlaps. The percentage value returned describes the probability that a point falls in the comparison area. This addresses an often typical problem of whether or not an address falls inside a specific area. For example, is a particular house in a flood zone.

Basic Usage

GDL has been highly tuned to perform geographic determination in a high performance environment. In order to perform the spatial comparison operations, the library uses a proprietary format for the spatial object file. These files are called GeoStan Spatial Boundary (GSB) files and can be created with the Spatial+ library. These GSB files need to be created and available prior to the execution of GDL. Please refer to the Spatial+ Reference Manual for detailed instructions on how to create these files.

NOTE: A GSB file must contain only one object type. For example, one GSB file contains only polygons, another file contains only lines, and yet another file contains only points.

About the Library


Spatial Attributes

You can also include your own data by using “attributes”. These spatial attributes might include population counts, revenue figures, demographic characteristics, or other information specific to a region or specific location. You can view the attribute information after you choose your input file, specify the input and outfield fields, and process the data.

About the Library


Contacting Technical Support

If you have any technical questions regarding the use of the Geographic Determination Library, contact Precisely Technical Support.. To open a Support case, go to https://support.precisely.com/casemanagement/. When you contact Precisely Technical Support, please have the following information ready:

• Product name• Company name under which the product is registered• Company name with which you are affiliated• Telephone number at which you may be contacted• Development environment (if applicable)• Thorough description of the problem

Precisely technical support representatives work closely with you so that:

• Your questions about Geographic Determination Library are answered quickly• Any problems you may encounter while using Geographic Determination Library

are resolved.

Precisely products make every effort to return accurate matches whenever possible, while providing the fewest false-positive matches. No product can match with 100 percent accuracy or handle every data error. Some inaccuracies are inherent in the software, as trade-offs are made in the match logic to balance high match rates with low false positive matches.

https://support.precisely.com/casemanagement/

https://support.precisely.com/casemanagement/

CHAPTER 2

Basic Concepts

This chapter provides an overview of several key terms and concepts that GDL uses.

Geographic Determination

Calculations made in the initial geocoding process may have produced an answer that is almost, but not totally, accurate. GDL eliminates any uncertainty by providing a confidence factor and associating it with the geocode so that additional rules may be applied. This confidence factor can be described as either a distance value (between two points and/or lines) or as a percentage representing the amount of overlap between two polygons.

Geographic determination describes both the spatial relationship between two entities and the degree of confidence in that description. High confidence determinations, based on any level of geocode (address, ZIP+4, ZIP+2, or ZIP Code) are critical for many geographically sensitive business decisions.

High-level Overview

To further understand how a GDL application works, this section provides a high-level overview of a GDL application that only performs polygon comparison operations (see Figure 1 on page 11.) First, the application attempts to geocode an address using GeoStan. If the address was successfully geocoded, GDL is invoked to create a geo-variance surface. Next, GDL determines the quality level of the geocode (address, ZIP+4, ZIP+2, or ZIP) and creates the

Basic Concepts


appropriate geo-variance surface. To test the variance surface, GDL calls are made to open a spatial file containing a polygon for comparison. GDL then returns the percentage overlap between the two areas.

The application then uses this value in conjunction with business rules to make the final determination. In this example, a 100 percent overlap would be understood to be a high confidence match. Anything less results in a low confidence match. The business rules used to evaluate the GDL results are unique to every organization and are based on the way you do business. Most important is that very fine levels of automated decision making can be implemented with GDL, especially when distance values are used.

For example, the business rules used in the example above could be modified to create new medium level confidence for address level polygons that overlapped between 99 and 75 percent. In this new situation, further distance calculations could be performed by GDL to determine how far inside the target area the geocode actually resides. The net result of this processing is that fewer expensive manual determinations need to be performed, saving your organization both time and money.

The following flow chart depicts one typical process that GDL might address.

Basic Concepts


Figure 1: Flowchart depicting the determination process

Handles

Throughout GDL, the concept of a handle is prevalent. A “handle” is a reference to an object that is required by the Library and is not to be manipulated directly by the developer. For example, when gdlInitialize is called to initialize the library, a handle is returned. This handle (or one derived from it) is required for many Library functions. Likewise, when the gdlOpenSpatialFile function is called, a file handle is returned and is required for all spatial comparison operations. It is important to note that

Standardize &Geocode Property

Address

GeocodedSuccessfully

Did not Geocode

Yes No

AddressGeocode

ZIP+2Geocode

ZIP CodeGeocode

ZIP+4Geocode

ManuallyProcess

Create StreetSegment Dynamic

Buffer

Create ZIP+2Dynamic Buffer

Use 5 digit ZIPCode Boundary

Create ZIP+4Dynamic Buffer

Test DynamicBuffer against

Territory

Bufferwholly inside

Territory

Territorywholly inside

Buffer

Bufferintersects with

Territory

High ConfidenceMatch

Low ConfidenceMatch

Completed Manually Process

Basic Concepts


two function calls, gdlGenerateErrorSurface and gdlGetStreetLength, require that GeoStan handles are passed. This handle is generated when the GeoStan library is initialized.

This approach satisfies the requirements that Precisely had when creating the library:

• The library must be language independent• The library must be platform independent• The library API must be the same regardless of the language or platform

The library does not require you to have any special knowledge about the above requirements. The most important concept to remember is this:

If a function creates a new handle, then memory or other resources have been allocated by the library. In order to return those resources to the system (free memory, close files, etc.), you must use the appropriate command to “terminate” the handle when you have completed the task.

Shapes

Within a GDL application, you need to create spatial objects in memory to perform your comparison operations. Conceptually, these objects are called “shapes” and can be used to represent points, lines, or polygons. Just as handles need to be terminated to release system resources after use, so do shapes. Use gdlShapeFree to deallocate memory used by shapes.

Coordinates

Unique to GDL, the coordinates used are always represented as 64-bit doubles. Longitude and latitude coordinates are always in degrees. Positive numbers represent the Eastern and Northern hemispheres, respectively, and negative numbers represent the Western and Southern hemispheres. For example, the point 140W by 30N would be represented as –140.0,30.0. The library always assumes that the longitude coordinate is the horizontal direction and the latitude coordinate is the vertical direction. Support is not provided for user coordinates.

Distances

The distances referred to herein are straight line distances and do not account for the curvature of the earth. The distances calculated in GDL are very accurate for points within 50 to 100 miles of each other. As the north-south distance becomes greater, slight errors in calculations can occur. The examples in Table on page 13 are for points that are oriented directly north or south of the base point, which would have the largest error for the distance given.

Basic Concepts


Error introduced by distance from base point

North-South Distance Maximum Error

50 miles 0.25% (0.1 miles)

200 miles 0.9% (1.8 miles)

400 miles 1.25% (5 miles)

1,000 miles 1.9% (19 miles)

CHAPTER 3

Installation

This chapter describes system requirements for GDL, as well as how to install on the Windows platform. If you are installing GeoStan™ for z/OS, refer to the Installation Notes provided with the installation package.

NOTE: GDL on UNIX is available only as part of AddressBroker. For installation instructions, see the GeoStan Geocoding Suite Installation Guide for Unix and Linux.

Installation Requirements

You can install GDL on platforms with thread-safe and non thread-safe versions as listed in Table .

Supported Platforms for Thread-Safe and Non Thread-Safe

Versions

To see a list of the specific OS versions that Precisely supports, see the GeoStan Geocoding Suite Supported Platforms document available at support.precisely.com.

GDL is distributed as Windows DLL files, and as UNIX C libraries. Refer to this table for a complete listing of the Windows DLL files.

Windows OS Mainframe OS

Windows 32- and 64-bit z/OS

https://support.precisely.com

Installation


Windows DLL filenames

table lists the APIs that are supported on each OS.

GDL APIs supported on each OS.

License Renewal

License renewal is automatic; you do not need to take any action to renew your license. You must, however, provide written notice to Precisely. if you do not want to renew. Written notice of your intent not to renew must be received by Precisely no less than 60 days prior to the expiration of your current term. A warning message is displayed when you execute a GDL application if you are within 90 days of your renewal date.

Windows Installation Procedure

Step 1 – Install the Product

1 Download the Geographic Determination Library installation .zip file for your platform and extract the files.

2 Close all Windows programs.

3 In the root folder where you extracted the files, locate setup.exe. Right-click on setup.exe and select “Run as administrator”.

4 The Geographic Determination Library install wizard launches and will guide you through the installation process.

Platform Filename Example

Windows Thread-Safe <progname>MT.dll gdlMT.dll

Windows Non Thread-Safe <progname>.dll gdl.dll

C COBOL VB

Windows OS

z/OS

Installation


NOTE: You only need to install the license file if you are a new customer, if you are upgrading, or if you are renewing your contract with Precisely. Regular updates do not require new license files. The license file and password are provided via e-mail to the primary contact in your company.

Step 2 – Install the Data FilesNOTE: If you plan to use GSD Split, complete the procedure provided in the GeoStan

Geocoding Suite Utilities Reference Manual. The data files required for processing must reside on your system.

NOTE: For descriptions of the data files you may need to complete the desired processing and the data installation procedure, view the Installation Notes for the Centrus Data Products Suite and the Centrus Data Products Release Announcement included in the installation package.

CHAPTER 4

C Function Reference

This chapter describes how to incorporate GDL functions into your application.

Function Formats

The format for the syntax of each function is:

ReturnType FunctionName(ArgumentType identifier, ArgumentType identifier)

where:

• ReturnType is the type of return value associated with the function.

• FunctionName is the name of the function.• ArgumentType is the type of the identifier that follows.• identifier is the descriptive name of the argument.

Primitive data types used are as follows:

intl 32-bit signed integer

double 64-bit floating point

pstr pointer to null-terminated string

gdlHandle 32- or 64-bit1 signed integer

gdlFileHandle 32-or 64-bit1 signed integer



1. The size of the pointer is dependent on the operating system: 32-bit for a 32-bit OS and 64-bit for a 64-bit OS.

All examples in the function reference are shown using “C.”

NOTE: The return values and input values provided for each function are explained in detail in Appendix A, “Summary of Return and Input Values.”

Quick Reference

Initialization FunctionsgdlInitializeInitializes the GDL Library. Must be called before any other Library function.gdlTerminateReleases resources allocated from gdlInitialize.

File Operation FunctionsgdlWriteShapeWrites the shape out to the file system in a well known spatial data format, including Precisely’

GSB, ESRI’s BNA and MapInfo’s MIF/MID formats.gdlOpenSpatialFileOpens a file for spatial analysis.gdlCloseSpatialFileCloses the file previously opened by gdlOpenSpatialFile.gdlGetVersionReturns a string containing the GDL library version number.

GDL-Specific FunctionsgdlGenerateErrorSurfaceGenerates an error surface from a match found inside the GeoStan™ handle.gdlGetAttributeCountReturns the number of attributes present in the associated GSA file.gdlGetAttributeInfoByNameRetrieves the data in the GSA attribute file based on the name of the attribute.gdlGetAttributeInfoByNumberRetrieves the data in the GSA attribute file based on the column number.gdlGetAttributeNameByNumberRetrieves the field name information in the GSA attribute file by column number.

gdlShape 32- or 64-bit1 signed integer

GsId 32- or 64-bit1 signed integer



gdlGetConfidenceSurfaceTypeGenerates a confidence surface type based on information from a GeoStan match.gdlGetStreetLengthDetermines the street segment length for address level geocodes. Use with address-level matches.gdlSetStrSets properties of the gdlHandle.

Comparison Operation FunctionsgdlFindNearestFinds the nearest point or line to a given point. gdlFindNextFinds the next nearest feature after a successful call to gdlFindNearest.gdlFindPolygonOverlapDetermines if a binary polygon overlap has occurred and, if so, returns the polygon that is in

overlap with the input polygon.gdlFindNextPolygonOverlapDetermines if another binary polygon overlap has occurred and, if so, returns the polygon that is

in overlap with the input polygon.gdlFindPolygonOverlapPercentageDetermines if a percentage polygon overlap has occurred and, if so, returns the polygon and the

percentage overlap with the input polygon. gdlFindNextPolygonOverlapPercentageDetermines if another percentage polygon overlap has occurred and, if so, returns the polygon and

the percentage overlap with the input polygon. gdlPointInPolygonFinds the first polygon that contains the input point and determines within which polygon a

geocoded address is located. gdlPointInPolygonNextFinds the next polygon that contains the input point.gdlNearDistanceDetermines the minimum distance that exists between an error surface or a geocoded point and

another point or line.gdlFarDistanceDetermines the distance between the farthest point of the error surface and the nearest point of the

feature (point, line or polygon).gdlManhattanDistanceDetermines the Manhattan distance between two points.gdlDistanceDetermines the straight line distance between two points.

Shape Operation FunctionsgdlShapeGetLongReturns properties from the shape object in the form of a long integer.gdlShapeGetStrReturns properties from the shape object in the form of a string.



gdlShapeCreateCreates a shape of a given type with specified coordinates.gdlShapeGetCoordsReturns the coordinates with which a shape of a given type is created.gdlShapeFreeDeallocates any memory associated with a shape.

Conversion FunctionsgdlSpatialConvertWrites features out to a particular spatial data format.

gdlCloseSpatialFileCLOSES THE FILE PREVIOUSLY OPENED BY GDLOPENSPATIALFILE.

Syntaxintl gdlCloseSpatialFile( gdlFileHandle* hFile );

ArgumentshFile Pointer to the gdlFileHandle returned by gdlOpenSpatialFile. Input

Return valuesGDL_OK

PrerequisitesgdlOpenSpatialFile

Alternates

None.

Notes

Must be called upon completion of use of the spatial file prior to calling gdlTerminate.



gdlDistanceDETERMINES THE STRAIGHT LINE DISTANCE BETWEEN TWO POINTS.

Syntaxintl gdlDistance( gdlHandle hGdl, gdlShape point1, gdlShape point2, intl* distance );

ArgumentshGdl The gdlHandle initialized by gdlInitialize. Input.

point1 Pointer to a gdlShape that contains the geocode coordinates representing the first point. Input.

point2 Pointer to a gdlShape that contains the geocode coordinates representing the second point. Input.

distance The distance in feet. Output.

Return valuesGDL_NOT_LICENSEDGDL_ERRORGDL_WRONG_TYPEGDL_OK

PrerequisitesgdlInitializegdlShapeCreate or gdlGenerateErrorSurface

AlternatesgdlManhattanDistance

Notes

The following diagram illustrates a straight line distance between two points:



gdlFarDistanceDETERMINES THE DISTANCE BETWEEN THE FARTHEST POINT OF THE ERROR SURFACE AND THE NEAREST POINT OF THE FEATURE (POINT OR LINE).

Syntaxintl gdlFarDistance( gdlHandle hGdl, gdlShape shape1, gdlShape shape2, intl* distance );


shape1 The gdlShape object representing the error surface. Input.

shape2 The gdlShape object representing the object found using gdlFindNearest (or gdlFindNext). Input.


Return valuesGDL_NOT_LICENSEDGDL_ERRORGDL_OK

PrerequisitesgdlFindNearestgdlGenerateErrorSurface

AlternatesgdlNearDistance

NOTE: To return the distance from the farthest point of the error surface to the nearest point of the feature, the error surface must be passed in as shape1 and the feature as shape2.

Notes

The following diagram illustrates the distance between the farthest point of the error surface and the nearest point of a line:



gdlFindNearestFINDS THE NEAREST POINT OR LINE TO A GIVEN POINT.

Syntaxintl gdlFindNearest( gdlFileHandle hFile, gdlShape input, gdlShape* output, intl type, intl max );

ArgumentshFile The gdlFileHandle returned by gdlOpenSpatialFile. Input.

input The gdlShape object that contains the input point. Input.

output A pointer to the nearest gdlShape object. Output.

type The type of shape to find. Input.

Type options:

max The maximum to search in feet. Input.

Return valuesGDL_WRONG_TYPEGDL_NOT_FOUNDGDL_ERRORGDL_OK


GDL Shape Types

GDL_POINT

GDL_LINE

Far Distance

Feature

1168 ft

Polygon

Error Surface



gdlShapeCreate or gdlGenerateErrorSurface

Alternates

None.

Notes

Features are returned from nearest to farthest.

Following instances of this function, you should call gdlShapeFree with the output shape when you are finished using the output shape to release system resources.

The following diagram illustrates the nearest point and nearest line to a given point:

gdlFindNextFINDS THE NEXT NEAREST FEATURE; CALLED AFTER SUCCESSFUL GDLFINDNEAREST.

Syntaxintl gdlFindNext( gdlFileHandle hFile, gdlShape* output, intl type );


output A pointer to the next nearest gdlShape object. Output.

type The type of shape to find. Input.Type options:

GDL Shape Types

GDL_POINT

GDL_LINE

��



Return valuesGDL_NOT_FOUNDGDL_ERRORGDL_OK

PrerequisitesgdlFindNearest

Alternates

None.

Notes


gdlFindNextPolygonOverlapDETERMINES IF ANOTHER BINARY POLYGON OVERLAP HAS OCCURRED AND, IF SO, RETURNS THE POLYGON THAT IS IN OVERLAP WITH THE INPUT POLYGON.

Syntaxintl gdlFindNextPolygonOverlap( gdlFileHandle hFile, gdlShape* output );


output A pointer to the overlapping polygon. Output.


PrerequisitesgdlFindPolygonOverlap

AlternatesgdlFindNextPolygonOverlapPercentage

Notes

Following instances of this function, you should call gdlShapeFree with the output polygon when you are finished using the output polygon to release system resources.



gdlFindNextPolygonOverlapPercentageDETERMINES IF ANOTHER PERCENTAGE POLYGON OVERLAP HAS OCCURRED, RETURNING THE POLYGON AND THE PERCENTAGE OVERLAP WITH THE INPUT POLYGON.

Syntaxintl gdlFindNextPolygonOverlapPercentage( gdlFileHandle hFile, gdlShape* output, double* overlap );



overlap The percentage of overlap. Output.


PrerequisitesgdlFindPolygonOverlapPercentage

AlternatesgdlFindNextPolygonOverlap

Notes

The percentage overlap determines the confidence rating.


gdlFindPolygonOverlapDETERMINES IF A BINARY POLYGON OVERLAP HAS OCCURRED AND, IF SO, RETURNS THE POLYGON THAT IS IN OVERLAP WITH THE INPUT POLYGON.

Syntaxintl gdlFindPolygonOverlap( gdlFileHandle hFile, gdlShape polygon, gdlShape* output );


polygon The polygon with which to determine overlap. Input






AlternatesgdlFindPolygonOverlapPercentagegdlGenerateErrorSurface

Notes


The following diagram illustrates a polygon that is in overlap with an input polygon:



gdlFindPolygonOverlapPercentageDETERMINES IF A PERCENTAGE POLYGON OVERLAP HAS OCCURRED AND, IF SO, RETURNS THE POLYGON AND THE PERCENTAGE OVERLAP WITH THE INPUT POLYGON.

Syntaxintl gdlFindPolygonOverlapPercentage( gdlFileHandle hFile, gdlShape polygon, gdlShape* output, double* overlap );


polygon The polygon with which to determine overlap. Input.


overlap The percentage of overlap. Output.



AlternatesgdlFindPolygonOverlap

Notes



The following diagram illustrates a polygon and the percentage overlap with the input polygon:



gdlGenerateErrorSurfaceGENERATES AN ERROR SURFACE FROM A MATCH FOUND INSIDE THE GEOSTAN HANDLE.

Syntaxintl gdlGenerateErrorSurface( gdlHandle hGdl, GsId hGeostan, intl bufferWidth, gdlShape* point, gdlShape* surface );


hGeostan The GsId from the GeoStan library. This handle must contain a valid GeoStan match. Input.

buffer Width The distance to buffer Address Level and ZIP+4 Level matches. Input.

point Pointer to a gdlShape that contains the geocode coordinates. Output.

surface Pointer to a gdlShape that contains the error surface coordinates. Output.

Return valuesGDL_ERRORGDL_NOT_LICENSEDGDL_NO_ADDRESSMATCH_FOUNDGDL_ZIP5_FILE_ERRORGDL_ZIP9_FILE_ERRORGDL_TEMP_PATH_ERRORGDL_OK

PrerequisitesgdlSetStrgsFind (from GeoStan)

Alternates

None.

Notes

After a call to gdlGenerateErrorSurface, the internal data geocode buffers maintained by the GeoStan handle are set to NULLs. Because of this, the GeoStan handle is always invalidated after a call to gdlGenerateErrorSurface.

Following instances of point or surface arguments of this function, you should call gdlShapeFree with the output shape (point and surface) when you are finished using the output shape to release system resources.



The gdlGenerateErrorSurface function provides a worst-case scenario for address location. The geocode error surface (geo-variance region) provides the smallest possible surface that an address can be determined. The GDL generates the geocode error surfaces. Based on the GeoStan Match Code, a buffer is built around a given street segment, ZIP+4, or ZIP+2 that indicates a geo-variance surface that contains the location.

Match Code Geo-Variance (Error) Surface

Address Level Buffer street segment

Intersection Match Circular buffer that represents 2X the buffer distance

ZIP+4 Buffer all street segments in ZIP+4

ZIP+2 Convex Hull around all ZIP+4s that make up a ZIP+2

ZIP Code The ZIP Code boundary

AS7 and APxx (point locations) are treated as intersections to prevent the generation of an address level error surface. Because there are no streets in a point location code, an address level error surface cannot be generated.

Auxiliary File matches create an error surface that is similar to one created for intersection matches.

gdlGetAttributeCountRETURNS THE NUMBER OF ATTRIBUTES PRESENT IN THE ASSOCIATED GSA FILE.

Syntaxintl gdlGetAttributeCount ( gdlFileHandle hFile, intl * attr_count);

ArgumentshFile A gdlFileHandle. Input.

*attr_count The number of fields in the opened attribute (GSA) file. Output.

Return Value

Number of fields in gdlOpenSpatialFile. If a GSA file does not exist, a GDL_ERROR is returned and attr_count is set to zero.




Alternates

None.

Exampleintl count;if( gdlGetAttributeCount( hFile, &count ) == GDL_OK ){ for( intl i = 0; i < count; i++ ){ gdlAttributeInfoStruct info; gdlGetAttributeInfoByNumber( hfile, i, &info );}}

gdlGetAttributeInfoByNameRETRIEVES THE DATA IN THE GSA ATTRIBUTE FILE BASED ON THE NAME OF THE ATTRIBUTE.

Syntaxintl gdlGetAttributeInfoByName ( gdlFileHandle hFile, pstr * fieldName, gdlAttributeInfoStruct* info)


*fieldName The field name in the attribute (GSA) file. Input.

*info The gdlAttributeInfoStruct containing the information about the attribute. Output.

Return ValueGDL_OKGDL_ERROR


Alternates

None.

Notes

The gdlGetAttributeInfoByName function uses gdlAttributeInfoStruct as a data structure to hold information about the specified attribute.



Example

The gdlAttributeInfoStruct holds the following file information:

gdlGetAttributeInfoByNumberRETRIEVES THE DATA IN THE GSA ATTRIBUTE FILE BASED ON THE COLUMN NUMBER.

Syntaxintl gdlGetAttributeInfoByNumber ( gdlFileHandle hFile, intl fieldNumber, gdlAttributeInfoStruct* info);


fieldNumber The field index into the attribute GSA file. Input.

*info The gdlAttributeInfoStruct that contains the information about the attribute. Output.



Alternates

None.

Notes

The gdlGetAttributeInfoByNumber function uses gdlAttributeInfoStruct as a data structure to hold information about the specified attribute.

Field Description

char name[12] Field name.

char value[256] Field value.

intl length Field length.

intl type Field type: CHARACTER=67, NUMERIC=78.

intl decimals If numeric, are there any decimals?



Example

The gdlAttributeInfoStruct holds the following file information:

gdlGetAttributeNameByNumberRETRIEVES THE FIELD NAME INFORMATION IN THE GSA ATTRIBUTE FILE BY COLUMN NUMBER.

Syntaxintl gdlGetAttributeNameByNumber ( gdlFileHandle hFile, intl fieldNumber, pstr name, intl bufSize );


fieldNumber Column of the attribute in the GSA file. Output.

name A buffer to hold the found attribute name. Output.

bufSize The size of the buffer that contains the identifier of the object in which the point is located. If the buffer size is smaller than the identifier, the identifier is truncated. Input.



Alternates

None.

Field Description

char name[12] Field name.

char value[256] Field value.

intl length Field length.

intl type Field type: CHARACTER=67, NUMERIC=78.

intl decimals If numeric, are there any decimals?



Notes

The gdlGetAttributeNameByNumber is a convenience function.The gdlGetAttributeInfoByNumber function might be used more often to return the column name by column number.

gdlGetConfidenceSurfaceType GENERATES A CONFIDENCE SURFACE TYPE BASED ON INFORMATION FROM A GEOSTAN MATCH.

Syntax intl gdlGetConfidenceSurfaceType( gdlHandle hGdl, gdlConfidenceSurfType *confSurfType );

Arguments hGdl Identifies the gdlHandle. Input.

confSurfType Type of confidence surface. Output.

Type options:

Type Value Description

GDL_SURF_UNDEFINED 0 Nothing has been searched yet.

GDL_SURF_ERROR 1 The search failed - address was not found.

GDL_SURF_INTERSECTION

2 Intersection confidence-surface generated.

GDL_SURF_ADDRESS 3 Address error-surface generated.

GDL_SURF_POINT 4 Point level match.

GDL_SURF_AREA1 5 State confidence-surface generated.

GDL_SURF_AREA2 6 County confidence-surface generated.

GDL_SURF_AREA3 7 City confidence-surface generated.

GDL_SURF_AREA4 8 Not used in USA.

GDL_SURF_POSTAL1 9 A Zip confidence -surface generated.

GDL_SURF_POSTAL2 10 A Zip + 2 confidence -surface generated.

GDL_SURF_POSTAL3 11 A Zip + 4 confidence -surface generated

GDL_SURF_POSTAL4 12 Not used in USA.



Return valuesGDL_OKGDL_NOT_LICENSED

PrerequisitesgdlInitialize

gdlGenerateErrorSurface

Alternates

None.

Notes

The error (or confidence) surface type indicates the type of location that the surface encloses.

The enum definition, gdlConfidenceSurfaceType, defines the full set of possible surface types that can be generated.

In general, the better the location code from GeoStan, the higher quality the surface type.

gdlGetStreetLengthDETERMINES THE STREET SEGMENT LENGTH OR THE LENGTH OF A DIAGONAL.

Syntaxintl gdlGetStreetLength( gdlHandle hGdl, GsId hGeostan, gdlShape* point, intl* length );


hGeostan The GsId from the GeoStan library. This handle must contain a valid GeoStan match. Input.

point Pointer to a gdlShape representing the geocoded point. Output.

length The length of the street segment, or the length of the MBR diagonal. Output.

Return valuesGDL_ERRORGDL_NOT_LICENSEDGDL_OK

PrerequisitesgdlInitialize, gsFind (from GeoStan)



Alternates

None.

Notes

Given a GeoStan handle, we can determine the street segment length for address level geocodes. The street length values can be used to make a fast determination of complete polygon inclusion when used in conjunction with the gdlPointInPolygon and gdlNearDistance functions.

If a ZIP-level geocode is returned, the distance for the minimum bounding rectangle (MBR) is also returned.

A GeoStan handle remains valid after calling gdlGetStreetLength.

Following instances of point arguments of this function, you should call gdlShapeFree with the output point when you are finished using the output point to release system resources.

gdlGetVersionRETURNS A STRING CONTAINING THE GDL LIBRARY VERSION NUMBER.

Syntaxintl gdlGetVersion( char* buffer, const int buflen);

Argumentsbuffer The location to store the returned version string. Output.

buflen The maximum data size the buffer can contain. The buffer size must be at least 11 characters. Input.

Return ValuesGDL_OK

Prerequisites

None.

Alternates

None.

Notes

The string returned is in the following format:GDL v#.#



For example, GDL v1.3.

gdlInitialize INITIALIZES THE GEOGRAPHIC DETERMINATION LIBRARY; MUST BE CALLED BEFORE ANY OTHER LIBRARY FUNCTION.

Syntaxintl gdlInitialize( gdlHandle* hGdl, intl number, char* filename );

ArgumentshGdl Pointer to a gdlHandle. Output.

number License password. Input.

filename License filename. Input.

Return valuesGDL_NOT_LICENSEDGDL_OK

Prerequisites

None.

Alternates

None.

Notes

This should be the first function called. Call gdlTerminate when finished with gdlHandle.

gdlManhattanDistanceDETERMINES THE MANHATTAN DISTANCE BETWEEN A POINT AND ANOTHER POINT.

Syntaxintl gdlManhattanDistance( gdlHandle hGdl, gdlShape point1, gdlShape point2, intl* distance );


point1 Pointer to a gdlShape that contains the geocode coordinates representing the first point. Input.

point2 Pointer to a gdlShape that contains the geocode coordinates representing the second point. Input.




Return valuesGDL_NOT_LICENSEDGDL_WRONG_TYPEGDL_ERRORGDL_OK

PrerequisitesgdlShapeCreate or gdlGenerateErrorSurface

AlternatesgdlDistance

Notes

The following diagram illustrates the Manhattan distance between two points:

gdlNearDistanceDETERMINES THE MINIMUM DISTANCE THAT EXISTS BETWEEN AN ERROR SURFACE AND ANY OTHER FEATURE: POINT OR LINE.

Syntaxintl gdlNearDistance( gdlHandle hGdl, gdlShape shape1, gdlShape shape2, intl* distance );


shape1 The gdlShape object representing the error surface. Input.

shape2 The gdlShape object representing the object found using gdlfindnearest (or gdlfindnext). Input.


Return valuesGDL_NOT_LICENSEDGDL_ERROR



GDL_OK

PrerequisitesgdlFindNearestgdlGenerateErrorSurface

Alternates

None.

Notes

The order of the objects does not affect the distance returned. However, for consistency, Precisely recommends that the error surface be passed as shape1.

The following diagram illustrates the minimum distance between an error surface and a line:

gdlOpenSpatialFileOPENS A FILE FOR SPATIAL ANALYSIS.

Syntaxintl gdlOpenSpatialFile( gdlHandle hGdl, gdlFileHandle* hFile, char* filename );


hFile A pointer to a gdlFileHandle. Output.

filename The filename of the spatial file to open. Input.

Return valuesGDL_ERRORGDL_NOT_FOUNDGDL_NOT_LICENSEDGDL_OK

Near Distance

Feature

682 ftPolygon

Error Surface




Alternates

None.

Notes

Call gdlCloseSpatialFile when finished with gdlFileHandle.

gdlPointInPolygonFINDS THE FIRST POLYGON THAT CONTAINS THE INPUT POINT.

Syntaxintl gdlPointInPolygon( gdlFileHandle hFile, gdlShape point, gdlShape* polygon );


point Pointer to a gdlShape that contains the geocode coordinates. Input.

polygon A pointer to the first polygon found to contain the input point. Output.


PrerequisitesgdlOpenSpatialFilegdlShapeCreate or gldGenerateErrorSurface

Alternates

None.

Notes

Call gdlShapeFree on the output polygon.

The following diagram illustrates the first polygon that contains the input point:



gdlPointInPolygonNextFINDS THE NEXT POLYGON THAT CONTAINS THE INPUT POINT.

Syntaxintl gdlPointInPolygon( gdlFileHandle hFile, gdlShape* polygon );


polygon A pointer to the next polygon found to contain the input point. Output.


PrerequisitesgdlPointInPolygon

Alternates

None.

Notes

Call gdlShapeFree on output polygon.

gdlSetStrALLOWS THE USER TO SET THE PROPERTIES OF THE GDLHANDLE.



Syntaxintl gdlSetStr( gdlHandle hGdl, intl type, char* value,intl size );


type The type of shape to find. Input.

Type options:

value An array of characters from which to read the property value. Input.

size The size of the character array in value. Input.



Alternates

None.

gdlShapeCreateCREATES A SHAPE OF A GIVEN TYPE WITH SPECIFIED COORDINATES.

Syntaxintl gdlShapeCreate( gdlHandle hGdl, gdlShape* shape, char* name, intl type, double* x, double* y, intl* pointsPerPart, intl partCount );

GDL Variables Description

GDL_ZIP5_FILENAME Name of the GSB file that contains the ZIP Code boundaries.

GDL_ZIP9_FILENAME Name of the US.Z9 file of ZIP Code centroids.

GDL_TEMP_PATHNAME The temporary path.

GDL_GEOSTAN_PATH Direct GDL to return data in the datum specified in GeoStan using GsSetDatum. GDL performs datum conversions on the address- and ZIP4-level error surfaces created with gdlGenerateErrorSurface. This value should be the same as the value used to initialize GeoStan. If this path is not set, GDL returns data in the NAD83 datum.




shape A pointer to the new gdlShape object. Output.

name The name of the object being created. Input.

type The type of shape to create. Input.

Type options.

x An array of x coordinates in decimal degrees. Input.

y An array of y coordinates in decimal degrees. Input.

pointsPerPart An array of integers indicating the number of points in each part. Input.

partCount The number of parts. Input.



Alternates

None.

Notes


gdlShapeFreeDEALLOCATES ANY MEMORY ASSOCIATED WITH A SHAPE.

Syntaxintl gdlShapeFree( gdlShape* shape );

GDL Shape Types

GDL_POINT

GDL_LINE

GDL_POLYGON



Argumentsshape The pointer to the shapeObject needing destruction. Input.

Return valuesGDL_OK

PrerequisitesgdlGenerateErrorSurface, gdlFindNearest, gdlFindNext, gdlFindPolygonOverlap, gdlFindNextPolygonOverlap, gdlFindPolygonOverlapPercentage, gdlFindNextPolygonOverlapPercentage, gdlPointInPolygon, gdlPointInPolygonNext, gdlShapeCreate

Alternates

None.

Notes

Failure to call gdlShapeFree after those function calls may result in a cumulative loss of memory resources.

gdlShapeGetCoordsRETURNS THE COORDINATES WITH WHICH A SHAPE OF A GIVEN TYPE IS CREATED.

Syntaxintl gdlShapeGetCoords( gdlHandle hGdl, gdlShape shape, intl* type, double* x, double* y, intl* pointsPerPart, intl partCount, intl maxPoints, intl maxParts );


shape The shape from which to get coordinates. Input.

type The type of shape being sought. Output.

x An array of x coordinates in decimal degrees. Output.

y An array of y coordinates in decimal degrees. Output.

GDL Shape Types

GDL_POINT

GDL_LINE

GDL_POLYGON



pointsPerPart An array of long integers indicating the number of points in each part. Output.

partCount The number of parts. Output.

maxPoints The maximum number of points that fit into the x and y arrays above. Input.

maxParts The maximum number of parts that fit into the pointsPerPart array above. Input.

Return valuesGDL_NOT_LICENSEDGDL_ERRORGDL_OK

Prerequisites

None.

Alternates

None.

gdlShapeGetLongRETURNS PROPERTIES FROM THE SHAPE OBJECT IN THE FORM OF A LONG INTEGER.

Syntaxintl gdlShapeGetLong( gdlShape shape, intl type, intl* value );

Argumentsshape The GDL shape. Input.

type The type of shape variable to return. Input.

value A pointer to the value. Output.

Return valuesGDL_ERRORGDL_OK

GDL Shape Variables Explanation

GDL_TYPE The type of shape

GDL_PART_COUNT The number of parts the shape has

GDL_POINT_COUNT The total number of points



Prerequisites

None.

Alternates

None.

gdlShapeGetStrRETURNS PROPERTIES FROM THE SHAPE OBJECT IN THE FORM OF A STRING.

Syntaxintl gdlShapeGetStr( gdlShape shape, intl type, char* value, intl max_size );

Argumentsshape The GDL shape. Input.

type The type of variable to return. Input.

value An array of characters in which to place the property value. Output.

max_size The size of the character array in value. Input.

Return valuesGDL_ERRORGDL_OK

Prerequisites

None.

Alternates

None.

gdlSpatialConvertWRITES A SUBSET OF FEATURES FROM A SPATIAL FILE TO A PARTICULAR SPATIAL DATA FORMAT.

GDL Type Variables Explanation

GDL_NAME The name of the object.

GDL_NAME2 The secondary name of the object



Syntaxintl gdlSpatialConvert( gdlHandle hGdl,gdlFileHandle hFile,char* filename, intl filetype, intl featuretype, double minx, double miny, double maxx, double maxy );

ArgumentshGdl The gdlHandle. Input.

hFile The gdlFileHandle of the Spatial file to read the subset of features from. Input.

filename The filename to use to output the file. Input.

filetype The type of the file to write. Options include: GDL_SHP, GDL_SDF, GDL_GSB, GDL_BNA, and GDL_MIF. Input.

featuretype The type of features to write. Options include: GDL_POINT, GDL_LINE, and GDL_POLYGON.

minx The minimum x coordinate in decimal degrees. Input.

miny The minimum y coordinate in decimal degrees. Input.

maxx The maximum x coordinate in decimal degrees. Input.

maxy The maximum y coordinate in decimal degrees. Input.

Return valuesGDL_OKGDL_NOT_LICENSEDGDL_ERROR

Prerequisites

None.

Alternates

None.

Notes

There are no extra licensing requirements for gdlSpatialConvert.

A GSB file must contain only one object type. For example, one GSB file should contain only polygons, another file should contain only lines, still another file should contain only points, etc.

gdlTerminateRELEASES RESOURCES ALLOCATED FROM GDLINITIALIZE.

Syntaxintl gdlTerminate( gdlHandle* hGdl );



ArgumenthGdl A pointer to the gdlHandle initialized by gdlInitialize. Input.

Return valuesGDL_NOT_LICENSEDGDL_OK


Alternates

None.

Notes

This function must be the last function called from the library.

gdlWriteShape WRITES THE SHAPE TO THE FILESYSTEM IN A WELL KNOWN SPATIAL DATA FORMAT.

Syntaxintl gdlWriteShape( gdlHandle hGdl, gdlShape shape, char* filename, intl type );


shape The actual shape to be written out. Input.

filename The name of the file to write. Input.

type The type of format to write to the file system. Input.


Data formats Description

GDL_SHP ESRI’s Shape file format

GDL_GSB Precisely Spatial+™ GSB format

GDL_SDF Autodesk SDF format

GDL_MIF MapInfo® MIF/MID formats

GDL_BNA ESRI’s BNA format



Prerequisites

None.

Alternates

None.

Notes

Provides a graphical depiction of the error buffer with a wide variety of mapping tools. Precisely’ GSB, ESRI’s BNA and SHAPE, and MapInfo’s MIF/MID formats are supported.

CHAPTER 5

Using the Geographic

Determination Library

Developing a GDL Application

This chapter explains the general use of the Geographic Determination Library function set and how to incorporate these functions into your application. To assist in learning, a simple program using the Geographic Determination Library functions is shown at the end of this chapter.

Within the library, all the public functions begin with gdl, such as gdlOpenSpatialFile. Where possible, you should avoid using variables, constants, or macros beginning with gdl or pip. See the include file in the directory for the development environment you are using for a complete list of visible symbols.

Using GDL on Windows

To successfully use GDL, your project must define one or all of these symbols:

__NT___WIN32WIN32

You are not warned with compile or link errors if these symbols are undefined, but your application does not

Using the Geographic Determination Library


function properly. The most common error if the symbols are not defined is to run out of stack space.

Microsoft compilers typically define these symbols for you, but we strongly recommend defining them in your project for completeness.

Using GDL on z/OS

If you are not using JCL supplied by Precisely, you should specify correct control cards and link to the appropriate object modules and use the data definitions in Table .

z/OS Data Definitions

How GDL Works

The Geographic Determination Library allows you to determine a geographic region that describes the maximum probable variance associated with the geocode. This geographic region is referred to as a geo-variance buffer or surface. Once you have this surface area created, there are a number of functions available in GDL that allow you to make comparisons between it and other geographic features.

There are essentially two types of comparisons available to you, near/far distance comparisons and polygon overlap comparisons. Distance comparisons are useful when you need to determine with great confidence whether or not an address is located within a certain distance of another feature. Polygon overlap comparisons are useful for determining whether or not your geocoded address is located within another polygon.

Getting Started

GDL functions use three internal data structures: gdlHandle, gdlFileHandle and gdlShape. Whenever you make a function call that results in one of these data structures being returned as an output parameter, you must call a corresponding function to free the resources associated with the data structure.

Data Definition Name

File Type

Y – Required for library initializationN – Optional Usage

ZIPIN Input Y zip5.gsb (ZIP Code boundaries)

ZIPSRCH Input Y us.z9 (ZIP Code centroids)



To initialize the library, call the gdlInitialize function. This function initializes and returns a gdlHandle. When you are using gdlHandle, call gdlTerminate to release resources associated with it.

To open a spatial file, call the gdlOpenSpatialFile function. This function initializes a gdlFileHandle. When you are done using gdlFileHandle, call gdlCloseSpatialFile to release resources associated with the gdlFileHandle.

The following functions initialize a gdlShape object:

gdlGenerateErrorSurface gdlGetStreetLengthgdlFindNearestgdlFindNextgdlFindPolygonOverlapgdlFindNextPolygonOverlapgdlFindPolygonOverlapPercentagegdlFindNextPolygonOverlapPercentagegdlPointInPolygongdlPointInPolygonNextgdlShapeCreate

After calling one of the previous functions, you must call gdlShapeFree to release resources associated with the gdlShape object.

Program Flow

GDL applications normally follow the program flow listed below:

1 Initialize the GDL library using gdlInitialize.

2 Set properties necessary for generating error surfaces with the gdlSetStr function.

3 Initialize the GeoStan™ library and call GsFind in order to geocode an address.

4 Generate an error surface by passing the GeoStan handle that contains a valid match to the gdlGenerateErrorSurface function.

5 Open a spatial file to make comparisons with using the gdlOpenSpatialFile function.

6 Retrieve features from the spatial file for comparison.

• a. If you are looking for points or lines, use gdlFindNearest with gdlFindNext.• b. If you want to make comparisons with polygons, use gdlFindPolygonOverlap with gdlFindNextPolygonOverlap to determine if polygons overlap or use gdlFindPolygonOverlapPercentage with gdlFindNextPolygonOverlapPercentage to determine percent overlap information.

7 Release resources associated with the shapes you have received using the gdlShapeFree function.



8 Close the spatial file by calling the gdlCloseSpatialFile function.

9 Release resources associated with the GeoStan handle using GsTerm.

10 Release resources associated with the gdlHandle by calling the gdlTerminate function.

Include Files for C Development

The C header file gdlapi.h contains all symbolic constants used or returned by the GDL functions, and should be included in every project.

Include Files for Visual Basic Development

The Visual Basic module gdlapi.bas contains the Visual Basic interface for the GDL functions. Geostan.inc contains all of the necessary constant definitions for GeoStan functions for use in Visual Basic development. Both files should be included in every project.

Include Files for COBOL Development on z/OS Systems

The COBOL copybook, GDLCOPY, contains the constants used or returned by the GDL procedures, and should be included in every project.

Samples

Refer to the sample code provided in the installation directory as follows:

\GDL\MS_c

\GDL\Vbasic

CHAPTER 6

COBOL Procedure

ReferenceThis chapter describes the general use of the COBOL calls to GDL and how to incorporate them into your application.

The naming convention for all of the GDL procedure calls from with GDL programs is GDLPROCEDURENAME. All GDL calls from COBOL use this naming convention.

NOTE: GDL constants are in the copy book GDLCOPY. They are the same as the C constants, but use a hyphen (-) rather than an underscore (_).

Data Types

Primitive data types

Data type Description

S9(9)BINARY 32-bit long integer

S9(4)BINARY 16-bit short integer

S9(9)BINARY Handle

X’00’ Used to "null-terminate" strings.

COBOL Procedure Reference


Quick Reference

Initialization ProceduresGDLINITInitializes the GDL Library. You must call this procedure before any other library procedure.GDLTERMReleases resources allocated from GDLINIT.

File Operation ProceduresGDLOSFOpens a file for spatial analysis.GDLCSFCloses the file previously opened by GDLOSF.GDLGTVERReturns a string containing the GDL library version number.

GDL/zOS-Specific ProceduresGDLCSTReturns the confidence surface type based on information from a GeoStan™ match.GDLGESGenerates an error surface (geo-variance region) from a match found inside the GeoStan/zOS

handle. GDLGSLDetermines the street segment length or the length of a diagonal.GDLSSSets properties of the gdlHandle.

Comparison Operation ProceduresGDLFNFinds the nearest point or line to a given point. GDLFNXFinds the next nearest feature after a successful call to GDLFN.GDLFPODetermines if a binary polygon overlap has occurred and, if so, returns the polygon that is in

overlap with the input polygon.GDLFNPODetermines if another binary polygon overlap has occurred and, if so, returns the polygon that is

in overlap with the input polygon.GDLFPOPDetermines if a percentage polygon overlap has occurred and, if so, returns the polygon and the

percentage overlap with the input polygon.



GDLFNPOPDetermines if another percentage polygon overlap has occurred returning the polygon and the

percentage overlap with the input polygon. GDLPIPFinds the first polygon that contains the input point and determines within which polygon a

geocoded address is located. GDLPIPNFinds the next polygon that contains the input point.GDLNDDetermines the minimum distance that exists between an error surface or a geocoded point and

another point or line.GDLFDDetermines the distance between the farthest point of the error surface and the nearest point of the

feature (point, line or polygon).GDLMDDetermines the Manhattan distance between two points.GDLDISTDetermines the straight line distance between two points.

Shape Operation ProceduresGDLSGLReturns properties from the shape object in the form of a long integer.GDLSGSReturns properties from the shape object in the form of a string.GDLSCCreates a shape of a given type with specified coordinates.GDLSGCReturns the coordinates with which a shape of a given type is created.GDLSFDeallocates any memory associated with a shape.



GDLCSFCLOSES THE FILE PREVIOUSLY OPENED BY GDLOSF.

Syntax05 GDL-CLOSE-SPATIAL-FILE.10 GDL-CSF-SPATIAL-HANDLEPIC S9(09) BINARY.* CALL “GDLCSF” USING GDL-CLOSE-SPATIAL-FILEGDL-RETURN-CODE.

Arguments

GDL-CSF-SPATIAL-HANDLEA pointer to the gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Output.

Return Values

Prerequisites

GDLOSF

Alternates

None.

Notes

Must be called upon completion of use of the spatial file prior to calling GDLTERM.

GDL-OK Success



GDLCSTRETURNS THE CONFIDENCE SURFACE TYPE BASED ON INFORMATION FROM A GEOSTAN MATCH.

SyntaxFrom copy book GDLCOPY:

05 GDL-CONFIDENCE-SURFACE-TYPE. 10 GDL-CST-HANDLE PIC S9(09) BINARY. 10 GDL-CST-CONF-SUR-TYPE PIC S9(09) BINARY. 88 GDL-SURF-UNDEFINED VALUE 0. 88 GDL-SURF-ERROR VALUE 1. 88 GDL-SURF-INTERSECTION VALUE 2. 88 GDL-SURF-ADDRESS VALUE 3. 88 GDL-SURF-POINT VALUE 4. 88 GDL-SURF-AREA1 VALUE 5. 88 GDL-SURF-AREA2 VALUE 6. 88 GDL-SURF-AREA3 VALUE 7. 88 GDL-SURF-AREA4 VALUE 8. 88 GDL-SURF-POSTAL1 VALUE 9. 88 GDL-SURF-POSTAL2 VALUE 10. 88 GDL-SURF-POSTAL3 VALUE 11. 88 GDL-SURF-POSTAL4 VALUE 12. 10 GDL-RETURN-CODE PIC S9(09) BINARY.* MOVE GDL-INIT-HANDLE TO GDL-CST-HANDLE.CALL “GDLCST”USING GDL-CONFIDENCE-SURFACE-TYPE,GDL-RETURN-CODE

Arguments

GDL-CONFIDENCE-SURFACE-TYPEIdentifies the gdlHandle. Input.

GDL-RETURN-CODEType of confidence surface. Output.

Type options:


GDL-SURF-UNDEFINED 0 Nothing has been searched yet.

GDL-SURF-ERROR 1 The search failed - address was not found.

GDL-SURF-INTERSECTION 2 Intersection confidence-surface generated.

GDL-SURF-ADDRESS 3 Address error-surface generated.

GDL-SURF-POINT 4 Point level match.

GDL-SURF-AREA1 5 State confidence-surface generated.

GDL-SURF-AREA2 6 County confidence-surface generated.

GDL-SURF-AREA3 7 City confidence-surface generated.

GDL-SURF-AREA4 8 Not used in USA.

GDL-SURF-POSTAL1 9 A Zip confidence -surface generated.



Return Values

PrerequisitesGDLINITGDLGES

Alternates

None.

Notes

The error (or confidence) surface type indicates the type of location that the surface encloses.

The enum definition, GDLGES, defines the full set of possible surface types that can be generated.

In general, the better the location code from GeoStan, the higher quality the surface type.

GDL-SURF-POSTAL2 10 A Zip + 2 confidence -surface generated.

GDL-SURF-POSTAL3 11 A Zip + 4 confidence -surface generated

GDL-SURF-POSTAL4 12 Not used in USA.

GDL-OK Success

GDL-NOT-LICENSED




GDLDISTDETERMINES THE STRAIGHT LINE DISTANCE BETWEEN TWO POINTS.

Syntax05 GDL-DISTANCE. 10 GDL-DIST-HANDLE PIC S9(09) BINARY.10 GDL-DIST-POINT1 PIC S9(09) BINARY.10 GDL-DIST-POINT2 PIC S9(09) BINARY.10 GDL-DIST-DISTANCE PIC S9(09) BINARY.* CALL “GDLDIST”USING GDL-DISTANCEGDL-RETURN-CODE.

Arguments

GDL-DIST-HANDLEThe gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-DIST-POINT1Pointer to a gdlShape that contains the geocode coordinates representing the first point. Input.

GDL-DIST-POINT2Pointer to a gdlShape that contains the geocode coordinates representing the second point. Input.

GDL-DIST-DISTANCEThe distance in feet. Output.

Return Values

Prerequisites

GDLINIT

Alternates

GDLMD - Use to determine the Manhattan distance instead of the straight line distance.

Notes

The following diagram illustrates the straight line distance between two points:

GDL-OK Success

GDL-ERROR An internal error occurred

GDL-WRONG-TYPE Occurs if the value of GDL_DIST_POINTX is not a point.



GDLFDDETERMINES THE DISTANCE BETWEEN THE FARTHEST POINT OF THE ERROR SURFACE AND THE NEAREST POINT OF THE FEATURE (POINT, LINE, OR POLYGON).

Syntax05 GDL-FAR-DISTANCE.10 GDL-FD-HANDLE PIC S9(09) BINARY.10 GDL-FD-SHAPE1 PIC S9(09) BINARY.10 GDL-FD-SHAPE2 PIC S9(09) BINARY.10 GDL-FD-DISTANCE PIC S9(09) BINARY.* CALL “GDLFD”USING GDL-FAR-DISTANCEGDL-RETURN-CODE.

Arguments

GDL-FD-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-FD-SHAPE1 The first shape. GDL-GES-SURFACE from GDLGES Input.

GDL-FD-SHAPE2 The second shape. Input.

GDL-FD-DISTANCE The distance in feet. Output.

Return Values

Prerequisites

GDLINIT

Alternates

GDLND - Use to determine the minimum distance between an error surface and any other feature.

Notes

The following diagram illustrates the distance between the farthest point of the error surface and the nearest point of a line:

GDL-OK Success

GDL-ERROR GDL-FD-SHAPEX is not a valid object



Far Distance

Feature

1168 ft

Polygon

Error Surface



GDLFNFINDS THE NEAREST POINT OR LINE WITHIN A SPATIAL FILE TO A GIVEN POINT.

Syntax05 GDL-FIND-NEAREST.10 GDL-FN-HANDLE PIC S9(09) BINARY.10 GDL-FN-INPUT-SHAPE PIC S9(09) BINARY.10 GDL-FN-OUTPUT-SHAPE PIC S9(09) BINARY.10 GDL-FN-TYPE PIC S9(09) BINARY.10 GDL-FN-MAX PIC S9(09) BINARY.* CALL “GDLFN” USING GSL-FIND-NEARESTGDL-RETURN-CODE.

Arguments

GDL-FN-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-STATIAL-HANDLE). Input.

GDL-FN-INPUT-SHAPEThe point to use as input. Input.

GDL-FN-OUTPUT-SHAPEA pointer to the nearest shape. Output.

GDL-FN-TYPEThe type of shape to find. Input.

Type options:

GDL-FN-MAX The maximum to search in feet. Input.

Return Values

Prerequisites

GDLOSF

Alternates

None.

COBOL Shape Types

GDL-POINT

GDL-LINE

GDL-OK Success

GDL-ERROR The file is not open or GDLOSF has not been called\

GDL-NOT-FOUND No shape of the desired type is within GDL-FN-MAX of GDL-FN-INPUT-SHAPE

GDL-WRONG-TYPE GDL-FN-INPUT-SHAPE is not a point or GDL-FN-TYPE is not GDL-POINT or GDL-LINE



Notes

Features are returned from nearest to farthest.

Following instances of this procedure, you should call GDLSF with the output shape when you are finished using the output shape to release system resources.

The following diagrams illustrate the nearest point and line to a given point:

��



GDLFNPODETERMINES IF ANOTHER BINARY POLYGON OVERLAP HAS OCCURRED AND, IF SO, RETURNS THE POLYGON THAT IS IN OVERLAP WITH THE INPUT POLYGON.

Syntax05 GDL-FIND-NEXT-POLYGON-OVERLAP. 10 GDL-FNPO-HANDLE PIC S9(09) BINARY.10 GDL-FNPO-OUTPUT-SHAPE PIC S9(09) BINARY.* CALL “GDLFNPO”USING GDL-FIND-NEXT-POLYGON-OVERLAPGDL-RETURN-CODE.

Arguments

GDL-FNPO-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-STATIAL-HANDLE). Input.

GDL-FNPO-OUTPUT-SHAPE A pointer to the overlapping polygon. Output.

Return Values

Prerequisites

GDLFPO

Alternates

GDLFNPOP - If percentage overlap is required.

Notes

Following instances of this procedure, you should call GDLSF with the output polygon when you are finished using the output polygon to release system resources.

GDL-OK Success


GDL-NOT-FOUND No further returns are available



GDLFNPOPDETERMINES IF ANOTHER PERCENTAGE POLYGON OVERLAP HAS OCCURRED, RETURNING THE POLYGON AND THE PERCENTAGE OVERLAP WITH THE INPUT POLYGON.

Syntax05 GDL-FIND-NEXT-POLYGON-OVR-PCT.10 GDL-FNPOP-HANDLE PIC S9(09) BINARY.10 GDL-FNPOP-OUTPUT-SHAPE PIC S9(09) BINARY.10 GDL-FNPOP-OVERLAP COMP-2.* CALL “GDLFNPOP”USING GDL-FIND-NEXT-POLYGON-OVR-PCTGDL-RETURN-CODE.

Arguments

GDL-FNPOP-HANDLE The gdlFileHandle returned by GDLSOF (GDL-OSF-STATIAL-HANDLE). Input.

GDL-FNPOP-OUTPUT-SHAPEA pointer to the overlapping polygon. Output.

GDL-FNPOP-OVERLAP The percentage of overlap. Output.

Return Values

Prerequisites

GDLFPOP

Alternates

GDLFNPO – For better performance when percent overlap is not needed

Notes


Following instances of this procedure, you should call GDLSF with the output polygon when you are finished using the output polygon to release system resources.

GDL-OK Success





GDLFNXFINDS THE NEXT NEAREST FEATURE; CALLED AFTER SUCCESSFUL GDLFN.

Syntax05 GDL-FIND-NEXT.10 GDL-FNX-HANDLE PIC S9(09) BINARY.10 GDL-FNX-OUTPUT-SHAPE PIC S9(09) BINARY.10 GDL-FNX-TYPE-SHAPE PIC S9(09) BINARY.* CALL “GDLFNX” USING GDL-FIND-NEXTGDL-RETURN-CODE.

Arguments

GDL-FNX-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Input.

GDL-FNX-OUTPUT-SHAPEA pointer to the next nearest shape. Output.

GDL-FNX-TYPE-SHAPEThe type of shape to find. Input.Type options:

Return Values

Prerequisites

GDLFN

Alternates

None.

Notes

Following instances of this procedure, you should call GDLSF with the output shape (GDL-FNX-OUTPUT-SHAPE) when you are finished using the output shape to release system resources.

COBOL Shape Types

GDL-POINT

GDL-LINE

GDL-OK Success


GDL-NOT-FOUND No more features were found

GDL-WRONG-TYPE GDL-FNX-TYPE-SHAPE is not GDL-POINT or GDL-LINE



GDLFPODETERMINES IF A BINARY POLYGON OVERLAP HAS OCCURRED BETWEEN AN INPUT POLYGON AND POLYGON OBJECTS IN A SPATIAL FILE AND, IF SO, RETURNS THE POLYGON THAT IS IN OVERLAP WITH THE INPUT POLYGON.

Syntax05 GDL-FIND-POLYGON-OVERLAP.10 GDL-FPO-HANDLE PIC S9(09) BINARY.10 GDL-FPO-POLYGON PIC S9(09) BINARY.10 GDL-FPO-OUTPUT-SHAPE PIC S9(09) BINARY.* CALL “GDLFPO”USING GDL-FIND-POLYGON-OVERLAP,GDL-RETURN-CODE.

Arguments

GDL-FPO-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Input.

GDL-FPO-POLYGON The polygon with which to determine overlap (GDL-GES-SURFACE). Input

GDL-FPO-OUTPUT-SHAPEA pointer to the overlapping polygon. Output.

Return Values

Prerequisites

GDLOSF

Alternates

GDLFPOP - If percentage overlap is required.

Notes

Following instances of this procedure, you should call GDLSF with the output polygon (GDL-FPO-OUTPUT-SHAPE) when you are finished using the output polygon to release system resources.

The following diagram illustrates a polygon that is in overlap with an input polygon:

GDL-OK Success



GDL-WRONG-TYP GDL-FPOP-POLYGON is not a polygon



GDLFPOPDETERMINES IF A PERCENTAGE POLYGON OVERLAP HAS OCCURRED BETWEEN AN INPUT POLYGON AND POLYGON OBJECTS IN A SPATIAL FILE AND, IF SO, RETURNS THE POLYGON AND THE PERCENTAGE OVERLAP WITH THE INPUT POLYGON.

Syntax05 GDL-FIND-POLYGON-OVERLAP-PCT.10 GDL-FPOP-HANDLE PIC S9(09) BINARY.10 GDL-FPOP-POLYGON PIC S9(09) BINARY.10 GDL-FPOP-OUTPUT-SHAPE PIC S9(09) BINARY.10 GDL-FPOP-OVERLAP COMP-2.* CALL “GDLFPOP” USING GDL-FIND-POLYGON-OVERLAP-PCT,GDL-RETURN-CODE.

Arguments

GDL-FPOP-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Input.

GDL-FPOP-POLYGON The polygon with which to determine overlap (GDL-GES-SURFACE). Input.

GDL-FPOP-OUTPUT-SHAPEA pointer to the overlapping polygon. Output.

GDL-FPOP-OVERLAP The percentage of overlap. Output.

Return Values

Prerequisites

GDLOSF

Alternates

GDLFPO – For better performance when percent overlap is not needed

Notes

Following instances of this procedure, you should call GDLSF with the output polygon ( GDL-FPOP-OUTPUT-SHAPE) when you are finished using the output polygon to release system resources.


The following diagram illustrates a polygon and the percentage overlap with an input polygon:

GDL-OK Success

GDL-ERROR Unknown internal error occurred or GDL-FPOP-HANDLE was not properly opened by GDLOSF

GDL-NOT-FOUND No overlapping object is found

GDL-WRONG-TYPE GDL-FPOP-POLYGON is not a polygon



GDLGESGENERATES AN ERROR SURFACE FROM A MATCH FOUND INSIDE THE GEOSTAN/ZOS HANDLE.

Syntax05 GDL-GENERATE-ERROR-SURFACE.10 GDL-GES-HANDLE PIC S9(09) BINARY.10 GDL-GES-GEOSTAN PIC S9(09) BINARY.10 GDL-GES-DISTANCE PIC S9(09) BINARY.10 GDL-GES-POINT PIC S9(09) BINARY.10 GDL-GES-SURFACE PIC S9(09) BINARY.* CALL “GDLGES” USING GDL-GENERATE-ERROR-SURFACE,GDL-RETURN-CODE.

Arguments

GDL-GES-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-GES-GEOSTAN The GsId from the GeoStan/zOS library. This handle must contain a valid GeoStan/zOS match. Input.

GDL-GES-DISTANCE The distance, in feet, to buffer Address Level and ZIP+4 Level matches. Input.

GDL-GES-POINT Pointer to a gdlShape that contains the geocode coordinates. Output.

GDL-GES-SURFACE Pointer to a gdlShape that contains the error surface coordinates. Output.

Return Values

Prerequisites

GDLSS and GSFIND (from GeoStan)

Alternates

None.

GDL-OK Success


GDL-NO-ADDRESSMATCH-FOUND

GeoStan was not used to find a location prior to calling this function

GDL-ZIP5-FILE-ERROR The ZIP5 file is not set or points to an invalid location

GDL-ZIP9-FILE-ERROR The ZIP9 file is not set or points to an invalid location



Notes

After a call to GDLGES, the internal data geocode buffers maintained by the GeoStan/zOS handle are set to NULLs. Because of this, the GeoStan/zOS handle is always invalidated after a call to GDLGES.

Following instances of point or surface arguments of this procedure, you should call GDLSF with the output shape (point and surface) when you are finished using the output shape to release system resources.

The GDLGES procedure provides a worst-case scenario for address location. The geocode error surface (geo-variance region) provides the smallest possible surface that an address can be determined. The GDL/zOS generates the geocode error surfaces. Based on the GeoStan/zOS Match Code, a buffer is built around a given street segment, ZIP+4, or ZIP+2 that indicates a geo-variance surface that contains the location.

Match Code Geo-Variance (Error) Surface

Address Level Buffer street segment

Intersection Match Circular buffer that represents 2X the buffer distance

ZIP+4 Buffer all street segments in ZIP+4

ZIP+2 Convex Hull around all ZIP+4s that make up a ZIP+2

ZIP Code The ZIP Code boundary



GDLGSLDETERMINES THE STREET SEGMENT LENGTH OR THE LENGTH OF A DIAGONAL.

Syntax05 GDL-GET-STREET-LENGTH.10 GDL-GSL-GEOSTAN PIC S9(09) BINARY.10 GDL-GSL-POINT PIC S9(09) BINARY.10 GDL-GSL-LENGTH PIC S9(09) BINARY.* CALL “GDLGSL” USING GDL-GET-STREET-LENGTH, GDL-RETURN-CODE.

Arguments

GDL-GSL-GEOSTAN The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-GSL-POINT Pointer to a gdlShape that contains the geocode coordinates. Output.

GDL-GSL-LENGTH The length of the street segment, or the length of the MBR diagonal. Output.

Return Values

Prerequisites

GDLINIT, GSFIND (from GeoStan)

Alternates

None.

Notes

Given a GeoStan/zOS handle, we can determine the street segment length for address level geocodes. The street length values can be used to make a fast determination of complete polygon inclusion when used in conjunction with the GDLPIP and GDLND procedures.

A GeoStan/zOS handle remains valid after calling GDLGSL.

Following instances of point arguments of this procedure, you should call GDLSF with the output point when you are finished using the output point to release system resources.

GDL-OK Success

GDL-ERROR An internal error occurred or GeoStan was not used to find an address prior to this call



GDLGTVERRETURNS A STRING CONTAINING THE GDL LIBRARY VERSION NUMBER.

Syntax05 GDL-GET-VERSION. 10 GDL-GV-VERSION PIC X(20).*CALL “GDLGTVER”USING GDL-GET-VERSION,GDL-RETURN-CODE.

Arguments

GDL-GV-VERSION The version string. Output.

Return Values

Prerequisites

None.

Alternates

None.

Notes

The string returned is in the following format:GDL/390 v#.#

For example, GDL/390 v.2.9.

GDL-OK Success



GDLINITINITIALIZES THE GEOGRAPHIC DETERMINATION LIBRARY/ZOS; MUST BE CALLED BEFORE ANY OTHER LIBRARY PROCEDURE.

Syntax05 GDL-INITIALIZE.10 GDL-INIT-HANDLE PIC S9(09) BINARY.10 FILLER PIC S9(09) BINARY.10 FILLER PIC X(08).* CALL “GDLINIT”USING GDL-INITIALIZE,GDL-RETURN-CODE.

Arguments

GDL-INIT-HANDLE Pointer to a gdlHandle. Output.

GDL-INIT-NUMBER Unused.

GDL-INIT-LICENSE-DDNAME Unused.

NOTE: z/OS users, fill with low-values.

Return Values

Prerequisites

None.

Alternates

None.

Notes

This should be the first procedure called. Call GDLTERM when finished with gdlHandle.

GDL-OK Success



GDLMDDETERMINES THE MANHATTAN DISTANCE BETWEEN A POINT AND ANOTHER POINT.

Syntax05 GDL-MANHATTAN-DISTANCE. 10 GDL-MD-HANDLE PIC S9(09) BINARY.10 GDL-MD-POINT1 PIC S9(09) BINARY.10 GDL-MD-POINT2 PIC S9(09) BINARY.10 GDL-MD-DISTANCE PIC S9(09) BINARY.* CALL “GDLMD” USING GDL-MANHATTAN-DISTANCE,GLD-RETURN-CODE.

Arguments

GDL-MD-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-MD-POINT1 Pointer to a gdlShape that contains the geocode coordinates representing the first point. Input.

GDL-MD-POINT2 Pointer to a gdlShape that contains the geocode coordinates representing the second point. Input.

GDL-MD-DISTANCE The distance in feet. Output.

Return Values

Prerequisites

GDLINIT

Alternates

GDLDIST - Used to determine the straight line distance instead of the Manhattan distance.

GDLND - Used to determine the nearest distance between an error surface and any other feature.

GDLFD - Used to determine the farthest distance between an error surface and any other feature.

GDL-OK Success


GDL-WRONG-TYPE GDL-MD-POINTX are not points



Notes

The following diagram illustrates the Manhattan distance between two points:



GDLNDDETERMINES THE MINIMUM DISTANCE THAT EXISTS BETWEEN AN ERROR SURFACE AND ANY OTHER FEATURE: POINT, LINE, OR POLYGON.

Syntax05 GDL-NEAR-DISTANCE.10 GDL-ND-HANDLE PIC S9(09) BINARY.10 GDL-ND-SHAPE1 PIC S9(09) BINARY.10 GDL-ND-SHAPE2 PIC S9(09) BINARY.10 GDL-ND-DISTANCE PIC S9(09) BINARY.* CALL “GDLND” USING GDL-NEAR-DISTANCE, GDL-RETURN-CODE.

Arguments

GDL-ND-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-ND-SHAPE1 The first shape. Input.

GDL-ND-SHAPE2 The second shape. Input.

GDL-ND-DISTANCE The distance in feet. Output.

Return Values

Prerequisites

GDLINIT

Alternates

None.

Notes

The following diagram illustrates the minimum distance that exists between an error surface and a line:

GDL-OK Success




Near Distance

Feature

682 ftPolygon

Error Surface



GDLOSFOPENS A FILE FOR SPATIAL ANALYSIS.

Syntax05 GDL-OPEN-SPATIAL-FILE.10 GDL-OSF-GDL PIC S9(09) BINARY.10 GDL-OSF-SPATIAL-HANDLE PIC S9(09) BINARY.10 GDL-OSF-SPATIAL-DDNAME PIC X(08).* CALL “GDLOSF” USING GSL-OPEN-SPATIAL-FILE,GDL-RETURN-CODE.

Arguments

GDL-OSF-GDL The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE. Input.

GDL-OSF-SPATIAL-HANDLE A pointer to a gdlFileHandle. Output.

GDL-OSF-SPATIAL-DDNAME The DD name of the spatial file to open. Input.

Return Values

Prerequisites

GDLINIT

Alternates

None.

Notes

Call GDLCSF when finished with gdlHandle.

GDL-OK Success


GDL-NOT-FOUND Spatial files could not be found



GDLPIPFINDS THE FIRST POLYGON THAT CONTAINS THE INPUT POINT.

Syntax05 GDL-POINT-IN-POLYGON.10 GDL-PIP-HANDLE PIC S9(09) BINARY.10 GDL-PIP-POINT PIC S9(09) BINARY.10 GDL-PIP-POLYGON PIC S9(09) BINARY.* CALL “GDLPIP”USING GDL-POINT-IN-POLYGON,GDL-RETURN-CODE.

Arguments

GDL-PIP-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Input.

GDL-PIP-POINT Pointer to a gdlShape that contains the geocode coordinates. Input.

GDL-PIP-POLYGON A pointer to the first polygon. Output.

Return Values

Prerequisites

GDLOSF

Alternates

None.

Notes

Call GDLSF on the output polygon.

The following diagram illustrates the first polygon that contains the input point:

GDL-OK Success


GDL-NOT-FOUND No enclosing regions were found

GDL-WRONG-TYPE GDL-PIP-POINT is not a Point



GDLPIPNFINDS THE NEXT POLYGON THAT CONTAINS THE INPUT POINT.

Syntax05 GDL-POINT-IN-POLYGON-NEXT.10 GDL-PIPN-HANDLE PIC S9(09) BINARY.10 GDL-PIPN-POLYGON PIC S9(09) BINARY.* CALL “GDLPIPN” USING GDL-POINT-IN-POLYGON-NEXT,GDL-RETURN-CODE.

Arguments

GDL-PIPN-HANDLE The gdlFileHandle returned by GDLOSF (GDL-OSF-SPATIAL-HANDLE). Input.

GDL-PIPN-POLYGON A pointer to the next polygon. Output.

Return Values

Prerequisites

GDLPIP

Alternates

None.

Notes

Call GDLSF on output polygon.

GDL-OK Success


GDL-NOT-FOUND No more enclosing objects were found



GDLSCCREATES A SHAPE OF A GIVEN TYPE WITH SPECIFIED COORDINATES.

Syntax05 GDL-SHAPE-CREATE.10 GDL-SC-HANDLE PIC S9(09) BINARY.10 GDL-SC-SHAPE PIC S9(09) BINARY.10 GDL-SC-NAME PIC X(80).10 GDL-SC-TYPE PIC S9(09) BINARY.10 GDL-SC-X-POINT COMP-2.10 GDL-SC-Y-POINT COMP-2.10 GDL-SC-POINTS-PER-PART PIC S9(09) BINARY.10 GDL-SC-PART-COUNT PIC S9(09) BINARY.* CALL “GDLSC”USING GDL-SHAPE-CREATE,GDL-RETURN-CODE.

ArgumentsGDL-SC-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE).

Input.

GDL-SC-SHAPE A pointer to the new gdlShape object. Output.

GDL-SC-NAME The name of the object being created. Input.

GDL-SC-TYPE The type of shape to create. Input.

Type options.

GDL-SC-X-POINT An array of x coordinates in decimal degrees. Input.

GDL-SC-Y-POINT An array of y coordinates in decimal degrees. Input.

GDL-SC-POINTS-PER-PART An array of integers indicating the number of points in each part. Input.

GDL-SC-PART-COUNT The number of parts. Input.

GDL-POINT

GDL-LINE

GDL-POLYGON



Return Values

Prerequisites

GDLINIT

Alternates

None.

Notes

Following instances of this procedure, you should call GDLSF with the output shape when you are finished using the output shape to release system resources.

GDL-OK Success


GDL-WRONG-TYPE Type setting is not one of the allowed values or the type is inconsistent



GDLSFDEALLOCATES ANY MEMORY ASSOCIATED WITH A SHAPE.

Syntax05 GDL-SHAPE-FREE.10 GDL-SF-SHAPE PIC S9(09) BINARY.* CALL “GDLSF” USING GDL-SHAPE-FREE,GDL-RETURN-CODE.

Arguments

GDL-SF-SHAPE The shape needing destruction. Input.

Return Values

Prerequisites

GDLGES, GDLFN, GDLFNX, GDLFPO, GDLFNPO, GDLFPOP, GDLFNPOP, GDLPIP, GDLPIPN, GDLSC

Alternates

None.

Notes

Failure to call GDLSF after those procedure calls may result in a cumulative loss of memory resources.

GDL-OK Success



GDLSGCRETURNS THE COORDINATES WITH WHICH A SHAPE OF A GIVEN TYPE IS CREATED.

Syntax05 GDL-SHAPE-GET-COORDS.10 GDL-SGC-HANDLE PIC S9(09) BINARY.10 GDL-SGC-SHAPE PIC S9(09) BINARY.10 GDL-SGC-TYPE PIC S9(09) BINARY.10 GDL-SGC-X-POINT COMP-2.10 GDL-SGC-Y-POINT COMP-2.10 GDL-SGC-POINTS-PER-PART PIC S9(09) BINARY.10 GDL-SGC-PART-COUNT PIC S9(09) BINARY.10 GDL-SGC-MAX-POINTS PIC S9(09) BINARY.10 GDL-SGC-MAX-PARTS PIC S9(09) BINARY.* CALL “GDLSGC” USING GDL-SHAPE-GET-COORDS,GDL-RETURN-CODE.

Arguments

GDL-SGC-HANDLEThe gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-SGC-SHAPEThe shape from which to get coordinates. Input.

GDL-SGC-TYPEThe type of shape being examined. Output.

Constants:

GDL-SGC-X-POINTAn array of x coordinates in decimal degrees. Output.

GDL-SGC-Y-POINTAn array of y coordinates in decimal degrees. Output.

GDL-SGC-POINTS-PER-PARTAn array of long integers indicating the number of points in each part. Output.

GDL-SGC-PART-COUNTThe number of parts. Output.

GDL-SGC-MAX-POINTSThe maximum number of points that fit into the x and y arrays above. Input.

GDL-SGC-MAX-PARTSThe maximum number of parts that fit into the pointsPerPart array above. Input.

GDL-POINT

GDL-LINE

GDL-POLYGON



Return Values

Prerequisites

None.

Alternates

None.

GDL-OK Success




GDLSGLRETURNS PROPERTIES FROM THE SHAPE OBJECT IN THE FORM OF A LONG INTEGER.

Syntax05 GDL-SHAPE-GET-LONG.10 GDL-SGL-SHAPE PIC S9(09) BINARY.10 GDL-SGL-TYPE PIC S9(09) BINARY.10 GDL-SGL-VALUE PIC S9(09) BINARY.* CALL “GDLSGL”USING GDL-SHAPE-GET-LONG,GDL-RETURN-CODE.

Arguments

GDL-SGL-SHAPE The GDL/zOS shape. Input.

GDL-SGL-TYPE The type of shape variable to return. Input.

Constants:

GDL-SGL-VALUE A pointer to the value. Output.

Return Values

Prerequisites

None.

Alternates

None.

GDL-TYPE The type of shape

GDL-PART-COUNT The number of parts the shape has

GDL-POINT-COUNT The total number of points

GDL-OK Success




GDLSGSRETURNS PROPERTIES FROM THE SHAPE OBJECT IN THE FORM OF A STRING.

Syntax05 GDL-SHAPE-GET-STR.10 GDL-SGS-SHAPE PIC S9(09) BINARY.10 GDL-SGS-TYPE PIC S9(09) BINARY.10 GDL-SGS-VALUE PIC X(80).10 GDL-SGS-MAXSIZE PIC S9(09) BINARY.* CALL “GDLSGS” USING GDL-SHAPE-GET-STR,GDL-RETURN-CODE.

Arguments

GDL-SGS-SHAPE The GDL/zOS shape. Input.

GDL-SGS-TYPE The type of variable to return. Input.

Constants:

GDL-SGS-VALUE An alphanumeric value in which to place the property value. Output.

GDL-SGS-MAXSIZE The size of the character array in value. Input.

Return Values

Prerequisites

None.

Alternates

None.

GDLSSALLOWS THE USER TO SET THE PROPERTIES OF THE GDLHANDLE.

Syntax05 GDL-SET-STR.10 GDL-SS-HANDLE PIC S9(09) BINARY.

GDL-NAME The name of the object

GDL-NAME2 The secondary name of the ob-ject

GDL-OK Success




10 GDL-SS-TYPE PIC S9(09) BINARY.10 GDL-SS-DDNAME PIC X(08).* CALL “GDLSS” USING GDL-SET-STR,GDL-RETURN-CODE.

Arguments

GDL-SS-HANDLE The gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Input.

GDL-SS-TYPE The type of shape to find. Input.

GDL-SS-DDNAME An array of characters from which to read the property value. Input.

size The size of the character array in value. Input.

Return Values

Prerequisites

GDLINIT

Alternates

None.

Notes

The argument GDL-TEMP-PATHNAME is ignored on MVS.

GDL-ZIP5-FILENAME Name of the gsb file that contains the ZIP Code boundaries.

GDL-ZIP9-FILENAME Name of the US.Z9 file of ZIP Code centroids.

GDL-GEOSTAN-PATH Direct GDL to return data in the datum specified in GeoStan. GDL performs datum conversions on the address- and ZIP4-level error surfaces created with GDLGES.This value should be the same as the value used to initialize GeoStan. If this path is not set, GDL returns data in the NAD83 datum.

GDL-OK Success

GDL-NOT-FOUND Did not find a type (GDL-SS-TYPE)



GDLTERMRELEASES RESOURCES ALLOCATED FROM GDLINITIALIZE.

Syntax05 GDL-TERMINATE. 10 GDL-TERM-HANDLE PIC S9(09) BINARY.* CALL “GDLTERM”USING GDL-TERMINATE,GDL-RETURN-CODE.

Argument

GDL-TERM-HANDLE A pointer to the gdlHandle initialized by GDLINIT (GDL-INIT-HANDLE). Output.

char* License filename. Input.

Return Values

Prerequisites

GDLINIT

Alternates

None.

Notes

This procedure must be the last procedure called from the library.

GDL-OK Success

APPENDIX A

Summary of Return and Input

ValuesThe following are to be assigned by definition.

NOTE: z/OS users, GDL constants are in the copy book GDLCOPY. They are the same as the C constants, but use “-” (hyphen) rather than “_” (underscore).

GDL Return Values

GDL Return Values Explanation

GDL_ERROR An error exists

GDL_FOUND Feature found

GDL_NO_ADDRESSMATCH_FOUND No address or ZIP5 data available

GDL_NOT_FOUND Feature not found

GDL_NOT_IMPLEMENTED Not implemented

GDL_NOT_LICENSED GDL is not licensed

GDL_OK Results are as expected

GDL_TEMP_PATH_ERROR Temp path was incorrect

GDL_WRONG_TYPE Wrong type passed


GDL_ZIP5_FILE_ERROR ZIP5 file was incorrect

GDL_ZIP9_FILE_ERROR ZIP9 file was incorrect

GDL Return Values Explanation


GDL File Types

GDL Shape Types

GDL Shape Variables

GDL Variables

GDL File Types Explanation

GDL_GSB Spatial+ file

GDL_BNA ESRI BNA file

GDL_MIF MID/MIF Interchange file

GDL_SHP ESRI shapefile

GDL_SDF MapGuide SDF file

GDL Shape Types Explanation

GDL_POINT Point

GDL_LINE Multi- or single-point line

GDL_POLYGON Multi- or single-point polygon

GDL Shape Variables Explanation

GDL_NAME Primary name of feature

GDL_NAME2 Secondary name of feature

GDL_TYPE Point, line or polygon

GDL_PART_COUNT Number of parts

GDL_POINT_COUNT Total number of points

GDL Variables Explanation

GDL_ZIP5_FILENAME Name of ZIP5 GSB file

GDL_ZIP9_FILENAME Name of US.Z9 file


Spatial Import

GDL allows you to use an import utility located in the \GDL\32bit (for 32-bit OS installation) or \GDL\64bit (for 64-bit OS installation) directory to retrieve attribute information. You must create a Spatial+ object (GSB) file and associated it with a GSA attribute file. These synchronized GSA and GSB files allow you to retrieve an unlimited amount of attribute information that is not currently available from the Name and Name2 fields. For instructions on using the import utility, see the Spatial+ Reference Manual.

GDL_TEMP_PATHNAME Temp path

GDL_GEOSTAN_PATH Direct GDL to return data in the datum specified in GeoStan™ using GsSetDatum. GDL performs datum conversions on the address- and ZIP4-level error surfaces created with gdlGenerateErrorSurface.This value should be the same as the value used to initialize GeoStan. If this path is not set, GDL returns data in the NAD83 datum.

GDL Variables Explanation

APPENDIX B

Formats Supported in GDL

These are the export formats available for geo-variance buffers. Imports are performed through Spatial+™.

NOTE: These formats are not supported on z/OS systems.

Autodesk Mapguide Format

Available for export.

ESRI BNA Format

The Geographic Determination Library, through the underlying tools of Spatial+, supports ESRI’s Atlas GIS BNA format (also referred to as the Atlas ASCII format). For a summary of how the Atlas format is supported by Spatial+, see Appendix A in the Spatial+ Reference Manual. For a more complete description of the format, please contact ESRI.

ESRI Shapefile Format



MapInfo® MIF/MID Format

The Geographic Determination Library, through the underlying tools of Spatial+, supports a subset of the MapInfo Data Interchange Format, also referred to as MIF/MID format. For a summary of that format as supported by GDL, see Appendix B in the Spatial+ Reference Manual. For a more complete description of the format, please contact MapInformation.

Spatial+ GSB Format


APPENDIX C

COBOL Copybook

GDLCOPY

* 01 GDL-INTERFACE-WS. 05 GDL-INITIALIZE. 10 GDL-INIT-HANDLE PIC S9(09) BINARY. 10 GDL-INIT-NUMBER PIC S9(09) BINARY. 10 GDL-INIT-LICENSE-DDNAME PIC X(08). 05 GDL-TERMINATE. 10 GDL-TERM-HANDLE PIC S9(09) BINARY. 05 GDL-GENERATE-ERROR-SURFACE. 10 GDL-GES-HANDLE PIC S9(09) BINARY. 10 GDL-GES-GEOSTAN PIC S9(09) BINARY. 10 GDL-GES-DISTANCE PIC S9(09) BINARY. 10 GDL-GES-POINT PIC S9(09) BINARY. 10 GDL-GES-SURFACE PIC S9(09) BINARY. 05 GDL-GET-STREET-LENGTH. 10 GDL-GSL-GEOSTAN PIC S9(09) BINARY. 10 GDL-GSL-POINT PIC S9(09) BINARY. 10 GDL-GSL-LENGTH PIC S9(09) BINARY. 05 GDL-OPEN-SPATIAL-FILE. 10 GDL-OSF-GDL PIC S9(09) BINARY. 10 GDL-OSF-SPATIAL-HANDLE PIC S9(09) BINARY. 10 GDL-OSF-SPATIAL-DDNAME PIC X(08).


05 GDL-CLOSE-SPATIAL-FILE. 10 GDL-CSF-SPATIAL-HANDLE PIC S9(09) BINARY. 05 GDL-FIND-NEAREST. 10 GDL-FN-HANDLE PIC S9(09) BINARY. 10 GDL-FN-INPUT-SHAPE PIC S9(09) BINARY. 10 GDL-FN-OUTPUT-SHAPE PIC S9(09) BINARY. 10 GDL-FN-TYPE PIC S9(09) BINARY. 10 GDL-FN-MAX PIC S9(09) BINARY. 05 GDL-FIND-NEXT. 10 GDL-FNX-HANDLE PIC S9(09) BINARY. 10 GDL-FNX-OUTPUT-SHAPE PIC S9(09) BINARY. 10 GDL-FNX-TYPE PIC S9(09) BINARY. 05 GDL-FIND-POLYGON-OVERLAP. 10 GDL-FPO-HANDLE PIC S9(09) BINARY. 10 GDL-FPO-POLYGON PIC S9(09) BINARY. 10 GDL-FPO-OUTPUT-SHAPE PIC S9(09) BINARY. 05 GDL-FIND-NEXT-POLYGON-OVERLAP. 10 GDL-FNPO-HANDLE PIC S9(09) BINARY. 10 GDL-FNPO-OUTPUT-SHAPE PIC S9(09) BINARY. 05 GDL-POINT-IN-POLYGON. 10 GDL-PIP-HANDLE PIC S9(09) BINARY. 10 GDL-PIP-POINT PIC S9(09) BINARY. 10 GDL-PIP-POLYGON PIC S9(09) BINARY. 05 GDL-POINT-IN-POLYGON-NEXT. 10 GDL-PIPN-HANDLE PIC S9(09) BINARY. 10 GDL-PIPN-POLYGON PIC S9(09) BINARY. 05 GDL-FIND-POLYGON-OVERLAP-PCT. 10 GDL-FPOP-HANDLE PIC S9(09) BINARY. 10 GDL-FPOP-POLYGON PIC S9(09) BINARY. 10 GDL-FPOP-OUTPUT-SHAPE PIC S9(09) BINARY. * 10 GDL-FPOP-OVERLAP PIC S9(3)V9(15) COMP-2. 10 GDL-FPOP-OVERLAP COMP-2. 05 GDL-FIND-NEXT-POLYGON-OVR-PCT. 10 GDL-FNPOP-HANDLE PIC S9(09) BINARY. 10 GDL-FNPOP-OUTPUT-SHAPE PIC S9(09) BINARY. * 10 GDL-FNPOP-OVERLAP PIC S9(3)V9(15) COMP-2. 10 GDL-FNPOP-OVERLAP COMP-2. 05 GDL-NEAR-DISTANCE. 10 GDL-ND-HANDLE PIC S9(09) BINARY. 10 GDL-ND-SHAPE1 PIC S9(09) BINARY. 10 GDL-ND-SHAPE2 PIC S9(09) BINARY. 10 GDL-ND-DISTANCE PIC S9(09) BINARY. 05 GDL-FAR-DISTANCE. 10 GDL-FD-HANDLE PIC S9(09) BINARY. 10 GDL-FD-SHAPE1 PIC S9(09) BINARY. 10 GDL-FD-SHAPE2 PIC S9(09) BINARY. 10 GDL-FD-DISTANCE PIC S9(09) BINARY. 05 GDL-MANHATTAN-DISTANCE. 10 GDL-MD-HANDLE PIC S9(09) BINARY. 10 GDL-MD-POINT1 PIC S9(09) BINARY. 10 GDL-MD-POINT2 PIC S9(09) BINARY. 10 GDL-MD-DISTANCE PIC S9(09) BINARY. 05 GDL-DISTANCE. 10 GDL-DIST-HANDLE PIC S9(09) BINARY. 10 GDL-DIST-POINT1 PIC S9(09) BINARY. 10 GDL-DIST-POINT2 PIC S9(09) BINARY. 10 GDL-DIST-DISTANCE PIC S9(09) BINARY. 05 GDL-SET-STR. 10 GDL-SS-HANDLE PIC S9(09) BINARY. 10 GDL-SS-TYPE PIC S9(09) BINARY.


10 GDL-SS-DDNAME PIC X(08). 05 GDL-SHAPE-GET-LONG. 10 GDL-SGL-SHAPE PIC S9(09) BINARY. 10 GDL-SGL-TYPE PIC S9(09) BINARY. 10 GDL-SGL-VALUE PIC S9(09) BINARY. 05 GDL-SHAPE-GET-STR. 10 GDL-SGS-SHAPE PIC S9(09) BINARY. 10 GDL-SGS-TYPE PIC S9(09) BINARY. 10 GDL-SGS-VALUE PIC X(80). 10 GDL-SGS-MAXSIZE PIC S9(09) BINARY. 05 GDL-SHAPE-CREATE. 10 GDL-SC-HANDLE PIC S9(09) BINARY. 10 GDL-SC-SHAPE PIC S9(09) BINARY. 10 GDL-SC-NAME PIC X(80). 10 GDL-SC-TYPE PIC S9(09) BINARY. 10 GDL-SC-TYPE PIC S9(09) BINARY. * 10 GDL-SC-X-POINT PIC S9(3)V9(15) COMP-2. 10 GDL-SC-X-POINT COMP-2. * 10 GDL-SC-Y-POINT PIC S9(3)V9(15) COMP-2. 10 GDL-SC-Y-POINT COMP-2. 10 GDL-SC-POINTS-PER-PART PIC S9(09) BINARY. 10 GDL-SC-PART-COUNT PIC S9(09) BINARY. 05 GDL-SHAPE-GET-COORDS. 10 GDL-SGC-HANDLE PIC S9(09) BINARY. 10 GDL-SGC-SHAPE PIC S9(09) BINARY. 10 GDL-SGC-TYPE PIC S9(09) BINARY. * 10 GDL-SGC-X-POINT PIC S9(3)V9(15) COMP-2. 10 GDL-SGC-X-POINT COMP-2. * 10 GDL-SGC-Y-POINT PIC S9(3)V9(15) COMP-2. 10 GDL-SGC-Y-POINT COMP-2. 10 GDL-SGC-POINTS-PER-PART PIC S9(09) BINARY. 10 GDL-SGC-PART-COUNT PIC S9(09) BINARY. 10 GDL-SGC-MAX-POINTS PIC S9(09) BINARY. 10 GDL-SGC-MAX-PARTS PIC S9(09) BINARY. 05 GDL-SHAPE-FREE. 10 GDL-SF-SHAPE PIC S9(09) BINARY. 01 GDL-CONSTANTS. 05 GDL-RETURN-CODE PIC S9(09) BINARY. 88 GDL-ERROR VALUE -1. 88 GDL-NOT-FOUND VALUE -2. 88 GDL-WRONG-TYPE VALUE -3. 88 GDL-NOT-IMPLEMENTED VALUE -4. 88 GDL-NOT-LICENSED VALUE -5. 88 GDL-ZIP5-FILE-ERROR VALUE -6. 88 GDL-ZIP7-FILE-ERROR VALUE -7. 88 GDL-ZIP9-FILE-ERROR VALUE -8. 88 GDL-TEMP-PATH-ERROR VALUE -9. 88 GDL-OK VALUE 1. 88 GDL-FOUND VALUE 2. 05 GDL-SHAPE-TYPE PIC S9(09) BINARY. 88 GDL-POINT VALUE 1. 88 GDL-LINE VALUE 2. 88 GDL-POLYGON VALUE 4. 05 GDL-SHAPE-VARIABLE PIC S9(09) BINARY. 88 GDL-NAME VALUE 1. 88 GDL-NAME2 VALUE 5. 88 GDL-TYPE VALUE 2. 88 GDL-PART-COUNT VALUE 3. 88 GDL-POINT-COUNT VALUE 4.


INDEX

A

address standardization library 5array 30, 32, 33Atlas ASCII format 99attribute information 98attributes 7Autodesk Mapguide format 99

B

basic functionspipObjectGetAttributeInfoByNumber 32

binary polygon overlap 19, 25, 26, 55, 66, 69BNA format from ESRI 48, 99boundary, ZIP Code 74buffer

pointer to 33size 33

bufferscircular 74data 74error 49geocode 74geo-variance 51set to NULL 74street segment 74

C

C functionsgdlCloseSpatialFile 20gdlDistance 21gdlFarDistance 22gdlFindNearest 23gdlFindNext 24gdlFindNextPolygonOverlap 25gdlFindNextPolygonOverlapPercentage 26gdlFindPolygonOverlap 26gdlFindPolygonOverlapPercentage 28gdlGetAttributeCount 30gdlGetAttributeInfoByName 31gdlGetAttributeInfoByNumber 32gdlGetAttributeNameByNumber 33gdlGetStreetLength 35gdlGetVersion 36gdlInitialize 37gdlManhattanDistance 37gdlNearDistance 38gdlOpenSpatialFile 39gdlPointInPolygon 40gdlPointInPolygonNext 41

gdlSetStr 42gdlShapeCreate 42gdlShapeFree 43gdlShapeGetCoords 44gdlShapeGetLong 45gdlShapeGetStr 46gdlSpatialConvert 47gdlTerminate 47gdlWriteShape 48GsCityDataGet 104pipObjectGetAttributeInfoByNumber 32

C header file 52circular buffer 74close spatial file 57COBOL procedures

GDLCSF 57GDLDIST 60GDLFD 62GDLFN 64GDLFNPO 66GDLFNPOP 67GDLFNX 68GDLFPO 69GDLFPOP 71GDLGES 73GDLGSL 75GDLGTVER 76GDLINIT 77GDLMD 78GDLND 80GDLOSF 82GDLPIP 83GDLPIPN 85GDLSC 86GDLSF 88GDLSGC 89GDLSGL 91GDLSGS 92GDLSS 92GDLTERM 94

comparison operation functionsgdlDistance 21gdlFarDistance 22gdlFindNearest 23gdlFindNext 24gdlFindNextPolygonOverlap 25gdlFindNextPolygonOverlapPercentage 26gdlFindPolygonOverlap 26gdlFindPolygonOverlapPercentage 28gdlManhattanDistance 37gdlNearDistance 38gdlPointInPolygon 40gdlPointInPolygonNext 41


comparison operation proceduresGDLDIST 60GDLFD 62GDLFN 64GDLFNPO 66GDLFNPOP 67GDLFNX 68GDLFPO 69GDLFPOP 71GDLMD 78GDLND 80GDLPIP 83GDLPIPN 85

comparison operationscomparison area 6functions 19linear distance 6near/far distance 51percentage overlap 6polygon overlap 51procedures 55shapes 12

compile errors 50confidence rating 9, 26, 28, 67, 71constants, symbolic 52conversion functions

gdlSpatialConvert 46convex hull 74coordinates 12

get 44, 89latitude/longitude 5

copybooks, GDLCOPY 101

D

databuffers 74formats 48structures 51types 17, 54types, 64-bit doubles 12

deallocate memory 20, 43, 56, 88define symbols 50determination process 11developing a GDL application 50diagonal length 35, 55, 75distance

accuracy 12Manhattan 37, 78minimum 38, 80value 9

doubles, 64-bit 12

E

errorbuffer 49compile 50

in calculations 12error surface

generating 73near distance 38, 80

ESRI formatsBNA 99Shapefile 99

F

file handle. See handlefile operation functions

gdlCloseSpatialFile 20gdlGetVersion 36gdlOpenSpatialFile 39gdlWriteShape 48

file operation proceduresGDLCSF 57GDLOSF 82

file types 97files

gdlapi.bas 53gdlapi.h 52

findfirst polygon 40, 83nearest object 23, 64next polygon 41, 85

flood zone 6flow, program 52formats, supported 99, 101functions

C See C functionscomparison operation 19conversion 20file operation 18format 17gdlCloseSpatialFile 20gdlDistance 21gdlFarDistance 22gdlFindNearest 23gdlFindNext 24gdlFindNextPolygonOverlap 25gdlFindNextPolygonOverlapPercentage 26gdlFindPolygonOverlap 26gdlFindPolygonOverlapPercentage 28gdlGetAttributeCount 30gdlGetAttributeInfoByName 31gdlGetAttributeInfoByNumber 32gdlGetAttributeNameByNumber 33gdlGetStreetLength 35gdlGetVersion 36gdlInitialize 37gdlManhattanDistance 37gdlNearDistance 38gdlOpenSpatialFile 39gdlPointInPolygon 40gdlPointInPolygonNext 41gdlSetStr 42


gdlShapeCreate 42gdlShapeFree 43gdlShapeGetCoords 44gdlShapeGetLong 45gdlShapeGetStr 46gdlSpatialConvert 47gdlTerminate 47gdlWriteShape 48initialization 18pipObjectGetAttributeInfoByNumber 32

G

GDL copybook 101GDL/zOS-specific procedures

GDLGES 73GDLGSL 75GDLSS 92

gdlapi.bas (sample Visual Basic module) 53gdlapi.h (sample header file) 52gdlCloseSpatialFile 20GDLCSF 57GDLDIST 60gdlDistance 21gdlFarDistance 22GDLFD 62gdlFileHandle 20, 57gdlFindNearest 23gdlFindNext 24gdlFindNextPolygonOverlap 25gdlFindNextPolygonOverlapPercentage 26gdlFindPolygonOverlap 26, 28GDLFN 64GDLFNPO 66GDLFNPOP 67GDLFNX 68GDLFPO 69GDLFPOP 71GDLGES 73gdlGetAttributeCount 30gdlGetAttributeInfoByName 31gdlGetAttributeInfoByNumber 32gdlGetAttributeNameByNumber 33gdlGetStreetLength 35gdlGetVersion 36GDLGSL 75GDLINIT 77gdlInitialize 37gdlManhattanDistance 37GDLMD 78GDLND 80gdlNearDistance 38gdlOpenSpatialFile 39GDLOSF 82GDLPIP 83GDLPIPN 85gdlPointInPolygon 40gdlPointInPolygonNext 41

GDLSC 86gdlSetStr 42GDLSF 88GDLSGC 89GDLSGL 91gdlShapeCreate 42gdlShapeFree 43gdlShapeGetCoords 44gdlShapeGetLong 45gdlShapeGetStr 46gdlSpatialConvert 47GDL-specific functions

gdlGetAttributeCount 30gdlGetAttributeInfoByName 31gdlGetAttributeInfoByNumber 32gdlGetAttributeNameByNumber 33gdlGetStreetLength 35gdlSetStr 41

GDLSS 92GDLTERM 94gdlTerminate 47gdlWriteShape 48generate error surface 73geocode

and confidence factors 9buffers 74quality level 9

geocoding library 5geographic

determination 6region 51variance 6

GeoStan 5geo-variance

buffer 5, 51region 74surface 9, 51

get coordinates 44, 89Group 1 GSB format 100GSA file 98GSB file 98GSB format (Spatial+) from Group 1 48, 100

H

handledefinition of 11set properties 41, 92

header file, C 52hull, convex 74

I

import utility 98initialization

functions 18, 51of GDL 37of GDL/390 77


of library 11procedures 55

initialization functionsgdlInitialize 37gdlTerminate 47

initialization proceduresGDLINIT 77GDLTERM 94

input polygon 25, 28, 66, 71input values 95installation requirements 14–??

L

largestobject 32, 33

last function called 48last procedure called 94latitude/longitude coordinates 5length of street segment or diagonal 35, 55, 75licensing

password 37line

number of line objects in file 32, 33linear distance 6link errors 50

M

Manhattan distance 19, 37, 56, 78manual determination 10Mapguide format from Autodesk 99mapping tools 49maximum distance 19, 22, 56, 62MIF/MID formats from MapInfo 48minimum distance 38, 80

N

near/far distance comparisons 51nearest object 23, 64next nearest feature 24, 68

O

object, get properties 45, 46, 91, 92open spatial file 39, 51, 82operation, spatial comparison 6, 12output parameter 51overlap percentage 6, 9, 26, 67overlapping polygons 25, 26, 28, 66, 69, 71

P

parameters, output 51percentage of polygon overlap 6, 9, 19, 26, 28, 55, 67,

71pipObjectGetAttributeInfoByNumber function 32polygon

find first 40, 83find next 41, 85overlapping 26, 51, 69

primitive data types 17, 54procedure

GDLSGS 92procedure syntax 54procedures

COBOL See COBOL procedurescomparison operation 55file operation 55GDLCSF 57GDLDIST 60GDLFD 62GDLFN 64GDLFNPO 66GDLFNPOP 67GDLFNX 68GDLFPO 69GDLFPOP 71GDLGES 73GDLGSL 75GDLINIT 77GDLMD 78GDLND 80GDLOSF 82GDLPIP 83GDLPIPN 85GDLSC 86GDLSF 88GDLSGC 89GDLSGL 91GDLSS 92GDLTERM 94initialization 55

process, determination 11program flow 52properties, of object 45, 46, 91, 92

Q

quality level of geocode 9

R

release system resources 47, 52, 94return values 95

S

SDF format from Autodesk 48set handle properties 41, 92shape object, get properties 45, 46, 91, 92shape operation functions


gdlShapeCreate 42gdlShapeFree 43gdlShapeGetCoords 44gdlShapeGetLong 45gdlShapeGetStr 46

shape operation proceduresGDLSC 86GDLSGC 89GDLSGL 91GDLSGS 92

Shapefile format from ESRI 48, 99shapes

creating 42, 86description 12types 97variables 97

sizeof buffer 33

spatialclose file 20, 57comparison 5, 6data format 48file 6, 10object 12relationship 9

spatial operation proceduresGDLSF 88

Spatial+ GSB format from Group 1 48Spatial+ library 6stack space, out of 50straight line distance 21, 60street segment

buffer 74length 35, 55, 75

supported formats 99, 101surface, geo-variance 51symbolic constants 52syntax of functions 17syntax of procedures 54

T

termination function 47termination procedure 94

U

user coordinates 12

V

variables 97Visual Basic 53

W

Windows 50

writingfeatures to particular data format 46shape to filesystem 48

Z

z/OS 50ZIP Code boundary 74zOS-specific procedures

GDLGES 73GDLGSL 75GDLSS 92

geographic determination library - pitney bowes

Documents