Provided by: libncarg-dev_6.6.2.dfsg.1-2_amd64 
NAME
EZMAP - Allows one to plot maps of the earth according to any of ten different
projections, with parallels, meridians, and continental, international, and/or U.S. state
outlines.
EZMAPA is the name of a supplement to the EZMAP utility that allows users to produce
solid-filled maps of the earth. The EZMAPA routines are discussed as part of the EZMAP
utility.
EZMAPB is the name of a supplement to the EZMAP utility that provides access to improved
map databases (principally one called "Earth..1", which contains a unified higher-
resolution version of everything that was in the old outline datasets). The EZMAPB
routines are discussed as part of the EZMAP utility.
SYNOPSIS
Routines Used to Draw a Simple Map
To draw the simple map defined by the current values of EZMAP's internal parameters
(assuming no area fills and no access to the new, improved, map database
"Earth..1", which was created in 1998), one need only execute the single FORTRAN
statement "CALL MAPDRW":
• MAPDRW - Draws a complete simple map.
All that MAPDRW does is call four lower-level routines. In some situations, the
user may wish to call these routines directly; they are as follows (in the order in
which they are called by MAPDRW):
• MAPINT - Initializes. MAPINT must be called at least once before calling any
routine that depends on mapping lat/lon coordinates into u/v coordinates. After
one or more of MAPPOS, MAPROJ, and MAPSET has been called, MAPINT must be
called again. MAPINT does the call to the SPPS routine SET that defines the
mapping from the u/v (projection) plane to the x/y (plotter) plane.
• MAPGRD - Draws selected parallels and meridians.
• MAPLBL - Labels the international date line, the equator, the Greenwich
meridian, and the poles, and draws the perimeter.
• MAPLOT - Draws selected geographic outlines. Note that this routine uses
whichever old outline dataset is selected by the value of the internal
parameter 'OU'; to access the new map database "Earth..1", which was created in
1998, one must call instead the EZMAPB routine MPLNDR.
Routines Used to Change the Values of Internal Parameters
The following routines are called to change the values of internal parameters of
EZMAP, and thus change the behavior of other EZMAP routines:
• MAPPOS - Determines what portion of the plotter frame is to be used.
• MAPROJ - Determines the projection to be used.
• MAPSET - Determines what portion of the u/v plane is to be viewed.
• MAPSTC - Sets a parameter value of type CHARACTER.
• MAPSTI - Sets a parameter value of type INTEGER.
• MAPSTL - Sets a parameter value of type LOGICAL.
• MAPSTR - Sets a parameter value of type REAL.
Routines Used to Retrieve the Values of Internal Parameters
The following routines are used to retrieve the current values of EZMAP parameters:
• MAPGTC - Gets a parameter value of type CHARACTER.
• MAPGTI - Gets a parameter value of type INTEGER.
• MAPGTL - Gets a parameter value of type LOGICAL.
• MAPGTR - Gets a parameter value of type REAL.
Routines Used to Save and Restore Internal Parameters
To save/restore the current values of the internal parameters of EZMAP, use the
following:
• MAPSAV - Saves the values (by writing a record on a user-specified unit).
• MAPRST - Restores saved values (by reading a record from a user-specified
unit).
Routines Used to Draw Objects on a Map
To draw objects on the map, use the following routines:
• MAPTRA - Computes the u/v coordinates of a point from its latitude and
longitude. If the point is unprojectable or its projection lies outside the
current perimeter, a special value is returned to signal this.
• MAPTRN - Computes the u/v coordinates of a point from its latitude and
longitude. If the point is unprojectable, a special value is returned to signal
this, but no check is made for the projected value being outside the perimeter.
• MAPFST - Does a "pen-up" move defining the start of a line to be projected and
drawn. The line is defined by a series of lat/lon coordinates.
• MAPVEC - Does a "pen-down" move defining the continuation of a line to be
projected and drawn. The line is defined by a series of lat/lon coordinates.
• MAPIT - Does "pen-up" or "pen-down" moves. This routine is called by MAPFST and
MAPVEC.
• MAPIQ - Signals the end of a string of calls to MAPIT and causes its buffers to
be flushed.
• MAPGCI - Given the latitudes and longitudes of two points on the surface of the
globe, this routine returns the latitudes and longitudes of a specified number
of points along the great circle route joining them.
Routines Used to Do Inverse Transformations
The following routine was added to EZMAP early in 1992:
• MAPTRI - Computes the latitude and longitude of a point from its u/v
coordinates. If the point is outside the boundary of the map, a special value
is returned.
The example named "mpex10" shows one of the ways in which this routine may be used;
it draws what is essentially a colored contour plot of a data field defined on the
surface of the globe, using an orthographic projection.
Routines Used to Draw Solid-Filled Maps (EZMAPA)
In late 1986 or early 1987, a package of routines was written allowing a user to
draw solid-filled maps of the globe. This package was named EZMAPA and was first
advertised in the NCAR Graphics User's Guide (Version 2.00), published in August,
1987. Conceptually, the routines in this package are really part of EZMAP; they use
the same common blocks and many of the same underlying low-level routines and they
are affected by the same set of internal parameters as the routines in EZMAP
proper. The routines of EZMAPA will be described in this document; to use them
effectively, it will be necessary to understand also the package AREAS, which is
described in a separate document. The EZMAPA routines are as follows:
• MAPBLA - Adds boundary lines to an existing area map. Routines in the package
AREAS may then be used to process that area map in various ways. (Example:
drawing a map of Europe with each country in a different color.) Note that
this routine uses whichever old outline dataset is selected by the value of the
internal parameter 'OU'; to access the new map database "Earth..1", which was
created in 1998, one must call instead the EZMAPB routine MPLNAM.
• MAPBLM - Draws boundary lines "masked" by an existing area map. (Example:
drawing these lines only where they do not overlay CONPACK labels.) Note that
this routine uses whichever old outline dataset is selected by the value of the
internal parameter 'OU'; to access the new map database "Earth..1", which was
created in 1998, one must call instead the EZMAPB routine MPLNDM.
• MAPGRM - Draws lines of latitude and longitude "masked" by an existing area
map. (Example: drawing these lines over water, but not over land.)
• MAPITA and MAPIQA - Adds to an area map the projections of arbitrary lines
defined by lat/lon coordinates of points on the surface of the globe. MAPBLA
uses these routines to add boundary lines to an area map; they may be called
directly by the user to add his/her own set of boundary lines to the area map.
• MAPITM and MAPIQM - Draws, masked by an area map, the projections of arbitrary
lines defined by lat/lon coordinates of points on the surface of the globe.
MAPGRM uses these routines to draw masked lines of latitude and longitude; they
may be called directly by the user to draw other masked lines.
• MAPACI - A function which, given the "area identifier" for a particular area
defined by the boundaries in one of the old EZMAP outline datasets, returns a
suggested color index for that area; it is guaranteed that, if the suggested
color indices are used, no two areas having a boundary in common will have the
same color. Note that this function should not be used to select color indices
for areas defined by the new map database "Earth..1", which was created in
1998; for that purpose, use EZMAPB functions instead (in particular, MPISCI).
Routines Used to Access New Datasets (EZMAPB)
In early 1998, a new world map database, called "Earth..1", was created for use
with EZMAP; this database has higher-resolution coastlines, it has been updated to
reflect many of the political changes that have taken place over the years since
EZMAP came into existence, and it is structured differently, allowing for greater
flexibility and ease of use and providing for easier changes and extensions in the
future.
Each area defined by the database has 1) a "area identifier" (an integer uniquely
identifying it), 2) an "area type" specifying its level in a hierarchy of areas, 3)
a suggested color index, 4) an area identifier specifying its "parent" area (the
area of which it is a part), and 5) a name. For example, there is an area named
"Madeline Island" which is of type 4 (used for a state or a portion thereof) and
has suggested color index 6. Its parent is an area named "Wisconsin", which is
also of type 4 and has suggested color index 6. The parent of "Wisconsin" is
"Conterminous US", which is of type 3 (used for a country or a portion thereof) and
has suggested color index 3. The parent of "Conterminous US" is "United States",
which is also of type 3 and has suggested color index 3. The parent of "United
States" is "North America", which is of type 2 and has suggested color index 5.
The parent of "North America" is "Land", which is of type 1 and has suggested color
index 2. The area named "Land" is at the top of the hierarchy and therefore has no
parent (when you ask for the area identifier of its parent, you get a zero).
One may use the database at any of five specified hierarchical levels: 1 =>
land/water, 2 => continents, 3 => countries, 4 => states, and 5 => counties (so
far, no counties are included). When the database is used at a particular level,
entities that exist only at lower levels (larger level numbers) effectively
disappear.
The new database was created from data available on the World Wide Web, using a new
interactive editor based on NCAR Graphics. There are plans to make this editor
available, so that a knowledgeable user can create a database tailored to his or
her own needs: for example (assuming that one can obtain the necessary outline
data), it should now be relatively easy to create and use a Pangaea database with
EZMAP.
A new package of routines is used to access "Earth..1" and other databases in the
same format; this package is called EZMAPB. Conceptually, the EZMAPB routines are
just part of EZMAP; they use the same common blocks and many of the same underlying
low-level routines and they are affected by the same set of internal parameters as
the routines in EZMAP proper.
The principal EZMAPB routines are as follows:
• MPLNAM (MaP LiNes, to Area Map) - A routine to extract boundary lines from a
specified database and send them to an area map.
• MPLNDM (MaP LiNes, Draw Masked) - A routine to extract boundary lines from a
specified database and draw them, masked by the contents of an area map.
• MPLNDR (MaP LiNes, Draw) - A routine to extract boundary lines from a specified
database and draw them.
• MPLNRI - A routine to force the reading of certain information from a database
into labelled COMMON blocks inside EZMAP, so that subsequent references to some
of the functions described below will have that information to work with.
(Each of the routines MPLNAM, MPLNDM, and MPLNDR reads this data as a side
effect; MPLNRI is provided for use in cases in which none of the other three
routines has yet been called.)
As each of the EZMAPB routines MPLNAM, MPLNDM, and MPLNDR processes boundary lines
from a specified database, it calls an EZMAPB routine named MPCHLN (the default
version of which does nothing):
• MPCHLN - A user-replaceable routine that can be made to change line style,
color, line width, and so on as the boundary lines from a database are being
drawn; it can also be made to delete particular lines or to change the area
identifiers associated with them. The arguments of MPCHLN tell it which of the
EZMAPB routines is calling it and whether it's being called before or after the
line is processed; they also supply the "line type" of the line being drawn,
the area identifiers of the areas on either side of it, and the actual
coordinates defining the line. Line types are similar to area types (1 =>
land/water, 2 => continents, 3 => countries, 4 => states, and 5 => counties).
Another EZMAPB routine, named MPGLTY, may be called by the user from within the
line-processing routine specified by the final argument in a call to MPLNDM:
• MPGLTY - Retrieves the line type of the line being drawn.
There is a group of EZMAPB functions providing access to information about the
areas defined by a database being used; these may be referenced at any time the
appropriate information has been loaded into EZMAPB's common blocks (that is, after
calling one of MPLNAM, MPLNDM, MPLNDR, or MPLNRI), but they are normally to be
referenced from within the area-processing routine specified as the final argument
in a call to the AREAS routine ARSCAM, in which they may be used to obtain
information determining the manner in which the areas are to be rendered:
• MPIPAI - A function whose value is non-zero if and only if the area with a
specified area identifier is part of the area having a second specified area
identifier.
• MPIPAN - A function whose value is non-zero if and only if the area with a
specified area identifier is part of the area having a specified name.
• MPIOAR - A function whose value is the area identifier of the smallest area
that is defined at or above a specified level in the area hierarchy and of
which the area having a specified area identifier is a part.
• MPIATY - A function whose value is the type of the area having a specified area
identifier.
• MPIPAR - A function whose value is the area identifier of the parent of the
area having a specified area identifier.
• MPISCI - A function whose value is the suggested color index for an area having
a specified area identifier.
• MPNAME - A function whose value is the name of the area having a particular
area identifier.
• MPFNME - A function whose value is the full name of the area having a specified
area identifier, up to a specified level in the hierarchy of areas; the full
name of an area consists of its own name, preceded by the name of its parent,
preceded by the name of its parent's parent, and so on; the various components
of the name are separated by the 3-character string ' - ' (a blank, a dash, and
another blank).
Two additional EZMAPB functions are provided; these have nothing to do with
mapping, really, but can be useful in dealing with character strings:
• MPIFNB - A function whose value is the index of the first non-blank character
in a character string.
• MPILNB - A function whose value is the index of the last non-blank character in
a character string.
Miscellaneous Other Routines
The following EZMAP routines are used for the purposes stated:
• MAPRS - Re-executes the "CALL SET" done during the last call to MAPINT. This
is useful when there has been an intervening call to a utility that calls SET.
It is quite common for a background drawn by EZMAP to be placed in a flash
buffer (as created by the package "GFLASH"). When the contents of the flash
buffer are copied to the metafile being created, if it is desired to draw
something on the EZMAP background, MAPRS may first have to be called to ensure
that the correct SET call is in effect.
• MPRST - Resets the internal state of EZMAP/EZMAPA to the default.
• SUPMAP - Draws a map with a single call. An implementation of the routine from
which EZMAP grew.
C-BINDING SYNOPSIS
#include <ncarg/ncargC.h>
c_mapaci
c_mapbla
c_mapdrw
c_mapfst
c_mapgrd
c_mapgrm
c_mapgtc
c_mapgtc
c_mapgti
c_mapgtl
c_mapgtr
c_mapint
c_mapiq
c_mapiqa
c_mapiqm
c_mapit
c_mapita
c_mapitm
c_maplbl
c_maplot
c_mappos
c_maproj
c_maprs
c_maprst
c_mapsav
c_mapset
c_mapstc
c_mapsti
c_mapstl
c_mapstr
c_maptra
c_maptri
c_maptrn
c_mapvec
c_mpfnme
c_mpglty
c_mpiaty
c_mpifnb
c_mpilnb
c_mpiola
c_mpiosa
c_mpipai
c_mpipan
c_mpipar
c_mpisci
c_mplnam
c_mplndm
c_mplndr
c_mplnri
c_mpname
c_mprset
c_supmap
USER-MODIFIABLE INTERNAL ROUTINES
The following EZMAP routines are used for the purposes stated:
• MAPUSR - This routine is called by various EZMAP routines just before and just
after drawing parts of the map. By default, grid lines are drawn using software
dashed lines and geographical outlines are drawn using either solid lines or
dotted lines. The dash pattern used for the grid lines, the flag which says
whether outlines are solid or dotted, and the color indices of various parts of
the map are all user-settable parameters, but more complete control of color
indices, spot size, dash pattern, etc., may be achieved by supplying one's own
version of MAPUSR; a user version may be as complicated as is required to
achieve a desired effect. Note that this routine is not called by any of the
EZMAPB routines; they call MPCHLN instead.
• MAPEOD - This routine is called by the EZMAP routine MAPLOT and by the EZMAPA
routines MAPBLA and MAPBLM; in each case, it is called once for each segment in
the outline dataset. The user may supply a version which examines the segment
to see if it ought to be plotted and, if not, to delete it. This can be used
(for example) to reduce the clutter in northern Canada. Note that this routine
is not called by any of the EZMAPB routines; they call MPCHLN instead.
• MPCHLN - This routine is called by the EZMAPB routines MPLNAM, MPLNDM, and
MPLNDR; in each case, it is called just before and just after the processing of
each segment in the map database. The default version does nothing; a user-
supplied version can do for the new databases what MAPUSR and MAPEOD did for
the old ones.
ACCESS
To use EZMAP Fortran or C routines, load the NCAR Graphics libraries ncarg, ncarg_gks, and
ncarg_c, preferably in that order.
MESSAGES
When error conditions are detected, the support routine SETER is called. By default, SETER
writes a message to the standard error file (as defined by I1MACH(4)) and then terminates
execution. It is possible to put SETER into recovery mode and regain control after a
recoverable error (which includes all of the possible errors).
The possible error messages are listed below. All errors are recoverable in the sense
that a user program which has called ENTSR to set recovery mode will get control back
after one of these errors occurs.
MAPBLA - UNCLEARED PRIOR ERROR
MAPCHI - ERROR EXIT FROM GQPLCI
MAPCHI - ERROR EXIT FROM GQPMCI
MAPCHI - ERROR EXIT FROM GQTXCI
MAPDRW - UNCLEARED PRIOR ERROR
MAPFST - UNCLEARED PRIOR ERROR
MAPGCI - UNCLEARED PRIOR ERROR
MAPGRD - UNCLEARED PRIOR ERROR
MAPGRM - UNCLEARED PRIOR ERROR
MAPGTC - UNCLEARED PRIOR ERROR
MAPGTC - UNKNOWN PARAMETER NAME
MAPGTI - UNCLEARED PRIOR ERROR
MAPGTI - UNKNOWN PARAMETER NAME
MAPGTL - UNCLEARED PRIOR ERROR
MAPGTL - UNKNOWN PARAMETER NAME
MAPGTR - UNCLEARED PRIOR ERROR
MAPGTR - UNKNOWN PARAMETER NAME
MAPINT - ANGULAR LIMITS TOO GREAT
MAPINT - ATTEMPT TO USE NON-EXISTENT PROJECTION
MAPINT - MAP HAS ZERO AREA
MAPINT - MAP LIMITS INAPPROPRIATE
MAPINT - UNCLEARED PRIOR ERROR
MAPIO - EOF ENCOUNTERED IN OUTLINE DATASET
MAPIO - ERROR ON READ OF OUTLINE DATASET
MAPIQ - UNCLEARED PRIOR ERROR
MAPIQA - UNCLEARED PRIOR ERROR
MAPIQM - UNCLEARED PRIOR ERROR
MAPIT - UNCLEARED PRIOR ERROR
MAPITA - UNCLEARED PRIOR ERROR
MAPITM - UNCLEARED PRIOR ERROR
MAPLBL - UNCLEARED PRIOR ERROR
MAPLMB - UNCLEARED PRIOR ERROR
MAPLOT - UNCLEARED PRIOR ERROR
MAPPOS - ARGUMENTS ARE INCORRECT
MAPPOS - UNCLEARED PRIOR ERROR
MAPROJ - UNCLEARED PRIOR ERROR
MAPROJ - UNKNOWN PROJECTION NAME
MAPRS - UNCLEARED PRIOR ERROR
MAPRST - EOF ON READ
MAPRST - ERROR ON READ
MAPRST - UNCLEARED PRIOR ERROR
MAPSAV - ERROR ON WRITE
MAPSAV - UNCLEARED PRIOR ERROR
MAPSET - UNCLEARED PRIOR ERROR
MAPSET - UNKNOWN MAP AREA SPECIFIER
MAPSTC - UNCLEARED PRIOR ERROR
MAPSTC - UNKNOWN OUTLINE NAME
MAPSTC - UNKNOWN PARAMETER NAME
MAPSTI - UNCLEARED PRIOR ERROR
MAPSTI - UNKNOWN PARAMETER NAME
MAPSTL - UNCLEARED PRIOR ERROR
MAPSTL - UNKNOWN PARAMETER NAME
MAPSTR - UNCLEARED PRIOR ERROR
MAPSTR - UNKNOWN PARAMETER NAME
MAPTRA - UNCLEARED PRIOR ERROR
MAPTRI - UNCLEARED PRIOR ERROR
MAPTRN - ATTEMPT TO USE NON-EXISTENT PROJECTION
MAPTRN - UNCLEARED PRIOR ERROR
MAPVEC - UNCLEARED PRIOR ERROR
MPGETC - UNCLEARED PRIOR ERROR
MPGETI - UNCLEARED PRIOR ERROR
MPGETL - UNCLEARED PRIOR ERROR
MPGETR - UNCLEARED PRIOR ERROR
MPLNAM - Can't form name of ".names" file
MPLNAM - Can't open the ".lines" file
MPLNAM - Can't open the ".names" file
MPLNAM - Read bad index from ".names" file
MPLNAM - Read error on ".lines" file
MPLNAM - Read error on ".names" file
MPLNAM - UNCLEARED PRIOR ERROR
MPLNDM - Can't form name of ".names" file
MPLNDM - Can't open the ".lines" file
MPLNDM - Can't open the ".names" file
MPLNDM - Read bad index from ".names" file
MPLNDM - Read error on ".lines" file
MPLNDM - Read error on ".names" file
MPLNDM - UNCLEARED PRIOR ERROR
MPLNDR - Can't form name of ".names" file
MPLNDR - Can't open the ".lines" file
MPLNDR - Can't open the ".names" file
MPLNDR - Read bad index from ".names" file
MPLNDR - Read error on ".lines" file
MPLNDR - Read error on ".names" file
MPLNDR - UNCLEARED PRIOR ERROR
MPLNRI - Can't form name of ".names" file
MPLNRI - Can't open the ".names" file
MPLNRI - Read bad index from ".names" file
MPLNRI - Read error on ".names" file
MPLNRI - UNCLEARED PRIOR ERROR
MPRSET - UNCLEARED PRIOR ERROR
MPSETC - UNCLEARED PRIOR ERROR
MPSETI - UNCLEARED PRIOR ERROR
MPSETL - UNCLEARED PRIOR ERROR
MPSETR - UNCLEARED PRIOR ERROR
SUPCON - UNCLEARED PRIOR ERROR
SUPMAP - UNCLEARED PRIOR ERROR
SEE ALSO
Online: ezmap_params, mapaci, mapbla, mapblm, mapdrw, mapeod, mapfst, mapgci, mapgrd,
mapgrm, mapgtc, mapgti, mapgtl, mapgtr, mapint, mapiq, mapiqa, mapiqd, mapiqm, mapit,
mapita, mapitd, mapitm, maplbl, maplmb, maplot, mappos, maproj, maprs, maprst, mapsav,
mapset, mapstc, mapsti, mapstl, mapstr, maptra, maptri, maptrn, mapusr, mapvec, mpchln,
mpfnme, mpgetc, mpgeti, mpgetl, mpgetr, mpglty, mpiaty, mpifnb, mpilnb, mpiola, mpiosa,
mpipai, mpipan, mpipar, mpisci, mplnam, mplndm, mplndr, mplnri, mpname, mprset, mpsetc,
mpseti, mpsetl, mpsetr, supmap, supcon, ncarg_cbind
Hardcopy: NCAR Graphics Contouring and Mapping Tutorial; NCAR Graphics Fundamentals, UNIX
Version
COPYRIGHT
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.