Release Date: 8/7/25
Version: 8.5 and Above
The utility program SYDSTCAL.CBL is used to calculate the distance between two zip codes. To calculate the distance
between two ZIP codes using latitude and longitude (from their geographic
centers), the simplest trigonometric method is the Haversine formula.
It gives you the great-circle distance between two points on the Earth's
surface, accounting for the Earth's curvature. This calculation uses intrinsic functions to determine the distance. This requires the following compiler directive located in the first line of the program.
$SET ADDRSV "FUNCTION"
Note: Removal of this line or changes to this line will cause a compilation error.
The program uses the following linkage:
01 SYDSTCAL-VALUES.
03 SYDSTCAL-MODE PIC X(1).
03 SYDSTCAL-MILES-OR-KILOMETERS PIC X(1).
03 SYDSTCAL-PRIM-LOC-ZIP-CODE PIC X(5).
03 SYDSTCAL-LOCATIONS-TABLE.
05 SYDSTCAL-LOCATIONS OCCURS 100 TIMES.
07 SYDSTCAL-TABLE-NAME PIC X(8).
07 SYDSTCAL-REF-VALUE PIC X(30).
07 SYDSTCAL-ZIP-CODE PIC X(5).
07 SYDSTCAL-DISTANCE PIC S9(5)V9999.
03 SYDSTCAL-OPEN-STATUS PIC X(1).
SYDSTCAL-MODE - 1=Open File, 2=Close Files, 3=Calculate
SYDSTCAL-MILES-OR-KILOMETERS - K=Kilometers, M=Miles (default is miles)
SYDSTCAL-PRIM-LOC-ZIP-CODE - Primary location for the distance comparison.
SYDSTCAL-LOCATIONS (supports up to 100 entries)
SYDSTCAL-TABLE-NAME - Table name where the comparison zip code originated such as IMLOCFIL
SYDSTCAL-REF-VALUE - Reference value of the primary location such as the LOCATION-CODE from IMLOCFIL
SYDSTCAL-ZIP-CODE - Zip code used to compute the distance
SYDSTCAL-DISTANCE - Calculated distance returned by the program
SYDSTCAL-OPEN-STATUS - Indicates if the opening procedure in SYDSTCAL was successful
Normal Use of this Program
- Call SYDSTCAL in the opening procedure of the program with the mode set to "1." This will perform the opening procedure in SYDSTCAL and set local working storage variable in the program indicating if the opening procedure was successful. The variable SYDSTCAL-OPEN-STATUS is also set and returned back to the calling program. If this flag is set to "N," the OPENING-PROCEDURE-STATUS should be set to UNSUCCESSFUL.
- Call SYDSTCAL with the mode set to "3" during normal processing to calculate and return the distance for all of the provided zip codes.
- Call SYDSTCAL in the closing procedure of the program with the mode set to "2." This will perform the closing procedure in SYDSTCAL and set the local working storage variable in the program indicating that the closing procedure was performed. After the program returns, it should be cancelled in the closing procedure.
SYZIPCDS Table
This program uses the latitude and longitude provided in the table SYZIPCDS to calculate the distance between two zip codes. The maintenance of this table can be found in Elliott -> System Utilities -> Zip Code File. The latest SYZIPCDS.BTR table is installed in the <ElliottRoot> directory, while the versions in the DATA* folders may not be up to date. Therefore, we provide a Synchronize utility to synchronize the SYZIPCDS.BTR table in <ElliottRoot> with the corresponding tables in the <ElliottRoot>\DATA* folders. If the multi-company feature is used, you will need to perform this synchronization on a company-by-company basis. Since the SYZIPCDS.BTR file in the <ElliottRoot>\DATA* folders may be modified by you, it is better to use the Synchronize utility rather than performing a direct copy from the <ElliottRoot> folder.
What If A Provided Zip Code Does Not
Exist in our Zip Code Table?
Our distance calculation is
based on the 5-digit zip code. Various Elliott tables support a 10-digit zip cope but this program only uses the first 5 digits. It is possible a
new 5-digit zip code does not exist in our database. In that case, the program will use first 4 digits of the zip code to start and find the closest zip code. For
example, if zip code 91788 does not exist in the zip code table, then the application will
read all of the zip codes starting with 9178 to find zip codes between 91780 and 91789. The
closest lower zip codes will be used. That is to say, if 91780, 91782, 91784,
91785, 91789 exist, the application will use 91789 for the distance calculation because it is the closest (off by 1, vs. 91785 which is off by 3). On the other hand, if both 91787 and 91789 are
found, then we will use 91787 because it is off by 1, and it is the lower zip
code instead of 91789 which is the higher zip code. If no zip codes are found within the 4-digits zip code, then the application will try with the first 3 digits of the provided zip code (e.g., 917 in this example). If there are no zip codes found for 917* in the zip codes database, then it is
an error condition. This applies to either the primary (SYDSTCAL-PRIM-LOC-ZIP-CODE) or the list of potential location zip codes (SYDSTCAL-ZIP-CODE). In that case, the application will return a distance of 99999.9999 back, which is the maximum value. Also, if the zip code is less than 5 digits it is an error condition, and the application will return the value 99999.9999 as well.
This makes sure this entry will not be used.
Programs Added: SYDSTCAL.CBL, SYDSTCAL.WS
CLS