Installing ZipCenter

ZipCenter
User Manual
™
ZipCenter
™
User Manual
© 1997-2001 David Adams. All Rights Reserved.
Published World-Wide by Automated Solutions Group, Inc.
Automated Solutions Group.
16742 Gothard Street, Suite 218
Huntington Beach, CA 92647
(800) 375-4ASG • (714) 848-0382 FAX
http://www.asgsoft.com/
ZipCenter
Program design and examples: David Adams
External conversion: Stewart Buskirk
Manual: David Adams, John Steele
SOFTWARE LICENSE AND LIMIMTED WARRANTY
SOFTWARE LICENSE AND LIMIMTED WARRANTY
PLEASE READ THIS LICENSE CAREFULLY BEFORE USING THE SOFTWARE CONTAINED ON THE DISKS. BY USING THE SOFTWARE, YOU
AGREE TO BECOME BOUND BY THE TERMS OF THIS AGREEMENT,
WHICH INCLUDES THE SOFTWARE LICENSE AND WARRANTY DISCLAIMER (collectively referred to herein as the “Agreement”). THIS
AGREEMENT CONSTITUTES THE COMPLETE AGREEMENT BETWEEN
YOU AND AUTOMATED SOLUTIONS GROUP, INC. IF YOU DO NOT
AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT USE THE SOFTWARE AND PROMPTLY RETURN THE PACKAGE FOR A FULL REFUND.
Ownership of Software. The enclosed manual and computer programs (“Software”) were developed and copyrighted by David Adams, and are exclusively
published and distributed by Automated Solutions Group, Inc. (“ASG”) and are
licensed, not sold, to you by David Adams/ASG for use under the following
terms, and David Adams/ASG reserve any rights not expressly granted to
you. You own the disk(s) on which any software is recorded, but David
Adams/ASG retains ownership of all copies of the Software itself. Neither the
manual nor the Software may be copied in whole or in part except as explicitly
stated below.
License. David Adams/ASG, as Licensor, grants to you, the LICENSEE, a
non-exclusive, non-transferable right to use this Software subject to the terms
of the license as described below:
You may make backup copies of the Software for your use provided they bear
the David Adams/ASG copyright notice.
You may use this Software in an unlimited number of custom or commercial
databases or applications created by the original licensee. No additional
product license or royalty is required.
Restrictions. You may not distribute copies of the Software to others (except
as an integral part of a database or application within the terms of this
License) or electronically transfer the Software from one computer to another
over a network. You may not distribute copies of the Software as an integral
part of a development shell or non-compiled commercial data base. The Software contains trade secrets and to protect them you may not decompile,
reverse engineer, disassemble, or otherwise reduce the Software to a human
perceivable form. YOU MAY NOT MODIFY, ADAPT, TRANSLATE, RENT,
LEASE, LOAN OR RESELL FOR PROFIT THE SOFTWARE OR ANY PART
THEREOF.
Termination. This license is effective until terminated. This license will terminate immediately without notice from David Adams/ASG if you fail to comply
with any of its provisions. Upon termination you must destroy the Software
and all copies thereof, and you may terminate this license at any time by doing
so.
Update Policy. David Adams/ASG may create, from time to time, updated versions of the Software. At their option, David Adams/ASG will make such
updates available to the Licensee.
Warranty Disclaimer. THE SOFTWARE IS PROVIDED “AS IS” WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED , INCLUDING,
4
SOFTWARE LICENSE AND LIMIMTED WARRANTY
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. DAVID ADAMS/ASG
DO NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS
REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIALS IN THE TERMS OF CORRECTNESS,
ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE
ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. IF THE SOFTWARE OR WRITTEN
MATERIALS ARE DEFECTIVE YOU, AND NOT DAVID ADAMS/ASG OR
THEIR DEALERS, DISTRIBUTORS, AGENTS, OR EMPLOYEES, ASSUME
THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. However, DAVID ADAMS/ASG warrants to the original Licensee
that the disk(s) on which the Software is recorded is free from defects in materials and workmanship under normal use and service for a period of thirty (30)
days from the date of delivery as evidenced by a copy of the receipt.
THIS IS THE ONLY WARRANT OF ANY KIND, EITHER EXPRESS OR
IMPLIED, THAT IS MADE BY DAVID ADAMS/ASG ON THIS SOFTWARE
PRODUCT. NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN
BY DAVID ADAMS/ASG, IT’S DEALERS, DISTRIBUTORS, AGENTS, OR
EMPLOYEES SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE
THE SCOPE OF THIS WARRANTY, AND YOU MAY NOT RELY ON SUCH
INFORMATION OR ADVICE. THIS WARRANTY GIVES YOU SPECIFIC
LEGAL RIGHTS. YOU MAY HAVE OTHER RIGHTS, WHICH VARY FROM
STATE TO STATE.
Governing Law. This agreement shall be governed by the laws of the State of
California.
Windows is a registered trademark of Microsoft Corporation.
Apple is a registered trademark of Apple Computer, Inc.
Macintosh is a registered trademark of Apple Computer, Inc.
4th Dimension, 4D Server, 4D Compiler, and 4D are registered trademarks of
4D and 4D, Inc.
5
ZIPCENTER DATA FILE LICENSE AND LIMITED WARRANTY
ZIPCENTER DATA FILE LICENSE AND
LIMITED WARRANTY
PLEASE READ THIS LICENSE CAREFULLY BEFORE USING THE
DATA FILE CONTAINED ON THE DISKS. BY USING THE DATA
FILE, YOU AGREE TO BECOME BOUND BY THE TERMS OF
THIS AGREEMENT, WHICH INCLUDES THE DATA FILE LICENSE
AND WARRANTY DISCLAIMER (collectively referred to herein as
the “Agreement”). THIS AGREEMENT CONSTITUTES THE COMPLETE AGREEMENT BETWEEN YOU AND AUTOMATED
SOLUTIONS GROUP, INC. IF YOU DO NOT AGREE TO THE
TERMS OF THIS AGREEMENT, DO NOT USE THE DATA FILE
AND PROMPTLY RETURN THE PACKAGE FOR A FULL REFUND.
1. Ownership of Data File. The enclosed ZIP Code related data
file (“Data File”) is licensed by Automatd Solutions Group, Inc.
(“ASG”) for use under the following terms, and ASG reserves any
rights not expressly granted to you. You own the disk(s) on which
this Data File is recorded, but ASG retains exclusive rights to all
copies of the Data File itself. Any written documentation nor the
Data File may be copied in whole or in part except as explicitly
stated below.
2. License. ASG, as Licensor, grants to you, the LICENSEE, a
non-exclusive, non-transferable right to use this Data File subject
to the terms of the license as described below:
a. You may make backup copies of the Data File for your use
provided they bear the ASG copyright notice.
b. You may use this Data File in one installation of a 4D or
4D Server database (an “installation”). This includes all connections to this database via the web, custom TCP/IP connections, 4D Client, 4D Open, and so forth. A separate
license is required for each installation that utilizes the information contained within this Data File.
3. Restrictions. You may not distribute copies of the Data File to
others or electronically transfer the Data File from one computer
to another over a network (except as an integral part of an application within the terms of this License). You may only distribute
the Data File as an integral part of an application.
4. Termination. This license is effective until terminated. This
license will terminate immediately without notice from ASG if you
fail to comply with any of its provisions. Upon termination you
6
ZIPCENTER DATA FILE LICENSE AND LIMITED WARRANTY
must destroy the Data File and all copies thereof, and you may
terminate this license at any time by doing so.
5. Update Policy. ASG may create, from time to time, updated
versions of the Data File. At its option, ASG will make such
updates available to the Licensee.
6. Warranty Disclaimer. THE DATA FILE IS PROVIDED “AS IS”
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED , INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. ASG DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING
THE USE, OR THE RESULTS OF THE USE, OF THE DATA
FILE OR WRITTEN MATERIALS IN THE TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR
OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND
PERFORMANCE OF THE DATA FILE IS ASSUMED BY YOU. IF
THE DATA FILE OR WRITTEN MATERIALS ARE DEFECTIVE,
YOU, AND NOT ASG OR IT’S DEALERS, DISTRIBUTORS,
AGENTS, OR EMPLOYEES, ASSUME THE ENTIRE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
However, ASG warrants to the Licensee that the disk(s) on which
the Data File is recorded is free from defects in materials and
workmanship under normal use and service for a period of thirty
(30) days from the date of delivery as evidenced by a copy of the
receipt.
THIS IS THE ONLY WARRANT OF ANY KIND, EITHER EXPRESS
OR IMPLIED, THAT IS MADE BY ASG ON THIS DATA FILE
PRODUCT. NO ORAL OR WRITTEN INFORMATION OR ADVICE
GIVEN BY ASG, IT’S DEALERS, DISTRIBUTORS, AGENTS, OR
EMPLOYEES SHALL CREATE A WARRANTY OR IN ANY WAY
INCREASE THE SCOPE OF THIS WARRANTY, AND YOU MAY
NOT RELY ON SUCH INFORMATION OR ADVICE. THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE
OTHER RIGHTS, WHICH VARY FROM STATE TO STATE.
Governing Law. This agreement shall be governed by the laws of
the State of California.
ZipCenter is a trademark of David Adams.
7
Table of Contents
Table of Contents
SOFTWARE LICENSE AND LIMIMTED WARRANTY 4
ZIPCENTER DATA FILE LICENSE AND
LIMITED WARRANTY 6
Table of Contents viii
Using the ZipCenter Manual 10
Cross-Referencing Format 10
The Online PDF Version of the Manual 10
Command Lists 10
Command Descriptions and Syntax 11
About ZipCenter 12
ZipCenter Quick Lookups 13
ZipCenter Area Searches 13
ZIP Code Data 14
ZipCenter Use and Behavior 14
ZipCenter Requirements 14
Installing and De-Installing ZipCenter 15
ZipCenter Components 15
Installing the ZipCenter Plug-ins on the Macintosh 15
Installing ZipCenter 16
To Install ZipCenter in the Mac4DX Folder 16
De-Installing ZipCenter 16
De-Installing the Mac4DX version of ZipCenter 16
Installing ZipCenter Under Windows 16
To install ZipCenter from Program Manager 16
To install ZipCenter from the Windows 95/98 “Start” Menu 16
Using ZipCenter for Windows With Your
Database Applications 17
Configuration Commands 18
ZC_Register 18
Example 18
Note for Users of Earlier Versions of ZipCenter 19
ZipCenter Quick Lookups 20
Understanding Quick Lookups 20
ZipCenter Quick Lookup File Contents 20
Installing ZipCenter Lookup Files 21
Updating ZipCenter Lookup Files 21
ZipCenter Quick Lookups and Local Processes 21
ZipCenter Quick Lookup Commands 22
ZC_Lookup 22
ZC_GetMore 24
ZC_GetInfo 27
ZipCenter Area Searches 29
Introduction 29
What Does ZipCenter Area Searching Do? 29
How it Works 29
Required Data 30
viii
Table of Contents
Command Descriptions 30
ZC_SetStructure 30
ZC_FindZips 31
Locating Data Other Than ZIP Codes 33
Distance Commands 34
ZC_MilesApart 34
ZIP Code Data 35
Introduction 35
ZIP Code Data: Standard 35
Latitude and Longitude 36
4D Table Structure for Area Searches 36
ZIP Code Data: Enhanced 37
City Sequence 37
Acceptable 37
City, State and County FIPS Codes 38
4D Table Structure for Area Searches 38
Zip Center Lookup File Contents 40
Troubleshooting 42
Quick Lookups 42
Serial Numbers 42
ZipCenter Errors 43
Technical Support 44
ZipCenter Demo 45
Introduction 45
Overview 45
ZipCenter Quick Lookup 46
Zip Center Area Search 47
Distance Calculator 47
Edit Customers 49
View ZIP Codes 50
ZipCenter Command Reference — by Chapter 51
ZipCenter Command Reference — Alphabetical 52
ix
Using the ZipCenter Manual
Using the ZipCenter Manual
The ZipCenter package includes three components:
◆
5-digit ZIP Code lookups in an external file.
◆
Area searches.
◆
Current 5-digit ZIP Code data.
The “About ZipCenter” chapter provides an overview of the ZipCenter package. The individual components are described in their
own chapters. Each chapter begins with an overview of the topic,
and how to use the different commands. Each command is then
covered in detail, and examples provided.
If you are having troubles with ZipCenter, review the “Troubleshooting” chapter. If you are unable to resolve a problem using
this manual, you can contact our Technical Support Department,
as discussed in “Technical Support”.
Cross-Referencing Format
Each time a command is used, a cross-reference is given in parenthesis to let you quickly find the definition for the command.
The Online PDF Version of the Manual
The PDF version of this manual lets you view the manual using
Adobe Acrobat Reader. While viewing the manual, you can click
on any cross reference to jump immediately to the referenced
page. These hypertext-style jumpers are available for all cross references, the Table of Contents, Index, and command listings.
Command Lists
“ZipCenter Command Reference — by Chapter” lists ZipCenter
commands by chapter. “ZipCenter Command Reference — Alphabetical” lists ZipCenter commands alphabetically. These lists
include the parameters for each command, and the page number
for the command definition.
10
Using the ZipCenter Manual
Command Descriptions and Syntax
Each ZipCenter command has a syntax, or rules, that describe
how to use the command in your 4D database. For each command, the name of the command is followed by the command’s
parameters. The parameters are enclosed in parenthesis, and separated by semicolons. Following the command syntax description,
an explanation of the command’s parameters is provided.
Optional parameters are enclosed in brackets (the “[“ and “]”
characters).
For each parameter, the type of the parameter and a description is
shown. Several examples are provided for each of the commands,
showing examples of the syntax as well as how the various commands are used together.
Some parameters are used by ZipCenter to return a value. Do not
use local variables for these parameters, because 4D doesn’t support returning values from a plug-in into a local variable. Use a
process or inter-process variable.
11
About ZipCenter
About ZipCenter
ZipCenter adds 5-digit ZIP Code data and utilities to any 4D or
4D Server database. ZipCenter is really three products in one,
and includes:
◆
ZipCenter Quick Lookups
Plug-in commands and a special file for lightning fast ZIP
Code lookups.
◆
ZipCenter Area Searches
Plug-in commands that perform area searches.
◆
ZIP Code Basic Data Subscription
A 5-digit ZIP Code file in both ZipCenter and ASCII-file formats. The text file may be imported into any system for any
purpose. Includes fields for ZIP Code, Latitude, Longitude,
City and State. See “Zip Center Lookup File Contents” on
page 40 for more information.
or
◆
ZIP Code Enhanced Data Subscription
A 5-digit ZIP Code file in both ZipCenter and ASCII-text file
formats. The text file may be imported into any system for any
purpose. In addition to the fields included with the Basic data
file,the Enhanced data file includes:
- In the ZipCenter file: fields for County, County and State
FIPS Code, Area Code and whether or not secondary city
names are approved.
- In the ASCII-text file: fields for County, City FIPS, County
FIPS, State FIPS, Area Code, MSA Code, Time Zone,
whether Daylight Savings is observed, and whether or not
secondary city names are approved.
See “Zip Center Lookup File Contents” on page 40 for more
information.
The plug-ins and sample code included with ZipCenter also
include these features:
◆
Multi-process and multi-user safe code.
◆
Highly optimized for use under 4D or 4D Server.
◆
Flexible, high-performance procedural replacements for 4D’s
RELATE ONE SELECTION and RELATE MANY SELECTION commands.
12
About ZipCenter
ZipCenter Quick Lookups
Data entry is time consuming and error prone. A ZIP Code
lookup system makes address entry quicker and more accurate.
ZipCenter can look up any ZIP Code with almost no code. ZipCenter uses a special file on each user’s machine to perform ZIP
Code lookups, so query speed is as fast under 4D Server as
under 4D. ZipCenter quick lookups do not require adding tables
or data to your 4D database structure. The ZipCenter quick
lookup system is completely independent from the area search
features of ZipCenter, and does not require the ZIP Code data
provided with the package.
Please read the section “ZipCenter Quick Lookups” on page 20
for more information.
ZipCenter Area Searches
ZipCenter’s area search system finds all ZIP Codes within the
distance you specify from a starting point. In other words, ZipCenter finds records based on proximity. ZipCenter area
searching lets you answer the kinds of questions people like to
ask, rather than the kind of questions databases like to answer.
For example, you can use an area search to answer questions
like these:
◆
Find me every customer with 50 miles of our office.
◆
Find me the 7 closest doctors to this patient’s house.
◆
Find me hotels that are within 10 miles of this airport.
◆
Tell me the distance between these two locations.
These are natural and useful questions. Unfortunately, these
questions are difficult or impossible to answer in a normal database. ZipCenter helps you answer these questions with only a
few lines of code.
ZipCenter area searches give you a competitive advantage by
allowing you to get new information out of your data. The ZipCenter area search system requires ZIP codes and their
geophysical coordinates inside of your database. All of the data
you need is included with the product.
Please read the section “ZipCenter Area Searches” on page 29
for more information.
13
About ZipCenter
ZIP Code Data
ZipCenter includes current descriptions of U.S.P.S (United States
Postal Service) 5-digit ZIP Codes. You can use this data in any
way you like. The ZIP Code data includes the latitude and longitude information need by ZipCenter area searches. ZIP Codes
change on a regular basis, so your ZIP Code data should be
updated every few months. The ZipCenter product family
includes two kinds of data subscriptions. The standard package
includes ZIP Code descriptions with latitude and longitude. The
enhanced package adds area code, county names, state FIPS,
county FIPS, and entries for all secondary cities.
Please read the section “ZIP Code Data” on page 35 for more
information.
ZipCenter Use and Behavior
ZipCenter can be used with just a few commands. The example
database includes numerous examples of how to apply these
commands to quickly solve complex problems.
ZipCenter Requirements
Because of its implementation, ZipCenter imposes very minimal
memory requirements. The ZipCenter quick lookup system
requires no additional memory over standard 4th Dimension
requirements.
The Mac version of ZipCenter requires 4th Dimension v3.2.5 or
higher, and is compatible with databases complied with 4D Compiler. The example database includes routines optimized for
4D 3.5.3 and higher, including 4D and 4D Server V6 and later.
On the Macintosh, ZipCenter also requires System 7.
The Windows version of ZipCenter requires 4th Dimension 3.5 or
higher, and is compatible with databases compiled with the 4D
Compiler.
14
Installing and De-Installing ZipCenter
Installing and De-Installing ZipCenter
ZipCenter Components
ZipCenter includes three components.
◆
ZipCenter Plug-Ins
The ZipCenter plug-in package includes commands to perform area searches, and quick ZIP Code lookups. Installing
these plug-ins is the subject of this chapter.
◆
ZipCenter Quick Lookup File
If you use ZipCenter for local-5 digit ZIP Code lookups install
the ZipCenter plug-ins as described in this chapter, and install
the ZipCenter lookup file as described in “Installing ZipCenter
Lookup Files” on page 21.
◆
ZIP Code Data
If you want to perform ZipCenter area searches install the ZipCenter plug-ins as described in this chapter, and import the
ZIP Code data as described in “ZipCenter Area Searches” on
page 29.
You can also use the ZIP Code data for general ZIP Code lookups in your system. The exact contents of the ZIP Code import
file depends on your version of the ZipCenter data subscription. The data is described in detail in “ZIP Code Data” on
page 35.
Installing the ZipCenter Plug-ins on the Macintosh
The ZipCenter plug-in must be installed (and de-installed) using
the ZipCenter Mac4DX Library installation method described
herein. Do not use the 4D External Mover or ResEdit to install or
remove ZipCenter.
The file ZipCenter v1.5 contains both 68K and Power Macintosh
native code, and can be used with 4th Dimension v3.2.5 or later.
For more information about 4th Dimension plug-ins, please refer
to the 4th Dimension manuals.
15
Installing and De-Installing ZipCenter
Installing ZipCenter
To Install ZipCenter in the Mac4DX Folder
The ZipCenter disk contains a file entitled ZIPCNTR.4DX. This
file contains the shared library used to install ZipCenter into your
4D database. This version can only be used with 4th Dimension
v3.2.5 or later. To install this version:
1 Create a folder inside the same folder as your 4D Structure file.
2 Make the name of this folder Mac4DX.
Note: Steps 1 and 2 are not necessary if the Mac4DX folder
already exists.
3 Drag and drop the ZipCenter v1.5 file into the folder created
in step 1.
De-Installing ZipCenter
De-Installing the Mac4DX version of ZipCenter
To de-install the Mac4DX version of ZipCenter, simply remove the
file ZIPCNTR.4DX from the Mac4DX folder.
Installing ZipCenter Under Windows
To install ZipCenter from Program Manager
1
2
3
4
Insert the ZipCenter diskette in drive A:
Choose “Run” from Program Manager's “File” menu
Type a:setup (or b:setup if the disk is in drive b:)
Follow the instructions that the setup program displays to
select a directory for ZipCenter
To install ZipCenter from the Windows 95/98 “Start”
Menu
1
2
3
4
Insert the ZipCenter diskette in drive A:
Choose “Run” from the Windows 95/98 “Start” menu
Type a:setup (or b:setup if the disk is in drive b:)
Follow the instructions that the setup program displays to
select a directory for ZipCenter
By default, Setup installs the ZipCenter files in the directory
C:\ZIPCNTR. You can change the drive and directory if necessary.
16
Installing and De-Installing ZipCenter
Using ZipCenter for Windows With Your
Database Applications
To Install ZipCenter in the WIN4DX directory, you will need the
ZIPCNTR.4DX and ZIPCNTR.RSR files. These files will be loaded
automatically by 4D if you put the files in the WIN4DX directory
under the directory containing your structure file. To do this:
1 Create a a directory named WIN4DX in the directory containing your database structure file.
2 Copy the ZIPCNTR.4DX and ZIPCNTR.RSR files to the newlycreated directory.
17
Configuration Commands
Configuration Commands
ZipCenter is configured using the commands described in this
chapter. These commands are typically called while the 4D database is opening (via the Startup procedure or On Startup
database method).
ZC_Register
ZC_Register (Mac OS Code;Windows Code) ➞ ResultCode
Parameter
Type
Description
Mac OS Code
Windows Code
Text
Text
Mac OS Registration code provided by ASG.
Windows Registration code provided by ASG.
ZC_Register will, if passed a valid registration code, remove the
demo restrictions from the ZipCenter plug-in.
ZC_Register should be called prior to issuing any of the other
ZipCenter commands.
Mac OS Code— Text. Serial number assigned by Automated Solutions Group, provided when your ZipCenter license was
purchased for Mac OS.
Windows Code— Text. Serial number assigned by Automated
Solutions Group, provided when your ZipCenter license was purchased for Windows.
ResultCode — Longint. The result is 1 if the registration code is
accepted and 0 otherwise.
Example
The following example will register ZipCenter on both platofrms
(assuming you have valid registration codes for both platforms).
$result:=ZC_Register("regcodeMac";"regcodeWin")
If ($result=0)
ALERT("ZipCenter not registered")
End if
ZC_Register
18
Configuration Commands
Note for Users of ZipCenter 1.5
The ZC_Register command changed in ZipCenter 1.6 to accept
Mac OS and Windows registration codes simultaneously. If you
are using an earlier version of ZipCenter, update the calls to
ZC_Register:
Note for Users of ZipCenter Prior to 1.5
ZipCenter registration codes and the ZC_Register changed in
ZipCenter 1.5. If you are using an earlier version of ZipCenter,
update the call to ZC_Register:
1 Contact the Automated Solutions Group Sales department to
obtain an updated registration code.
2 Use the new registration code in your call to ZC_Register.
3 Make sure that you pass only one registration code in each
call to ZC_Register. If you are using ZipCenter on both platforms call ZC_Register twice, as shown in the example
above.
4 Make sure to test the ZC_Register result code with the new
values. This table compares the result codes from the past.
Code
0
1
2
Earlier version of ZipCenter
ZipCenter 1.5 and Later
The registration code was not
The registration code was not
accepted.
accepted.
The registration codes were
The registration code was
accepted.
accepted for the Mac OS.
This result code was not returned. The registration code was
accepted for the Windows platform.
ZC_Register
19
ZipCenter Quick Lookups
ZipCenter Quick Lookups
The ZipCenter quick lookup system consists of a plug-in package
for 4th Dimension, and a special file full of 5-digit ZIP Code data.
You control the operation of ZipCenter quick lookups using plugin commands which are part of the ZipCenter package.
Understanding Quick Lookups
ZipCenter is a 5-digit ZIP Code tool. The ZIP Code data for quick
lookups is stored in an external file, not in your 4D database. This
file can be loaded onto each user’s computer for fast local lookups. The same file can be used for Windows and Mac OS without
modification.
ZipCenter Quick Lookup File Contents
The ZipCenter lookup file comes in simple and enhanced versions corresponding to the data subscription you purchased. The
following table describes the information stored with each ZIP
Code:
Field
Type
Standard
Enhanced
ZIP Code
String (5)
√
√
Latitude
Real
√
√
Longitude
Real
√
√
Primary city
String
(30)
√
√
State abbreviation
String (2)
√
√
Last modified
Date
√
√
City sequence
Longint
√
Secondary city name
String
(30)
√
County name
String
(30)
√
Acceptable
String (1)
√
County FIPS
String (3)
√
State FIPS
String (2)
√
Area Code
String (3)
√
20
ZipCenter Quick Lookups
If you have questions about the contents of any of these fields,
see “ZIP Code Data” on page 35.
Installing ZipCenter Lookup Files
You do not import or work with this file directly. Each ZipCenter
quick lookup user needs a copy of the ZipCenter lookup file on
their local hard drive. The ZipCenter plug-in commands read this
specially formatted file. You can place the ZipCenter lookup file
anywhere you like. The ZipCenter commands require a path to
the ZipCenter lookup file, but do not require you to put the file in
any specific directory. If you are using 4D Server 1.2.6 or later the
most convenient location for the ZipCenter lookup file is in the
WIN4DX directory and MAC4DX folder on the server machine.
When users connect the ZipCenter lookup file downloads
automatically.
Updating ZipCenter Lookup Files
If you have purchased a ZipCenter data subscription you will
receive new ZipCenter quick lookup files periodically. All you
need to do is replace your user’s existing files. If you are using 4D
Server’s MAC4DX and WIN4DX system the update is handled for
you automatically.
ZipCenter Quick Lookups and Local Processes
ZipCenter does not read data from your database structure when
it does a quick lookup; it reads data from a special external file.
This means that you can safely use ZipCenter quick lookups in a
local process if you do not change any data in your database. This
can improve performance significantly under 4D Server. See your
4D or 4D Server documentation for more details on local
processes.
21
ZipCenter Quick Lookups
ZipCenter Quick Lookup Commands
ZC_Lookup
ZC_Lookup (File path;Zip Code;State;City;County;Area Code;Approved;State FIPS;
County FIPS;Longitude;Latitude)➞ Result code
Parameter
Type
Description
File path
ZIP Code
State
City
†County
†Area code
†Approved
†State FIPS
†County FIPS
Longitude
Latitude
String [255]
Longint
String [2]
String [30]
String [30]
String [3]
String [1]
String [2]
String [3]
Real
Real
Path to ZipCenter lookup file.
ZIP Code to look up.
➞ State abbreviation.
➞ Primary city name.
➞ County name.
➞ Area code.
➞ USPS approved city name?
➞ State Federal Information Processing Standards code.
➞ County Federal Information Processing Standards code.
➞ Longitude of center of ZIP Code.
➞ Latitude of center of ZIP Code.
† Fields available only with the enhanced ZipCenter lookup file.
ZC_Lookup looks up a ZIP Code in the ZipCenter lookup file
located at File path. The Result code parameter returns an error
code, or a reference to additional information. The remaining
parameters receive data back from ZipCenter. You should use
process or interprocess variables for these parameters.
State returns a two character state abbreviation code.
City returns the primary city name for this ZIP Code.
County returns the primary county name for this zip code. (This
value requires the enhanced ZipCenter data.)
Area code returns the U.S. telephone area code primarily associated with this zip code. (This value requires the enhanced
ZipCenter data.)
Approved returns a one character code indicating if this city name
is approved for postal delivery. The codes are A for “Approved”
and N for “Not approved”. Primary cities are always approved.
(This value requires the enhanced ZipCenter data)
State FIPS returns a two character FIPS code. (This value requires
the enhanced ZipCenter data.)
ZC_Lookup
22
ZipCenter Quick Lookups
County FIPS returns a three character FIPS code. (This value
requires the enhanced ZipCenter data.)
Longitude returns a real number with the longitude of the
approximate center of the ZIP Code.
Latitude returns a real number with the latitude of the approximate center of the ZIP Code.
Result code can return three different kinds of values:
0<
0
>0
A negative number indicates an error of some kind.
1 means that there was no error, and that this ZIP Code
has no secondary cities.
A positive number means that there was no error, and
that there is a secondary city for this ZIP Code.
A negative result is an error code. See “ZipCenter Errors” on
page 43 for a list of error codes with descriptions.
A result of 0 indicates that there was no problem, and that there is
no secondary data.
A positive result is a reference to a secondary city entry. You
retrieve secondary city data with a call to ZC_GetMore (page 24),
and requires the enhanced ZipCenter data.
You do not need to pass the complete parameter list to
ZC_Lookup.
This example only retrieves city and sate:
C_LONGINT($ResultCode)
C_STRING (2;vsState)
C_STRING (30;vsCity)
vsState:=""
vsCity:=""
$ResultCode:=ZC_Lookup (◊vsZQPath;vlZipCode;vsState;vsCity)
This example retrieves all of the information about a ZIP Code:
C_LONGINT($ResultCode)
C_STRING (2;vsState)
C_STRING (30;vsCity)
C_STRING (30;vsCounty)
C_STRING (3;vsAreaCode)
C_STRING (1;vsApproved)
ZC_Lookup
23
ZipCenter Quick Lookups
C_STRING (2;vsStateFIPS)
C_STRING (3;vsCntyFIPS)
C_REAL (vrLongitude)
C_REAL (vrLatitude)
$ResultCode:=ZC_Lookup (◊vsZQPath;vlZipCode;vsState;vsCity;vsCounty;
vsAreaCode;vsApproved;vsStateFIPS;vsCntyFIPS;vrLongitude;vrLatitude)
ZC_GetMore
ZC_GetMore (File path;Data reference;State;City;County;Area Code;Approved;State
FIPS;County FIPS;Longitude;Latitude) ➞ Result code
Parameter
Type
Description
File path
Data reference
State
City
County
Area code
Approved
State FIPS
County FIPS
Longitude
Latitude
String [255]
Longint
String [2]
String [30]
String [30]
String [3]
String [1]
String [2]
String [3]
Real
Real
Path to ZipCenter lookup file.
ZIP Code to look up.
➞ State abbreviation.
➞ Primary city name.
➞ County name.
➞ Area code.
➞ USPS approved city name?
➞ State Federal Information Processing Standards code.
➞ County Federal Information Processing Standards code.
➞ Longitude of center of ZIP Code.
➞ Latitude of center of ZIP Code.
ZC_GetMore looks up the secondary ZIP Code entry located at
Data reference in the ZipCenter lookup file located at File path.
You obtain Data reference from an earlier call to ZC_Lookup or
ZC_GetMore. The Result code parameter returns an error code,
or a reference to additional information. The remaining parameters receive data back from ZipCenter. You should use process or
interprocess variables for these parameters. ZC_GetMore
requires the enhanced ZipCenter data.
State returns a two character state abbreviation code.
City returns the primary city name for this ZIP Code.
County returns a two character state abbreviation code.
Area code returns a two character state abbreviation code.
Approved returns a one character code indicating if this city name
is approved for postal delivery. The codes are A for “Approved”
and N for “Not approved”.
State FIPS returns a two character FIPS code.
ZC_GetMore
24
ZipCenter Quick Lookups
County FIPS returns a three character FIPS code.
Longitude returns a real number with the longitude of the
approximate center of the ZIP Code.
Latitude returns a real number with the latitude of the approximate center of the ZIP Code.
Result code can return three different kinds of values:
0 < A negative number indicates an error of some kind.
0
1 means that there was no error, and that this ZIP
Code has no more secondary cities.
>0 A positive number means that there was no error, and
that there is another secondary city for this ZIP Code.
A negative result is an error code. See “ZipCenter Errors” on
page 43 for a list of error codes with descriptions.
A result of 0 indicates that there was no problem, and that there is
no more secondary data.
A positive result is a reference to another secondary city entry.
You retrieve secondary city data with another call to
ZC_GetMore, as illustrated in the following example.
ZC_GetMore
25
ZipCenter Quick Lookups
Example:
This example only retrieves city and sate:
C_LONGINT($ResultCode)
C_STRING(2;vsState)
C_STRING(30;vsCity)
ARRAY STRING(2;asState;0)
ARRAY STRING(30;asCity;0)
vsState:=""
vsCity:=""
$ResultCode:=ZC_Lookup (◊vsZQPath;vlZipCode;vsState;vsCity)
If ($ResultCode>0)
` There are secondary cities, we'll use arrays for display.
$Element:=1
INSERT ELEMENT(asState;$Element)
INSERT ELEMENT(asCity;$Element)
asState{$Element}:=vsState
asCity{$Element}:=vsCity
Repeat
` The previous $ResultCode value is the reference to the next city for this
` ZIP Code. If there are more secondary cities, we get another reference.
` If there are no more secondary cities we get a 0 back.
$ResultCode:=ZC_GetMore (◊vsZQPath;$ResultCode;vsState;vsCity)
` Add another element to the arrays for the new city-state information.
$Element:=$Element+1
INSERT ELEMENT(asState;$Element)
INSERT ELEMENT(asCity;$Element)
` Copy the data we just got into the arrays:
asState{$Element}:=vsState
asCity{$Element}:=vsCity
Until ($ResultCode<1)
End if
ZC_GetMore
26
ZipCenter Quick Lookups
ZC_GetInfo
ZC_GetInfo (File path;Enhanced;Creation date;Version) ➞ Result code
Parameter
Type
Description
File path
Enhanced
Creation date
Version
String [255]
Longint
Date
Longint
Path to ZipCenter lookup file.
➞ Is this an enhanced lookup file?
➞ Date ZipCenter lookup file was created.
➞ ZipCenter lookup file version.
ZC_GetInfo returns information about the ZipCenter lookup file
at File path. The Result code parameter returns an error code, or
a 0 if there was no error. The remaining parameters receive data
back from ZipCenter. You should use process or interprocess variables for these parameters.
Enhanced returns a 0 if this is a standard ZipCenter lookup file,
and a 1 if this is an enhanced ZipCenter lookup file.
Creation date returns the date the ZipCenter lookup file was
created.
Version returns the ZipCenter lookup file version number.
Example:
C_LONGINT($ErrorCode)
C_LONGINT(◊vlDataType)
C_DATE(◊vdCreated)
C_LONGINT(◊vlVersion)
$ErrorCode:=ZC_GetInfo (◊vsZQPath;◊vlDataType;◊vdCreated;◊vlVersion)
ZC_GetInfo
27
ZipCenter Quick Lookups
ZC_GetInfo
28
ZipCenter Area Searches
ZipCenter Area Searches
Introduction
What Does ZipCenter Area Searching Do?
ZipCenter queries your ZIP Code table for ZIP Codes within a
given distance of a starting latitude and longitude. This finds
records based on their relative nearness. This is often the only
way to find the records you need.
With the ZipCenter area search system you can find records based
on nearness—proximity—to a central point. No other 4D search
system available provides this feature. People naturally think of
the world geographically, but computers find this less straightforward. Here are some common examples of how to use proximity
searching:
Database
Use
Hotel listings
A customer needs a hotel near downtown Minneapolis.
Find the 5 closest hotels.
Pharmacists
A patient is out of town and needs a prescription
refilled. Find the three closest pharmacies.
Customers
A sales person is held over in Houston unexpectedly for
a day. Find all of their accounts with a 50 mile radius.
Parts
A critical part is out of stock at your regular supplier, find
the next two closest suppliers.
How it Works
ZipCenter combines two precise and highly-optimized search
algorithms to locate ZIP Codes within a given radius within a true
circle. Distances are compared on the surface of the globe, rather
than in two dimensions. This distinction becomes significant if
your searches consider areas of more than a few miles. All of the
necessary calculations are performed for you automatically by
ZipCenter.
29
ZipCenter Area Searches
Required Data
ZipCenter area searches change the selection in the ZIP Code
table you identify with ZC_SetStructure. Your ZIP Code table
must contain the following fields:
Field
Data Type
Indexed
ZIP Code
String (5)
Yes
Latitude
Real
Yes
Longitude
Real
Yes
All of the data you need for 5-digit ZIP Code lookups is provided
with ZipCenter. The full contents of the ZIP Code import file is
described in “ZIP Code Data” on page 35.
Command Descriptions
ZC_SetStructure
ZC_SetStructure (ZIP Code table;ZIP Code field;Longitude field;Latitude field) ➞ Result
code
Parameter
Type
Description
ZIP Code table
ZIP Code field
Longitude field
Latitude field
Longint
Longint
Longint
Longint
Number of the ZIP Code file in the current database.
Number of the ZIP Code field in the ZIP Code file.
Number of the longitude field in the ZIP Code file.
Number of the latitude field in the ZIP Code file.
ZC_SetStructure tells ZipCenter where to look in your database
structure for ZIP Code data. The ZC_FindZips command searches
your database directly, and needs to know where to look for the
data. This command is global in scope, so you only need to call it
once.
ZIP Code table is the number of the ZIP Code table in your database structure.
ZIP Code field is the number of the ZIP Code field in the ZIP
Code file. This field must be of type string with a length of 5. This
field should be indexed for performance reasons.
ZC_SetStructure
30
ZipCenter Area Searches
Longitude field is the number of the longitude field in the ZIP
Code file. This field must be of type real. This field should be
indexed for performance reasons.
Latitude field is the number of the latitude field in the ZIP Code
file. This field must be of type real. This field should be indexed
for performance reasons.
Result code returns 0 if there was no problem, or an error code.
Error codes are listed in “ZipCenter Errors” on page 43.
This example shows a reliable way to generate the table and field
numbers you need to pass to ZC_SetStructure:
C_LONGINT($ErrorCode)
C_LONGINT($ZipTable)
C_LONGINT($ZipField)
C_LONGINT($Longitude)
C_LONGINT($Latitude)
` Get the table and field numbers needed by ZipCenter:
$ZipTable:=Table(->[ZIP_Codes])
$ZipField:=Field(->[ZIP_Codes]ZIP_Code)
$Longitude:=Field(->[ZIP_Codes]Longitude)
$Latitude:=Field(->[ZIP_Codes]Latitude)
` Tell ZipCenter which table holds your ZIP Codes, and which fields hold
` ZIP Code, longitude and latitude:
$ErrorCode:=ZC_SetStructure ($ZipTable;$ZipField;$Longitude;$Latitude)
ZC_FindZips
ZC_FindZips (Latitude;Longitude;Distance;{Search in selection}) ➞ Result code
Parameter
Type
Description
Latitude
Longitude
Distance
Search selection
Real
Real
Real
Longint
Latitude of central point in search.
Longitude of central point in search.
Distance in miles to search around central point.
{Optionally you can search the current selection in the ZIP
Code table.}
ZC_FindZips locates ZIP Codes that are within Distance of the
Latitude and Longitude you specify. This command changes the
selection in the ZIP Code table specified in ZC_SetStructure.
ZipCenter uses 3-dimensional calculations for high accuracy. This
command is optimized for performance under 4D or 4D Server.
You must call ZC_SetStructure prior to calling ZC_FindZips.
ZC_FindZips
31
ZipCenter Area Searches
Latitude is the latitude of the starting point for the search.
Longitude is the longitude of the starting point for the search.
Distance is the distance in miles you want to search from the
starting point. It is, in other words, the search radius.
Search selection allows you to search the current selection of ZIP
Codes rather than the entire table. The default behavior is to
search the entire table. Pass 1 in this parameter to search the current selection.
Result code returns 0 if there was no problem, or an error code.
Error codes are listed in “ZipCenter Errors” on page 43.
Example:
This example finds ZIP Codes within 10 miles of a starting ZIP
Code. The routine excludes all secondary cities from the query:
C_LONGINT($ErrorCode)
C_REAL($Latitude;$Longitude)
` Get the latitude and longitude of the target ZIP Code:
QUERY([ZIP_Codes];[ZIP_Codes]ZIP_Code="01778")
$Latitude:=[ZIP_Codes]Latitude
$Longitude:=[ZIP_Codes]Longitude
` Only look for primary cities, secondaries share the same lat and long.
QUERY([ZIP_Codes];[ZIP_Codes]City_sequence=1)
$ErrorCode:=ZC_FindZips ($Latitude;$Longitude;10;1)
ZC_FindZips
32
ZipCenter Area Searches
Locating Data Other Than ZIP Codes
ZipCenter queries ZIP Codes, but you may want to find customers, suppliers, or other records that use ZIP Codes. Starting from
the selection of ZIP Codes you can find records in any other table
in your database. If, for example, your customer’s table includes
5-digit ZIP Codes here’s how to find all customer’s within 20 miles
of the ZIP Code 95014:
1 Make sure that you’ve called ZC_SetStructure to identify
where your ZIP Code data is stored.
2 Call ZC_FindZips to find all ZIP Codes within 20 miles of ZIP
Code 95014.
3 Use the selection of ZIP Codes to find all customers within 20
miles of 95014.
You can perform step three with built-in 4D commands if you
have a relationship between the ZIP Code table and the customer’s table. Here are the names of the commands to consider in
4D V3 and 4D V6:
V3
V6
PROJECT SELECTION
RELATE MANY SELECTION
JOIN
RELATE ONE SELECTION
A more flexible alternative is to use the Free Join routine found in
the ZipCenter example database. This routine replaces the 4D
commands listed above, and does not require relations between
your tables.
ZC_FindZips
33
Distance Commands
Distance Commands
ZipCenter includes a command that calculates the distance
between any two latitude-longitude pairs. These calculations are
performed using 3-dimensional geometry for high accuracy
results.
ZC_MilesApart
ZC_MilesApart (Latitude1;Longitude1;Latitude2;Longitude2) ➞ Distance
Parameter
Type
Description
Latitude1
Longitude1
Latitude2
Longitude2
Real
Real
Real
Real
Latitude of first point.
Longitude of first point.
Latitude of second point.
Longitude of second point.
ZC_MilesApart calculates the distance between two points, and
returns the result in miles. You can obtain latitude and longitude
coordinates from any source, including the ZipCenter lookup file,
or the ZIP Code import data supplied with ZipCenter.
ZC_MilesApart uses 3-dimensional geometry for high precision
results.
Latitude1 is the latitude of the first point.
Longitude1 is the longitude of the first point.
Latitude2 is the latitude of the second point.
Longitude2 is the longitude of the second point.
Distance is the distance between the points in miles. The example
database includes routines to convert miles to kilometers.
This example calculates the distance between two ZIP Codes:
C_REAL ($Lat1;$Long1;$Lat2;$Long2;$Distance)
QUERY([ZIP_Codes];[ZIP_Codes]ZIP_Code="01778")
$Lat1:=[ZIP_Codes]Latitude
$Long1:=[ZIP_Codes]Longitude
QUERY([ZIP_Codes];[ZIP_Codes]ZIP_Code="95060")
$Lat1:=[ZIP_Codes]Latitude
$Long1:=[ZIP_Codes]Longitude
$Distance:=ZC_MilesApart ($Lat1;$Long1;$Latitude_2;$Longitude_2)
ZC_MilesApart
34
ZIP Code Data
ZIP Code Data
Introduction
ZipCenter includes two different files with ZIP Code data:
◆
A ZipCenter lookup file designed exclusively for use with the
ZipCenter plug-in commands.
◆
A text file with 5-digit ZIP Code data needed for ZipCenter
area searches. This file includes additional useful ZIP Code
information.
Each of these files comes in two versions: standard and enhanced.
The file you have depends on the ZipCenter data subscription
option you purchased. This chapter describes the contents of
these files, and explains what each item is for.
ZIP Code Data: Standard
The standard version of the ZipCenter data includes roughly
43,000 records. The file contains the following information about
each 5-digit ZIP Code:
Field
Type
Notes
ZIP Code
String (5)
Each ZIP Code is unique.
Latitude
Real
The approximate latitude of the center of
the ZIP Code.
Longitude
Real
The approximate longitude of the center
of the ZIP Code.
Last modified
Date
The date ASG last updated this data.
Primary city
String (30)
Name of primary city associated with this
ZIP Code.
State abbreviation
String (2)
The approximate latitude of the center of
the ZIP Code.
A few of these fields deserve a bit of explanation.
35
ZIP Code Data
Latitude and Longitude
The latitude and longitude measurements included with each ZIP
Code are called a ‘centroid’ measurement. ZIP Codes cover areas
of different sizes and shapes. The latitude and longitude are for a
calculated central point.
4D Table Structure for Area Searches
You can import this data into whatever 4D table structure you
like. This table describes which fields are necessary for area
searches, which need indexes, and what data type to use:
Field
Type
Indexed
Unique
Necessary
ZIP Code
String (5)
√
√
√
Latitude
Real
√
√
Longitude
Real
√
√
Last modified
Date
√
Primary city
String (30)
State abbreviation
String (2)
36
ZIP Code Data
ZIP Code Data: Enhanced
The enhanced version of the ZipCenter data contains roughly
52,000 records. This file includes all of the data found in the standard version, as well as these additional fields:
Field
Type
Notes
City sequence
Longint
Distinguishes primary cities from all secondary cities.
County name
String (30)
The name of the county name associated
with this ZIP Code and city.
Acceptable
String (1)
Is this city name acceptable to the U.S.P.S.?
County FIPS
String (3)
The FIPS code for this county.
State FIPS
String (2)
The FIPS code for this state.
Area Code
String (3)
The area code for this ZIP Code.
City FIPSa
String (5)
The FIPS code for this city.
MSA Codea
Longint
Metropolitan Statistical Area code
Time Zonea
Longint
number of hours from GMT
DSTa
String (1)
'Y' if the area observes Daylight Savings
Time
a. These fields are at this time only available in the ASCII-text file version of
the Enhanced Data file.
A few of these fields deserve a bit of explanation.
City Sequence
ZIP Codes can cross city and county lines. The standard data set
includes the ‘primary’ city. The enhanced data set includes entries
for the primary, as well as any known secondary cities. A single
ZIP Code may have as many as 14 secondary cities. The primary
city has a city sequence number of 1.
Acceptable
Some secondary city names are commonly used local names not
recognized by the U.S.P.S. People may give you an unacceptable
secondary city name as their mailing address. WIth the ZipCenter
data you can locate cities as people call them, and address them
as the Post Office expects.
37
ZIP Code Data
City, State and County FIPS Codes
What is a FIPS code, and why would you care? FIPS stands for
Federal Information Processing Standards (but you knew that).
FIPS is a National Institute of Standards and Technology program
to achieve compatibility and interchangeability among data systems. Many useful data products from commercial and
government sources include FIPS codes. You can, for example,
purchase data that describes the average income and education
level associated with each county FIPS code. If you do not intend
to work with other data sets, you normally do not need the FIPS
codes in your database.
These codes may not be available for APO, FPO and some U.S.
Territories.
MSA Codes
MSA stands for Metropolitan Statistical Area codes. They define
greater metopolitan areas, such as the greater Miami area. Not all
zip codes have an MSA code because many zip codes are in rural
areas
Time Zone
U.S. time zones are expressed here in a standard format which is
the number of hours from Greenwich Mean Time (GMT). West of
GMT is negative and so all U.S. records have negative numbers.
The numbers range from -5 (Eastern Standard Time) to -10
(Hawaii).
Daylight Savings time
'Y' if the area observes Daylight Savings Time and 'N' if it doesn't
4D Table Structure for Area Searches
The ZipCenter database and import file use a flat-file format to
deliver the data. They do not use a relationally correct structure.
This table describes which fields are necessary for area searches,
which need indexes, and what data type to use:
Field
Type
Indexed
Unique
Necessary
ZIP Code
String (5)
√
√
√
Latitude
Real
√
√
Longitude
Real
√
√
38
ZIP Code Data
Field
Type
Indexed
Primary city
String (30)
State abbreviation
String (2)
City sequence
Longint
County name
String (30)
Acceptable
String (1)
County FIPS
String (3)
State FIPS
String (2)
Area Code
String (3)
Unique
Necessary
√
√
If you want to normalize this data in your system here is a formal
description of the tables you need, followed by a picture of a 4D
implementation.
ZIP Code Table
Field
Type
Keys
ZIP Code
String (5)
Primary key
Latitude
Real
Longitude
Real
State abbreviation
String (2)
Area code
String (3)
Foreign key: State table
County Table
Field
Type
Keys
County FIPS
String (2)
Primary key
County name
String (30)
State Table
Field
Type
Keys
State FIPS
String (2)
Primary key
State name
String (2)
39
ZIP Code Data
ZIP Codes and Cities Table
Field
Type
Keys
ZIP Code
String (5)
Primary key, part 1
Foreign key: ZIP Code table
City sequence
Longint
Primary key, part 2
City name
String (30)
County FIPS
String (3)
Acceptable
String (1)
Last modified
Date
Foreign key: County table
Here is one way to implement this in 4D:
Zip Center Lookup File Contents
The ZipCenter lookup file comes in standard and enhanced versions corresponding to the product you purchased. The contents
of the ZipCenter lookup file are the same as the flat-file import
file. The following table describes the information stored with
each ZIP Code:
Field
Type
Standard
Enhanced
ZIP Code
String (5)
√
√
Latitude
Real
√
√
Longitude
Real
√
√
Primary city
String (30)
√
√
State abbreviation
String (2)
√
√
Last modified
Date
√
√
40
ZIP Code Data
Field
Type
Standard
Enhanced
City sequence
Longint
√
Secondary city name
String (30)
√
County name
String (30)
√
Acceptable
String (1)
√
County FIPS
String (3)
√
State FIPS
String (2)
√
Area Code
String (3)
√
41
Troubleshooting
Troubleshooting
This chapter lists several common problems, and their solutions,
encountered when working with ZipCenter.
When trouble-shooting a problem, use all of the tools at your disposal, including the 4D debug window. Many problems can be
quickly resolved by stepping through each line of code, and
checking the values of variables and arrays.
Quick Lookups
When I try to do a quick lookup, I get error -93 back from ZipCenter.
Error -93 indicates that the ZIP Code could not be found in the
ZipCenter lookup file. This happens when the ZIP Code does not
exist, or when you haven’t selected a ZipCenter lookup file. Make
sure that you have selected a ZipCenter lookup file.
Serial Numbers
My ZipCenter serial number doesn’t work.
Make sure that you have entered the serial number exactly as it
was provided. It’s easy to confuse characters like 0 (zero) and O
(the letter O). If you received your serial number via email, cut
and paste it into your 4D procedure or view it in a serif font that
will more easily display the differences between characters. Also,
all serial numbers follow the format “xxx-nnnnn-nnnn”, where x
represents an alphabetic character (A-Z and a-z) and the n represents a numeral (0-9). Serial numbers will never place alphabetic
characters in the areas indicated as numbers, or vice-versa. Serial
numbers are case-sensitive.
Sometimes my serial number works, other times I’m told I’m
in demo mode.
The ZipCenter plug-ins go into demo mode automatically after
your database has been running for 10 minutes. To avoid this call
“ZC_Register” once at startup. Call this command before calling
any other ZipCenter command.
42
ZipCenter Errors
ZipCenter Errors
The following table explains the error codes that ZipCenter may
return.
Error
-99
-98
-97
-96
-95
-94
-93
-92
-91
-90
-89
-88
-87
-86
Description
File may be locked or volume full.
File not found.
File system error.
File input-output error.
Internal 4D error.
Bad structure preference settings.
ZIP Code not found.
Memory error.
File input-output error.
Secondary data not available for passed reference. You
need the enhanced ZipCenter lookup file.
General exception.
Opened with unmatched version of data file.
Need to set preferences with ZC_SetStructure
A bad file reference passed to ZC_SetStructure
43
Technical Support
Technical Support
Automated Solutions Group provides free technical support for all
registered users via electronic mail, telephone or standard mail.
Primary support is offered via electronic mail.
Electronic Mail
support@asgsoft.com US Customers
World Wide Web
http://www.asgsoft.com
ftp://ftp.asgsoft.com
Our WWW server provides a variety of additional information,
including FAQ's (Frequently Asked Questions) and our exclusive
Technical Notes as well as demo versions of other Automated
Solutions Group products.
44
ZipCenter Demo
ZipCenter Demo
Introduction
Use the ZipCenter Demo database to experiment with ZipCenter’s
various features. Feel free to use any of the procedures in your
own code; there are several useful routines included.
Once you purchase ZipCenter, you can use ZC_Register
(page 18) to register the use of the ZipCenter external within the
demo database. Until you do this, the external will run in demo
mode, which means that after ten minutes, it will time-out, and
you’ll have to relaunch the database in order to continue using
the demo.
Overview
The ZipCenter demonstration database examples illustrate how
ZipCenter works, and provide useful 4D code for use in your systems. Every command and feature in ZipCenter is illustrated in the
example database. There are five demonstration areas in the
database:
45
ZipCenter Demo
ZipCenter Quick Lookup
This demonstration uses ZC_Lookup and ZC_GetMore to look
up ZIP Codes in a ZipCenter lookup file.
46
ZipCenter Demo
You can set the path to the ZipCenter lookup file at any time by
selecting Pick Lookup FIle from the File menu.
Zip Center Area Search
The area search demo uses ZC_FindZips to locate ZIP Codes
within a given radius of a starting ZIP Code. The system automatically finds customers with matching ZIP Codes.
Optionally you can ask the system to show the distance between
the starting ZIP Code and each matching ZIP Code.
Distance Calculator
The distance calculator uses the ZC_MilesApart command to calculate the distance between two ZIP Codes.
47
ZipCenter Demo
48
ZipCenter Demo
Edit Customers
The edit customers demonstration lets you view and edit customer records. The ZIP Code field on the input form uses
ZC_Lookup to find a ZIP Code’s primary city and state.
49
ZipCenter Demo
View ZIP Codes
The view ZIP Codes demonstration displays the ZIP Codes in the
database for your convenience.
50
ZipCenter Command Reference — by Chapter
SOFTWARE LICENSE AND LIMIMTED WARRANTY................................................. 4
ZIPCENTER DATA FILE LICENSE AND
LIMITED WARRANTY................................................................................................... 6
Table of Contents...................................................................................................... viii
Using the ZipCenter Manual ..................................................................................... 10
About ZipCenter......................................................................................................... 12
Installing and De-Installing ZipCenter ..................................................................... 15
Configuration Commands......................................................................................... 18
ZC_Register (RegistrationCode) ➞ ResultCode ........................................................................................................................................................... 18
ZipCenter Quick Lookups ......................................................................................... 20
ZC_Lookup (File path;Zip Code;State;City;County;Area Code;Approved;State FIPS; County FIPS;Longitude;Latitude)➞ Result code..................... 22
ZC_GetMore (File path;Data reference;State;City;County;Area Code;Approved;State FIPS;County FIPS;Longitude;Latitude) ➞ Result code.......... 24
ZC_GetInfo (File path;Enhanced;Creation date;Version) ➞ Result code...................................................................................................................... 27
ZipCenter Area Searches .......................................................................................... 29
ZC_SetStructure (ZIP Code table;ZIP Code field;Longitude field;Latitude field) ➞ Result code.................................................................................. 30
ZC_FindZips (Latitude;Longitude;Distance;{Search in selection}) ➞ Result code........................................................................................................ 31
Distance Commands ................................................................................................. 34
ZC_MilesApart (Latitude1;Longitude1;Latitude2;Longitude2) ➞ Distance ................................................................................................................... 34
ZIP Code Data............................................................................................................. 35
Troubleshooting......................................................................................................... 42
ZipCenter Errors ........................................................................................................ 43
Technical Support...................................................................................................... 44
ZipCenter Demo ......................................................................................................... 45
ZipCenter Command Reference — by Chapter....................................................... 51
ZipCenter Command Reference — Alphabetical .................................................... 52
ZipCenter Command Reference — Alphabetical
ZC_Register (RegistrationCode) ➞ ResultCode ........................................................................................................................................................... 18
ZC_Lookup (File path;Zip Code;State;City;County;Area Code;Approved;State FIPS; County FIPS;Longitude;Latitude)➞ Result code..................... 22
ZC_GetMore (File path;Data reference;State;City;County;Area Code;Approved;State FIPS;County FIPS;Longitude;Latitude) ➞ Result code.......... 24
ZC_GetInfo (File path;Enhanced;Creation date;Version) ➞ Result code...................................................................................................................... 27
ZC_SetStructure (ZIP Code table;ZIP Code field;Longitude field;Latitude field) ➞ Result code.................................................................................. 30
ZC_FindZips (Latitude;Longitude;Distance;{Search in selection}) ➞ Result code........................................................................................................ 31
ZC_MilesApart (Latitude1;Longitude1;Latitude2;Longitude2) ➞ Distance ................................................................................................................... 34
Index
Numerics
4D Server
performance 12, 21
4th Dimension
v3.2.5 15
A
Acceptable
defined 37
Adobe Acrobat Reader 10
Area searches
about 12
defined 13, 29
demo 47
required data 30
uses 13
C
Windows 17
Installing ZipCenter
Mac4DX library 15
Mac4DX version 16
Interprocess variables 11
J
JOIN 12, 33
L
Local variables
as external parameters 11
M
Mac4DX 16
Mac4DX library
installing ZipCenter into 15
City sequence
defined 37
Command syntax 11
Configuring ZipCenter 18
O
D
Parameters 11
using local variables 11
Parenthesis
enclosing parameters 11
PDF 10
Power Macintosh 15
Process variables 11
Program Manager 16
PROJECT SELECTION 12, 33
Proximity searches
defined 29
demo 47
required data 30
uses 13
Proximity searching
defined 13
Proxmity searches
about 12
Deinstalling ZipCenter
Mac4DX version 16
Demos
area searches 47
ZC_FindZips 47
ZC_Lookup 46, 49
ZC_MilesApart 47
ZipCenter quick lookups 49
ZQ_GetMore 46
E
Example code
ZC_FindZips 32
ZC_GetInfo 27
ZC_GetMore 26
ZC_Lookup 23
ZC_MilesApart 34
ZC_SetStructure 31
F
FIPS codes
defined 38
I
Installing
On Startup 18
P
Q
Quick lookup
data 15
Quick lookups
advantages 13
data 20
defined 20
demo 49
installation 21
I-53
Index
updating the data 21
R
Registration 18
RELATE MANY SELECTION 12, 33
RELATE ONE SELECTION 12, 33
S
Semicolons
separating parameters 11
Serial number 18
Startup procedure 18
Syntax 11
V
Variables
interprocess 11
local 11
process 11
W
Windows
installing ZipCenter 17
Z
ZC_FindZips
defined 31
demo 47
example code 32
ZC_GetInfo
defined 27
example code 27
ZC_GetMore
defined 24
demo 46
example code 26
ZC_Lookup
demo 46, 49
example code 23
ZC_MilesApart
defined 34
demo 47
example code 34
ZC_Register 45
defined 18
description 18
ZC_SetStructure
defined 30
example 31
ZIP Code data
about 12, 14–15
acceptable 37
city sequence 37
defined 35
enhanced 37
FIPS codes 38
latitude and longitude 36
standard 35
viewing 50
ZipCenter 45
about 15
configuring 18
contents 10
error codes 43
installing 15
requirements 14
ZipCenter area searches
about 12
defined 13, 29
demo 47
required data 30
uses 13
ZipCenter quick lookup
data 15
ZipCenter quick lookups
about 12
advantages 13
data 20
defined 20
demo 49
installation 21
updating the data 21
I-54
Download PDF