Provided by: libncarg-dev_6.4.0-9_amd64 bug

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.