Auxiliary files

Creating your auxiliary files

This section contains information on creating auxiliary files, and contains the following topics:

• Auxiliary file requirements

• Record types

• Auxiliary file organization

• Default values

Auxiliary file requirements

GeoStan requires that the auxiliary file comply with the following:

• File must be a fixed-width text file

  • On Windows and UNIX, text file must be ASCII

  • On MVS, each text file must be in EBCDIC, and the DDNAME for the auxiliary file must end in a number (for example, AUXFIL1)

• File must have a .gax extension on Windows and UNIX

• File must have less than 500,000 records

• File must follow the column field order and lengths specified in Auxiliary file layout

Record types

You can include two types of records in your auxiliary file.

Street RecordsA street record contains a range of one or more addresses on a street. To be a valid street record the record must have the following fields:

n ZIP Code

n Street name

n Street type abbreviation, if part of the address

n Predirectional abbreviation, if part of the address

n Postdirectional abbreviation, if part of the address

n Low house number within the street segment

n High house number within the street segment

n Beginning longitude of the street segment

n Beginning latitude of the street segment

In addition, a street record may NOT have:

n Secondary address information, such as unit numbers

n Mailstops

n Private mail boxes (PMBs)

Landmark RecordsA landmark record represents a single site. To be a valid landmark record the record must have the following fields:

n ZIP Code

n Name of the landmark – placed in the street name field

n Beginning latitude of the landmark

n Beginning longitude of the landmark

In addition, a landmark record may NOT have the following fields:

n Street type abbreviation

n Predirectional abbreviation

n Postdirectional abbreviation

n Low house number

n High house number

During processing GeoStan ignores any record that does not comply with the preceding requirements.

Auxiliary file organization

You must comply with the following organizational rules when creating your auxiliary file.

• Use semicolons in the first column to indicate a row is a comment, not a data record; GeoStan ignores rows that begin with a semicolon.

• Order the records within the file by descending ZIP Code then descending street name for optimal performance.

• All records must represent one or both sides of a street.

• All records must represent segments that are straight lines. Records cannot represent a non-straight segment.

• If house numbers are present in the record, the house number range must be valid according to USPS rules documented in Publication 28.

• The numeric fields, such as ZIP Codes, must contain all numbers.

• Latitude and Longitude values must be in millionths of decimal degrees.

• Records cannot contain PO Box addresses.

Default values

GeoStan uses the following defaults if you do not include the values in the auxiliary file:

• House number parity = B (both odds and evens)

• Segment direction = F (forward) or A (ascending), these are interchangeable.

• Side of street = U (unknown)

Matching to auxiliary files

This section provides information on the matching performed by GeoStan to auxiliary files, and contains the following topics:

• Matching overview

• Record type matching rules

• Unavailable GeoStan features and functions

• Auxiliary match output

Matching overview

GeoStan performs the following steps when matching an input address to an auxiliary file.

1. GeoStan determines if there is an auxiliary file present.

   GeoStan only accepts one auxiliary file. If more than one auxiliary files is present, GeoStan attempts to match against the first file. GeoStan ignores any additional auxiliary files for matching, regardless if Geostan found a match to the first auxiliary file.

   If a record within the auxiliary files is invalid, GeoStan returns a message indicating the auxiliary file has an invalid record. GeoStan continues to process input addresses against the auxiliary file, but will not match to the invalid auxiliary file record.

2. If an auxiliary file is present, GeoStan first attempts to match to the auxiliary file.

   GeoStan assumes that the auxiliary file is the most accurate data set and first attempts to find a match to the input address in the auxiliary file. If GeoStan cannot find a match in the auxiliary file, it continues to process as normal against the traditional GeoStan data sets.

   Note: GeoStan only matches your input address to your auxiliary file if there is an exact match. Therefore, your input address list should be as clean as possible; free of misspellings and incomplete addresses.

3. If GeoStan finds an exact record match to the auxiliary file, it standardizes the match to USPS regulations and returns the output of the auxiliary file match.

Record type matching rules

When attempting a match against an auxiliary file, GeoStan abides by the following rules:

Street record match

• The input house number must fall within or be equal to the low and high house number values of the auxiliary record.

• The input house number must agree with the parity of the auxiliary record.

• The input ZIP Code must exactly match the ZIP Code of the auxiliary record.

Landmark record match

• The input data must contain both a ZIP Code and address line, and they must exactly match the values on the auxiliary record.

• The input address cannot have any other data, such as a house number, unit number, or Private Mail Box (PMB).

Unavailable GeoStan features and functions

The following contains the features and functions that do not apply when GeoStan makes an auxiliary file match.

• GeoStan does not match to:

  • two-line addresses

  • multi-line addresses

  • intersection addresses

  • dual addresses

• You cannot use auxiliary file matching when processing in CASS mode

• GeoStan does not perform EWS, ZIPMove, LACS^Link, or DPV processing on auxiliary matches

• You cannot create an auxiliary file for the reverse geocoding option

• You can only access the auxiliary file with processing through the Find function. You cannot access the auxiliary file through the Find First/Next or MBR functions

• You can only accesses the auxiliary file logic using the address code option of the Find function; not the geocode option.

• The following are not executed:

  C	COBOL	Java	.Net
  GsGetCoords	GSSETSEL	GeoStan.getCoords	Coordinate
  GsSetSelection	GSSSELR	GeoStan.select	GeoStan.select
  GsSetSelectionRange	GSHGET	Range.select	Range.select
  GsHandleGet	GSMGET	Street.getData	Street.getData
  GsHandleGetCoords	GSMGH	Segment.getData	Segment.getData
  GsMultipleGetHandle	GSHGCRD	Range.getData	Range.getData
  GsMultipleGetHandle	GSMGH	GeoStan.getRange	GeoStan.getRange
  GsHandleGetCoordsEx	GSHGCRDX	Segment.getCoords	Segment.Coords

Auxiliary match output

Several standard GeoStan outputs do not apply to an auxiliary match since GeoStan matches to an exact auxiliary match and does not perform any additional validation for the match.

GeoStan provides special match codes and location code values for auxiliary matches. See Appendix D: Status codes for more information.

When GeoStan finds a match to an auxiliary file, the default output follows the following conventions:

• GeoStan formats the output of auxiliary file match as a street-style address.

• GeoStan follows the casing setting you indicate by the casing function. GeoStan does not maintain the casing in the auxiliary file for mixed cased values. For example, GeoStan returns O’Donnell as ODONNELL or Odonnell depending on the setting of the casing function.

• GeoStan removes spaces at the beginning and ending of fields in the auxiliary file.

Auxiliary file layout