Deprecated C APIs

GsFind

Deprecated. Matches the current address loaded via GsDataSet.

Syntax

GsFunStat GsFind( GsId gs, GsEnum options );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

options   GsFind options. The following table contains valid enums. Input.

For Address processing, you must use either GS_ADDR_CODE or GS_Z_CODE (or both). These settings are additive. For most purposes, you should specify the GS_ADDR_CODE, GS_Z_CODE, and GS_GEO_CODE switch.

If you specify GS_ADDR_CODE and one of the Geocode level options, GeoStan only returns a ZIP Code centroid match if the address is standardized but an address geocode is not available.

For reverse geocoding, you need to set the reverse geocoding processing options: GS_NEAREST_ADDRESS, GS_NEAREST_INTERSECTION, and GS_NEAREST_UNRANGED. The address processing and multi-line address processing options are not valid for reverse geocoding.

Return Values

GS_ADDRESS_NOT_RESOLVED    GeoStan cannot resolve a match candidate.

GS_ADDRESS_NOT_FOUND    GeoStan did not find an address match or if you have a metered license and the GeoStan record count is depleted.

For metered licenses, GsFind decrements the GeoStan record counter in the license each time it returns a non-error match code. If the counter reaches zero or below, GsFind returns GS_ADDRESS_NOT_FOUND and sets the match code to E015. If you have an unmetered license, no decrementing occurs, and processing is unlimited.

GS_ERROR   Low-level errors; use GsErrorGet to retrieve the error information.

GS_LASTLINE_NOT_FOUND    GeoStan did not find a match for city/state or ZIP Code.

GS_SUCCESS    GeoStan found a match.

Prerequisites

GsDataSet

Notes

If GeoStan cannot standardize and address, you can still retrieve normalized address information, match codes, carrier routes, or other elements with GsDataGet. You can retrieve alias information by calling GsMultipleGet with an index of 0.

Before each find function, call GsClear to reset the internal buffers. If you do not reset the buffers, you may receive incorrect results with information from a previous find. If you use both the reverse geocode and address line matching enums in the same call, GeoStan displays an error. These types of finds are mutually exclusive.

GsGetCoords

Deprecated. Use GsGetCoordsEx for greater precision.

Syntax

ints GsGetCoords( GsId gs, pintl pCoords, intsu maxPoints );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

pCoords   Array of coordinates, in x,y (longitude, latitude) order. Output.

maxPoints   Maximum number of points to return; used to prevent writing past the end of the pCoords buffer. Input.

Return Values

Number of points assigned to buffer.

Prerequisites

GsFind

Notes

This function returns an array of coordinates for the current feature found via GsFind. The maximum number that GeoStan can return is 64 coordinate pairs, each pair consisting of two long integers.

GeoStan scales coordinate pairs to integers with four decimal digits of precision. For example, GeoStan returns a point at (-98.3, 29.7) as (983000, 297000). This is a different scale from that expected by Spatial+ and similar GIS applications, which typically express coordinates in millionths of degrees. You may need to scale coordinates obtained with this function before using them as input to other software libraries or applications.

GsGetDatum

Deprecated. Returns the current datum setting.

Syntax

intlu GsGetDatum ( GsId gs );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

Return Values

Current datum setting. Valid settings are DATUM_NAD27 and DATUM_NAD83 (default).

Prerequisites

GsSetDatum

Notes

This function returns the datum currently used by GeoStan in calculating address coordinates. This setting affects only the numeric coordinates returned by GsDataGet for the latitude and longitude of an address.

A datum is a mathematical model of the Earth used to calculate the coordinates on any map, chart, or survey system. The North American Datum (NAD) is the official reference ellipsoid used for the primary geodetic network in North America.

Although the return values are DATUM_NAD27 and DATUM_NAD83, note that TomTom uses WGS84 instead of NAD83. These two coordinate systems are compatible.

GsHandleGetCoords

Deprecated. Only used with GsGetCoords. If using GsGetCoordsEx, use GsHandleGetCoordsEx.

Syntax

ints GsHandleGetCoords( GsId gs, GsSegmentHandle *pHandle,pintl pCoords, intsu maxPoints );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

*pHandle   Handle of the segment object for the coordinates returned. Input.

pCoords   Array of coordinates, in x,y (longitude, latitude) order. Output.

maxPoints   Maximum number of points that GsGetCoords returns; used to prevent writing past the end of pCoords buffer. Input.

Return Values

Number of points assigned to the buffer.

Prerequisites

GsFindFirst or GsFindNext

Notes

This function returns an array of coordinates for the segment to which handle points.

Example

/*This example retrieves coordinates for a street segment found using GsFindFirstSegment.*/

#define MAX_POINTS 50

.

.

.

ints NumCoords;

intl Coords[MAX_POINTS *2];

NumCoords = GsHandleGetCoords(gs, &hSegment, Coords, MAX_POINTS);

for (int i = 0; i < NumCoords * 2; i += 2)printf("Lon = %ld, Lat = %ld\n", Coords[i], Coords[i+1]);

GsInit_r

Deprecated. Initializes GeoStan.

Syntax

GsId GsInit_r ( GsInitStruct *gis );

Arguments

gis   Contains the following:

gsVersion   Set to GS_GEOSTAN_VERSION. Input.

options   The following table contains valid enums. Input.

Except for a few cases, you should always specify GS_FILE_ADDR_CODE and GS_FILE_Z9_CODE. For example:

GS_FILE_ADDR_CODE | GS_FILE_Z9_CODE

pGeoPaths   List of paths to search for necessary files. Input.

pZ4Dir   Name of the ZIP + 4 directory file. Input.

licFilePassword    Password for the license file. Input.

licFileName   String [GS_MAX_STR_LEN] that specifies the path and name of the license file, for example, c:\license\geostan.lic. Input.

cacheSize   Relative cache size used by GeoStan; either 0, 1, or 2. Input.

relDate   String [GS_MAX_STR_LEN] that specifies the latest data to use in initialization, in the format YYYYMMDD. Input.

status   Pointer to a long (32 bit) integer that stores details on the successfully initialized components. Output.

GeoStan uses the following constants to test each significant bit:

Return Values

Valid GsId    System initialized correctly.

NULL   GeoStan failed to initialize. This can occur for one of the following reasons:

n GeoStan did not find the necessary files. Check the Status argument to view the files GeoStan found.

n GeoStan could not find the license files or the passwords were incorrect.

n There is not enough memory for GeoStan to initialize.

n All available GSD files have expired. Indicated by GS_FILE_EXPIRED in the status argument.

GS_WARNING   If you are using GsSetFilememoryLimit, you can only call GsSetFilememoryLimit once per process. When calling GsInit_r more than once, you do not need to call GsSetFileMemoryLimit again.

Notes

GsInit_r is the recommended way to start a GeoStan application. It sets the license and expiration date, and initializes the library.

You can use GsSetFilememoryLimit to control the amount of memory used for mapped files. If you are using GsSetFilememoryLimit, call GsSetFilememoryLimit before calling GsInit_r.

Example

bool showAllMessages = true;

GsId gs;

char message[256];

char details[256];

intlu lDays;

GsInitStruct GIS;

/* Initialize GeoStan */

/* Complete the initialization structure */

GIS.gsVersion = GS_GEOSTAN_VERSION;

GIS.options = GS_FILE_ADDR_CODE|GS_FILE_Z9_CODE;

strcpy(GIS.pGeoPaths, "c:\\geostan\\datasets;c:\\geostan");

strcpy(GIS.pZ4Dir, "c:\\geostan\\datasets\\us.z9");

GIS.licFilePassword=43218765;

strcpy(GIS.licFileName, "c:\\license\\geostan.lic");

GIS.cacheSize=2;

strcpy(GIS.relDate,"");

GIS.status=0;

/* Initialize the library */

gs = GsInit_r(&GIS);

if ( gs == 0 || showAllMessages ){while ( GsErrorHas(gs) ){     GsErrorGetEx(gs, message, details);

printf ("%s\n %s\n", message, details); }

    if ( gs == 0 )

    {

       /* GeoStan failed to initialize */

        printf("Unable to initialize GeoStan library,        status =       %04X.\n", GIS.status);

       return(1);

    }

}

/* GeoStan is initialized */

/* retrieve information about your GeoStan license */

lDays = GsFileStatusEx(gs, GS_STATUS_DAYS_REMAINING, 0, 0);

if ( lDays == DAYS_UNLIMITED )

{

printf("License is non-expiring.\n");

}

else

{

printf("License will expire in %d days.\n", lDays);

}

/* retrieve information about your GeoStan data */

lDays = GsFileStatusEx(gs, GS_STATUS_DATATYPE_STR, message, 256);

if ( lDays == GS_SUCCESS )

{

printf("GeoStan data type is %s.\n", message);

}

else

{

printf("Failed to retrieve information about data.\n");

}

/* do your geocoding ...*/

/* close the library */

GsTerm(gs);

return(0);

GsInitDpv_r

Deprecated. Initializes GeoStan for DPV

Syntax

GsFunStat GsInitDpv_r (GsId gs, DpvInitStruct *dpvInitStruct, int structSize);

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

*dpvInitStruct   This structure contains the following:

dataAccess   Indicates the type of files to load and how to access the files. The following table contains the possible values. Input.

memoryBufferSize    Number of MBs used to load buffered files into memory. Input.

This option is only valid if dataAccess is not DPV_DATA_FULL_MEMORY. The following table contains the possible values.

options   Reserved for future implementation. Input.

pDirectory   String that specifies the directory containing DPV data. Input.

securityKey   Security key to initialize DPV functionality. Input.

Status   Indicates the successful initialization of DPV. The following table contains the constants used to test each significant bit. Output.

structSize   Size of the dpvInitStruct data structure. Input.

structVersion    Set to GS_GEOSTAN_VERSION. Input.

Return Values

GS_SUCCESS    Initialized successfully.

GS_ERROR    Failed to initialize. Call GsErrorGetEx for information.

Prerequisites

See notes

Notes

If you are using GsSetFileMemoryLimit to control the amount of memory used for memory mapped files, you need to call GsInitDpv_r after GsSetFileMemoryLimit and before GsInit_r.

If you are not using GsSetFileMemoryLimit, you need to call GsInit_r before calling GsInitDpv_r.

GsInitLACSLink_r

Deprecated. Initializes GeoStan for LACS^Link.

Syntax

GsFunStat GsInitLACSLink_r ( GsId gs,LACSLinkInitStruct *lacsInitStruct, init structSize);

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

*lacsInitStruct    This structure contains the following:

structVersion    LACS^Link version number. Set to GS_GEOSTAN_VERSION. Input.

pDirectory   String that specifies the directory containing LACS^Link data. Input.

status   Indicates the successful initialization of LACS^Link. The following table contains the constants used to test each significant bit. Output.

options   Reserved for future implementation. Input.

securityKey   Security key to initialize LACS^Link functionality. Input.

structSize   Size of the lacsInitStruct data structure. Input.

Return Values

GS_SUCCESS    Initialized successfully.

GS_ERROR   Failed to initialize. Call GsErrorGetEx for information.

Prerequisites

See notes

Notes

If you are using GsSetFileMemoryLimit to control the amount of memory used for memory mapped files, you need to call GsInitLACSLink_r after GsSetFileMemoryLimit and before GsInit_r.

If you are not using GsSetFileMemoryLimit, you need to call GsInit_r before calling GsInitLACSLink_r.

GsSetDatum

Deprecated. Specifies the datum GeoStan uses to calculate address coordinates.

Syntax

intlu GsSetDatum ( GsId gs, intlu iNewDatum );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

iNewDatum   Enum value indicating the datum to use in returning address coordinates. Valid enums are DATUM_NAD27 and DATUM_NAD83 (default). Input.

Return Values

GS_SUCCESS   GeoStan used the requested datum to calculate the existing coordinates (no conversion required), or if all of the files for the requested datum are present.

GS_ERROR   GeoStan did not find any of the files for the requested datum. GeoStan continues to use the current datum, and does not reset. Call GsErrorGet to find out which datum files did not load.

Prerequisites

GsInit_r

Notes

Use GsSetDatum to select the datum you want GeoStan to use when returning address coordinates via GsDataGet.This setting affects only the numeric coordinates returned by GsDataGet for the latitude and longitude of an address.

You must call GsSetDatum before calling GsFind. GeoStan does not cache or modify the lat and lon values if you call GsSetDatum after GsFind.

Although the arguments are DATUM_NAD27 and DATUM_NAD83, note that TomTom uses WGS84 instead of NAD83. These two coordinate systems are compatible.

GsSetFileMemoryLimit

Deprecated. Controls the amount of memory used for memory mapped files.

Syntax

int GsSetFileMemoryLimit (intlu megabytes)

Arguments

megabytes   Amount of memory to budget for memory mapped files. 0-4294 megabytes. If you input 0, GeoStan uses a small cache and reads from the disk. If you use the maximum amount, GeoStan maps as many files as possible until the limit is exhausted. Input.

Return Values

GS_SUCCESS   

GS_ERROR   You must call GsSetFileMemoryLimit before calling GsInit_r.

Prerequisites

None

Notes

GsSetFileMemoryLimit helps you control the amount of memory GeoStan uses by providing you with a way to set the memory limit for mapped files. Mapped files are the gsd, gsu, gsi, cbsac.dir, finmbr.dat, and us.gsl files.

Call GsSetFileMemoryLimit before GsInit_r. GsSetFileMemoryLimit returns a warning if called more than once per process.

If you are using DPV and LACS^Link, you must call GsInitDpv_r and GsInitLACSLink_r after GsSetFileMemoryLimit and before GsInit_r. Although the DPV and LACS^Link files are not memory mapped files, these libraries load large files that can cause GsInit_r to fail if not enough memory is reserved.

To determine the amount of virtual bytes used by your process, set the file limit to 0 and run your process.

GsSetMatchMode

Deprecated. Controls the matching mode used by GsFind.

Syntax

ints GsSetMatchMode( GsId gs, ints MatchMode );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

MatchMode   Enum value indicating match mode type. The following table contains valid enums. Input.

Return Values

Old match mode

– or –

-1 if the new match mode is invalid

Prerequisites

GsInit_r or GsClear

Notes

GsSetMatchMode affects how GsDataSet performs. For this reason, only call this function immediately after GsInit_r or GsClear. The results are undefined if you call this function with GsDataSet.

To emulate the Centrus Desktop modes, use the settings in the following table.

GsFind then uses as its second argument the enums listed (in combination with a logical OR). For example, in CASS mode, the second argument to GsFind is:

GS_ADDR_CODE | GS_Z9_CODE | GS_FINANCE_SEARCH

Enums for the second argument in GsFind are:

Changing GsSetMatchMode does not require the presence of the following files; however, to achieve strict CASS compliance, these files must be present:

• Us.gsz

• Use.gsd and Usw.gsd

• Use.gsu and Usw.gsu

• DPV data

• EWS data (The file must be named ews.txt)

GsSetMixedCase

Deprecated. Sets the casing of the returned information.

Syntax

ints GsSetMixedCase( GsId gs, ints bMixedCase );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

bMixedCase   Sets the casing. Input.

n 0 = (default) Upper case

n 1 = Mixed case

Return Values

Current setting for this option (the setting before the change).

Prerequisites

GsInit_r

Notes

This function determines if GeoStan returns standardized data in upper or mixed case. It affects Firm name, all Address components, and City name. The USPS prefers upper case.

If you specify mixed case, generally only the first letter is set to upper case.

GsSetStreetCentroid

Deprecated. Used to enable street locator geocoding as an automatic geocoding fallback.

Syntax

qbool GsSetStreetCentroid( GsId gs, qbool GsStrCen );

Arguments

gs   ID returned by GsInit_r for the current instance of GeoStan. Input.

GsStrCen   Specifies whether or not to return a street segment geocode as an automatic geocoding fallback. Input.

n 0 = (default) Street locator disabled

n 1 = Return street segment geocode

Return Values

Current setting for this option (the setting before the change).

Prerequisites

GsInit_r

Notes

When this feature is enabled, if a street name is encountered while geocoding, and there is no matching address range, GeoStan will attempt to locate the street within the input ZIP Code or city if there is no input ZIP Code. If GeoStan is able to locate the street, it will return a geocode along the matched street segment rather than the geocode for the entered ZIP Code or ZIP + 4.

If a street number is entered, GeoStan will return the coordinates of the end point of the closest numeric street segment within the input ZIP Code. When there is no input ZIP Code, the closest numeric street segment of all the ZIP Codes within the input city will be returned.

If no street number is entered, the centroid of a matching street segment within the input ZIP Code will be returned. The centroid of a street segment for all the ZIP Codes within the input city will be returned when there is no input ZIP Code.

Match candidates may be returned. More information about the returned segment(s) can be obtained for either a single or a match candidate by calling GsMultipleGet().

This option is not available in CASS mode.