This series of 9 COBOL programs demonstrates the following
features of the COBOL language and how to use them.

1)  Reading CSV files and providing a hex dump of
    records (worldcities0)
2)  Writing CSV files (worldicites6)
3)  Inserting data into a SQL database (worldcities5)
4)  Fetching data from a SQL database (worldcities6)
5)  Loading and searching a reference table (worldcities1)
6)  Consistent use of subscript maximum and limit values
    (worldcities1 and others)
7)  Reporting common performance information, such as
    records read, elapsed time, records per second    
    (worldcities0 and others)
8)  Using a common print reporting structure
    for consistent printer movement and for widow
    and orphan control (worldcities2 and others) 
9)  Writing run statistics and error messages to
    a run report file (worldcities2 and others)
10) Defining a report as a collection of vertical
    strips for ease of development and maintenance
    (worldcities2 and others)
11) Compiling common subroutines in a separate module
    (worldcities3 and others)
12) Creating reports by adding to existing reports
    in a common file for overall batch control
    (worldcities2 and others)
13) Documenting a common COBOL development error
    (mine) and showing a correction (worldcities4)
15) Working with latitude and longitude data
    (worldcities4 and others)
16) Writing a google earth kml file (worldcities6)
17) Reading a google earth kml file (worldcities7)
19) Using a COBOL screen to capture parameters 
    and to interface with external utilities
    (worldcities8)
20) Use and misuse of the SORT verb (worldcities2)
21) Various techniques to incorporate external
    parameters:  chaining, accept, call SYSTEM.
22) Active techtonics generating command files.

Each program in the series has a corresponding
worldcities#.sh command file and there is a
all.sh command file to run the entire series

These command files, and the all.sh command file
are generated by createcommandfiles.sh

change rm run-file and rm report-file to
#rm run-file and #rm report-file after the first
instance of rm run-file and rm report-file and
change the lpr commands to #lpr
before the last two instances of lpr
in the all.sh command file to generate a combined
batch run report

All command files assume a directory named
'worldcityfiles' under the $HOME path.

The worldcityfiles directory will hold the CSV
files you download from
http://download.geonames.org/export/dump/

This $HOME/worldcitiesfile directory will also hold
the kml polygon files you create in google-earth.

Creating these kml files is somewhat obscure, so the
current directory (the one containing this README file)
has some sample kml polygon files.  Move these kml
polygon files to the $HOME/worldcitiesfile directory

Here's a list of the programs and the progressive
modifications

worldcities0
*> =============================================
*> 1) read a CSV file and create some run counts
*> =============================================

worldcities1
*> ================================================
*> modify worldcities0.cbl

*> 1) add a country lookup table
*> 2) move checkfilestatus to a copylib
*> ================================================

worldcities2
*> ============================================================
*> modify worldcities1.cbl
*>
*> 1) move the run count displays to a run print file
*> 2) move the country displays to a report print file
*> 3) define the report columns and headings in vertical strips
*> 4) use a common report printing structure
*> ============================================================

worldcities3
*>=============================================================
*>  modify worldcities2.cbl
*>
*>  1) select cities in a given continent
*>  2) show the top 3 cities by population in each country
*>  3) check for an end of page widow when printing the report 
*>  4) move checkfilestatus and printrunreport to a common
*>     source file
*>
*>     the idea of printing a runfile is that every (batch)
*>     cobol program needs to report run statistics, comments
*>     and possibly error messages in a runfile rather than
*>     to stdlist.
*>
*>     note that run-file is written OPEN EXTEND, so
*>     a single file can hold a series of run-reports
*>
*>     we define a 'universal' runreport subprogram to
*>     create this 'common' runfile usable by any (batch)
*>     cobol program.
*>
*>     we don't do the same for an application report-file,
*>     although its programming has a similar structure,
*>     because its variable headings and lines make it hard to
*>     standardize.
*>
*>  5) See the comment in the procedure division about my COBOL
*>     design error and its correction.
*>=============================================================

worldcities4
*>==================================================
*> modify worldcities3
*>
*> select cities with latitude/longitude
*> in a hard-coded polygon

*> www.distancesfrom.com will help you find polygon
*> latitudes and longitudes
*>==================================================

worldcities5
*>==================================================
*> modify worldcities4
*>
*> write selected records to a postgresql table
*>==================================================

worldcities6
*>==================================================
*> modify worldcities5
*>
*> 1)  read a postgresql table
*> 2)  create a kml file for google-earth
*>==================================================

worldcities7
*>==================================================
*> modify worldcities6
*>
*> 1)  read a google-earth polygon.kml file
*>
*> this version removes the ocesql/postgresql code
*>==================================================

worldcities8
*>==================================================
*> modify worldcities7
*>
*> 1)  use a screen to select polygon files,
*>     worldcity files, and feature-classes
*> 2)  show all feature-classes
*>==================================================

