Ezmap, A Map-Drawing Package

This document describes an NCAR Graphics package named EZMAP, which 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. The origin and orientation of the projection may be selected by the user. Points on the earth defined by latitude and longitude are mapped to points in a projection plane, referred to as the u/v plane. A rectangular perimeter whose sides are parallel to the u and v axes is chosen; material within that perimeter (or an inscribed elliptical perimeter) is mapped to the plane of the plotter (referred to as the x/y plane) for plotting. The u and v axes are parallel to the x and y axes, respectively.

Also described in this document are routines from a package originally named EZMAPA (added about 1986 or 1987), which, among other things, allows the user to produce solid-filled maps of the earth, and a package originally named EZMAPB (added in 1998), which 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).

Principal sections of this document are as follows:

The rest of this "INTRODUCTION" gives an overview of EZMAP, with short descriptions of all the available subroutines.
The section "PROJECTIONS" describes the projections of the earth that may be used.
The section "ROUTINES" gives detailed descriptions of all available subroutines.
The section "INTERNAL PARAMETERS" describes all the internal parameters of the package; each internal parameter affects some aspect of the behavior of one or more of the routines in the package.
The section "ERROR HANDLING" describes all the conditions that are recognized as errors and what can be done to recover from an error.
The section "EXAMPLES" describes examples that are available to illustrate the use of the package; some users may wish to obtain the code for these examples and run them so as to have them available for reference while reading further.
The section "AREA IDENTIFIERS" lists all the area identifiers that are used by EZMAP. User knowledge of these is necessary for some purposes.
The section named "MISCELLANY" gives information that will be of interest to a few users.

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.

MAPDRW simply calls four lower-level routines. In many situations, the user will 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 (which see, below).

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 the portion of the plotter frame to be used.
MAPROJ - Determines the projection to be used.
MAPSET - Determines the portion of the u/v plane to be viewed.
MAPSTC (or MPSETC) - Sets a parameter value of type CHARACTER.
MAPSTI (or MPSETI) - Sets a parameter value of type INTEGER.
MAPSTL (or MPSETL) - Sets a parameter value of type LOGICAL.
MAPSTR (or MPSETR) - 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 (or MPGETC) - Gets a parameter value of type CHARACTER.
MAPGTI (or MPGETI) - Gets a parameter value of type INTEGER.
MAPGTL (or MPGETL) - Gets a parameter value of type LOGICAL.
MAPGTR (or MPGETR) - 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 a 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.
MAPITD - Does "pen-up" or "pen-down" moves. Like MAPIT, but the new dash package DASHPACK is called instead of the old DASHCHAR.
MAPIQD - Signals the end of a string of calls to MAPITD 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 of EZMAPA 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 of EZMAP proper. The EZMAPA routines 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 (which see, below).
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 (which see, below).
MAPGRM - Draws selected parallels and meridians "masked" by an existing area map. (Example: drawing these lines over water, but not over land.)
MAPITA and MAPIQA - Add to an area map the projections of arbitrary lines defined by lat/lon coordinates of points on the surface of the globe. MAPBLA and MPLNAM both use 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 - Draw, masked by an area map, the projections of arbitrary lines defined by the lat/lon coordinates of points on the surface of the globe. MAPBLM, MAPGRM, and MPLNDM all use these routines to draw lines masked by the contents of an area map; 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.
MPIOLA - A function whose value is the area identifier of the largest 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.
MPIOSA - 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:

MAPEOD - This routine is called by the EZMAP routine MAPLOT and 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 used 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; for the same purpose, they call the routine MPCHLN.
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.
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.
SUPMAP - This is a version of the routine from which EZMAP grew. It allows one to draw a complete map with a single, rather lengthy, call. The routine SUPCON, which is the old analogue of MAPTRN, is also implemented.

All of the routines mentioned above are described in detail in the section "ROUTINES", below.

PROJECTIONS

EZMAP offers ten different projections, in three groups: conical, azimuthal, and cylindrical.

Conical Projections

Conical projections map the surface of the earth onto a cone which is either tangent to the earth along a single circle or intersects it along two circles. The cone is cut along some line passing through its vertex and opened up onto a flat surface. The only conical projection offered by EZMAP is the Lambert conformal with two standard parallels (becoming a simple conic with one standard parallel if the two parallels are made equal). The cone intersects the earth along two user-specified standard parallels (lines of latitude), which would normally both be in the Northern Hemisphere or in the Southern Hemisphere; the cone is cut along the line opposite a user-specified central meridian (line of longitude) and laid flat on the u/v plane with either the North Pole or the South Pole (as implied by the standard parallels) at the origin.

If LAT1 and LAT2 are the latitudes of the two standard parallels and LAT1 is not equal to LAT2, the so-called "cone constant" is given by the formula

		 LOG(COS(LAT1))-LOG(COS(LAT2))
    CONE = -------------------------------------------
	   LOG(TAN(45-S*LAT1/2))-LOG(TAN(45-S*LAT2/2))

where "S" is +1 in the Northern Hemisphere and -1 in the Southern Hemisphere. If LAT1 equals LAT2, then

    CONE = COS(90-S*LAT1)

The value of CONE is between 0 and 1; CONE*360 is the angular separation between the edges of the cut after the cone is opened onto the plane, as measured across the surface of the flattened cone. If (RLAT,RLON) is a point to be projected, then the formulas

    R = (TAN(45-S*RLAT/2))**CONE
    U = R*SIN(CONE*(RLON-CLON))
    V = -S*R*COS(CONE*(RLON-CLON))

where CLON is the longitude of the central meridian, give the coordinates of the projected point in the u/v plane.

The globe is projected onto the entire u/v plane minus a wedge with its apex at the origin. This projection is normally used to depict mid-latitude regions of limited extent, for which it is relatively distortion-free. It has the property of preserving angles.

See the example named "mpex01".

Azimuthal Projections

Azimuthal projections map the earth (or a single hemisphere of it) onto a u/v plane whose origin touches the earth at the user-specified point (PLAT,PLON). The image may be rotated by a user-specified angle ROTA. The azimuthal projections are generated as follows:

Step 1: Imagine that the earth is placed behind the u/v plane so that the point at latitude 0 and longitude 0 just touches the plane at the point (0,0), the North Pole is at the top, and the South Pole is at the bottom.
Step 2: Rotate the earth about its polar axis until the v axis is tangent to the meridian identified by PLON (and that meridian is therefore closest to you).
Step 3: Rotate the earth, tilting one of the poles directly toward you and the other pole directly away from you, until the point (PLAT,PLON) is at the origin of the u/v plane.
Step 4: Rotate the earth clockwise through the angle ROTA about a line perpendicular to the u/v plane passing through the point (0,0).
Step 5: Using lines of projection emanating from a central point within or behind the earth (depending on the projection type), project geographical outlines, parallels, and meridians from the earth's surface onto the u/v plane.
Step 6: Set up linear scales along the u and v axes. The ranges of u and v depend on the projection type.
Step 7: Draw a rectangular or elliptical portion of the resulting map.

If A is the angular separation, in degrees, of a point P, to be projected, from the point (PLAT,PLON), SINA is the sine of A, COSA is the cosine of A, and R is the linear distance of the projected point P' from the u/v origin, the various azimuthal projections may be described in terms of the relationship between A and R, as follows:

Stereographic projection:

      R = TAN(A/2) = (1-COSA)/SINA

: As A approaches 180 degrees, R approaches infinity. The entire globe is projected to the entire u/v plane. In practice, distortion becomes great beyond R=2, when A is approximately 127 degrees. The center of the projection is the point on the earth's surface opposite the point of tangency with the projection plane.
: See the examples named "mpex02", "mpex04", "mpex05", and "mpex07".

Orthographic projection:

      R = SINA

: Points for which A is greater than 90 degrees are treated as invisible. Thus, a hemisphere is projected inside a circle of radius 1. The center of the projection is at infinity; all projection lines are parallel to each other and perpendicular to the u/v plane.
: See the example named "mpex05".

Lambert equal-area projection:

      R = 2*SINA/SQRT(2*(1+COSA))

: As A approaches 180 degrees, R approaches 2. The entire globe is projected into a circle of radius 2.
: See the example named "mpex05".

Gnomonic projection:

      R = TAN(A) = SINA/COSA

: Points for which A is greater than 90 degrees are invisible. Thus, a hemisphere is projected to the entire u/v plane. In practice, distortion becomes great beyond R=2, when A is approximately 65 degrees. The center of this projection is the center of the earth.
: See the example named "mpex05".

Azimuthal equidistant projection:

      R = A*pi/180

: As A approaches 180 degrees, R approaches pi (3.1415926...). Thus, the entire globe is projected within a circle of radius pi.
: See the example named "mpex05".

Basic satellite-view projection:

      R = SQRT(SA*SA-1)*SINA/(SA-COSA)

: where "SA" is the distance from the center of the earth to a satellite above the point (PLAT,PLON), in multiples of the earth's radius. Points for which COSA is less than "1/SA" are invisible. The portion of the earth's surface which would be visible from the satellite is projected inside a circle of radius 1. The center of the projection is at the satellite's position. As the satellite moves further and further out, the basic satellite-view projection approaches the orthographic projection. See the examples named "mpex05" and "mpexfi".
: The basic satellite-view projection gives a view of the earth as seen by a satellite camera that is looking straight down toward the center of the earth. Note that the model for the "camera" we're talking about here is a pin-hole camera, in which each point of an image is formed by a single straight line emanating from some point in the scene. Real cameras are more complicated than that: each point of an image is formed by focusing infinitely many rays emanating from a point in the scene (all the rays from the point that happen to pass through the lens of the camera). An image formed by a real camera is generally distorted in some fashion and cannot be expected to exactly match an image formed by our hypothetical pin-hole camera.
: See the examples named "mpex05" and "mpexfi".

General satellite-view projection:

      R = (something messy that I don't have in closed form)!

: The user-settable parameters 'S1' and 'S2' affect the satellite-view projection as follows: S1 measures the angle between the line to the center of the earth and the line of sight of the satellite (the line to which the projection plane is perpendicular). The default value of S1 is zero, which gives the basic satellite view. When S1 is non-zero, S2 specifies the angle from the positive u axis of the basic satellite view counter-clockwise to the line OP, where O is the origin of the basic view and P is the projection (a single point), on the basic view, of the desired line of sight from the satellite. When S1 and S2 are used, the part of the earth projected is the same as for the basic view, but the part of the u/v plane covered by the projection may become the interior of an ellipse, the area "inside" a parabola, or the area "inside" one branch of a hyperbola; in each of these cases, the major axis of the curve defining the limb of the projection is at an angle S2 to the u axis.
: Basically, 'S1' and 'S2' allow you to aim the satellite camera in any desired direction; however, getting exactly the view that you want is not completely trivial. The example "cpex10" demonstrates a technique that may be quite useful: if, in the call to MAPROJ that requests the satellite-view projection (with a first argument = 'SV' and second and third arguments PLAT and PLON specifying the position of the satellite), you use a value of ROTA (the final argument) such that the point you want to aim the satellite camera at is directly above the center of the basic view and you then use 'S1' non-zero and 'S2' = 90., you get a view with "outer space" at the top, the earth at the bottom, and the horizon line more or less horizontal. It is recommended that the satellite-view projection be used with a call to MAPSET in which the first argument JLTS = 'AN'; in that case, the other four arguments specify the field of view of the camera (as angular distances to the left, to the right, to the bottom, and to the top, of the frame). It is further recommended that you not use a first argument JLTS = 'MA' in such a call to MAPSET, since, in that case, you get a view showing the entire part of the globe that is visible from the satellite and distortion is likely to be extreme.
: See the examples named "mpex06" and "cpex10". The latter is actually a CONPACK example, but it demonstrates the aiming technique described in the previous paragraph.

Cylindrical Projections

Cylindrical projections map the surface of the earth onto a cylinder which is tangent to the earth along a great circle passing through the user-specified point (PLAT,PLON) and tilted at a user-specified angle ROTA. The cylinder is cut along a line parallel to its axis and unrolled onto the plane. The cylindrical projections are generated as follows:

Step 1: Imagine that the earth is placed behind the u/v plane so that the point at latitude 0 and longitude 0 just touches the plane at the point (0,0), the North Pole is at the top, and the South Pole is at the bottom.
Step 2: Rotate the earth about its polar axis until the v axis is tangent to the meridian identified by PLON (and that meridian is therefore closest to you).
Step 3: Rotate the earth, tilting one of the poles directly toward you and the other pole directly away from you, until the point (PLAT,PLON) is at the origin of the u/v plane.
Step 4: Rotate the earth clockwise through the angle ROTA about a line perpendicular to the u/v plane and passing through the point (0,0).
Step 5: Wrap the u/v plane around the globe to form a cylinder, with the u axis touching the earth along a great circle.
Step 6: Using a technique dependent on the projection type, project geographical outlines, parallels, and meridians outward from the earth's surface onto the cylinder.
Step 7: Cut the cylinder along a line parallel to its axis and opposite the point (0,0).
Step 8: Unwrap the cylinder again.
Step 9: Set up linear scales along the u and v axes. The ranges of u and v depend on the projection type.
Step 10: Draw a rectangular or elliptical portion of the resulting map.

What happens in step 6 above will be described for each of the three types of cylindrical projections provided by EZMAP in the simple case where PLAT, PLON, and ROTA are all zero. Let RLAT and RLON be the latitude and longitude, in degrees, of a point to be projected; RLON must lie between -180 and +180. (If PLAT, PLON, and/or ROTA are non-zero, one must substitute for RLAT and RLON a pseudo-latitude and a pseudo-longitude computed from the real latitude and longitude; this is left as an exercise for the devotee of spherical trigonometry.) The cylindrical projections may then be described as follows:

Cylindrical Equidistant: U and V are computed using the equations

      U = RLON
      V = RLAT

: The entire globe is projected into a rectangle in the u/v plane. U ranges from -180 to +180, V from -90 to +90.
: See the example named "mpex05".

Mercator: U and V are computed using the equations

      U = RLON*pi/180 (where pi=3.14159...)
      V = ALOG(COT(45-RLAT/2))

: The entire globe is projected into an infinite rectangle in the u/v plane. U ranges from -pi to +pi, V from -infinity to +infinity. In practice, distortion becomes unacceptable for latitudes within 5 degrees of the North or South Pole.
: See the examples named "mpex03", "mpex04", "mpex05", "mpex08", and "mpex09".

Mollweide-type: The projection is not a true Mollweide. U and V are computed using the equations

      U = RLON/90
      V = COS(90-RLAT)

: The entire surface of the globe is projected into an ellipse. U ranges from -2 to +2, V from -1 to +1.
: See the example named "mpex05".

ROUTINES

This section describes all the user-callable routines of EZMAP. The descriptions are arranged in alphabetical order.

MAPACI (IAID)

The function MAPACI is normally used to pick colors for the areas created by the boundary lines added to an area map by a call to MAPBLA. 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).

Usage

The FORTRAN statement

      ICLR = MAPACI(IAID)

where IAID is the the area identifier for one of the areas created by the boundary lines in a selected outline dataset, gives ICLR an integer value between 1 and 7. This integer value will normally be used (in a manner determined by the user) to select a color index for that area. It is guaranteed that, if two areas have a portion of their boundaries of non-zero length in common, then MAPACI will return different values for the two areas. For a complete list of area identifiers and the values that MAPACI will return for each, see the section named "AREA IDENTIFIERS".

See the example named "eezmpa".

Arguments

IAID (an input expression of type INTEGER) is an area identifier for one of the areas defined by the set of boundary lines added to an area map by a call to MAPBLA.

MAPBLA (IAMA)

Adds to the area map in the array IAMA the set of boundary lines, of projected geographical entities, determined by the current state of the internal parameters of EZMAP. 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 (which see, below).

Usage

Execute the statement

      CALL MAPBLA (IAMA)

to add boundary lines to the area map in the array IAMA. The area map must previously have been initialized by calling the routine ARINAM, in the package AREAS, using a statement like "CALL ARINAM (IAMA,LAMA)", where LAMA is the length of the array IAMA. The area map may subsequently be used in various ways; for example, one may call the AREAS routine ARSCAM to draw a solid-filled map.

One or two groups of boundary lines are added to the area map by a call to MAPBLA. The first, having group identifier 'G1' (default value 1), consists of a perimeter (either rectangular or elliptical, depending on the value of the internal parameter 'EL') and the set of projected boundary lines implied by the user's selection of an outline dataset (some combination of continental, U.S., and world political outlines). For certain projections, a limb line may also be included.

If the parameter 'VS' has a value greater than zero, the group 'G2' is added to the area map; it consists of a copy of the perimeter and the limb line (if any) plus a set of vertical lines splitting the area inside the perimeter into 'VS' vertical strips. (By default, the value of 'VS' is 1.) The object of the group 'G2' is to split areas up, reducing the number of points required to define a typical area below the level at which some target hardware device begins to fail.

See the example named "eezmpa".

Arguments

IAMA (an input/output array of type INTEGER) is the area map array to which boundary lines are to be added.

MAPBLM (IAMA,XCRA,YCRA,MCRA, . . . )

(The remaining arguments are IAAI, IAGI, NOGI, and ULPR.)

Draws geographical outlines masked by the contents of a specified area map. 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 (which see, below).

Usage

The FORTRAN statement

      CALL MAPBLM (IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

is used to draw the set of boundary lines of projected geographical entities determined by the current state of the internal parameters of EZMAP, masked against the area map in the array IAMA.

MAPBLM is much like MAPLOT, except that the boundary lines are drawn using calls to MAPITM and MAPIQM, which does the masking of the lines against an area map and passes the pieces resulting from the masking process along to a user-provided line-drawing routine.

See the example named "cpex10".

Arguments

IAMA (an input/output array of type INTEGER, dimensioned as specified in a call to the AREAS routine ARINAM) is the array containing the area map against which boundary lines are to be masked. The area map must have been initialized by a call to ARINAM; it should contain the edges required to create a desired effect. For example, an area map might be created that defines a region of interest, within which user data is available and within which boundary lines are to be drawn. For more details, see the reference document for the package named AREAS.

XCRA and YCRA (scratch arrays, dimensioned at least MCRA, of type REAL) are to be used by MAPBLM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR.

MCRA (an input expression of type INTEGER) is the dimension of the arrays XCRA and YCRA.

IAAI and IAGI (scratch arrays, dimensioned at least NOGI, of type INTEGER) are to be used by MAPBLM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR. The mnemonics stand for "Integer Array of Area Identifiers" and "Integer Array of Group Identifiers", respectively.

NOGI (an input expression of type INTEGER) is the dimension of the arrays IAAI and IAGI. The mnemonic stands for "Number Of Group Identifiers (of edges in the area map)", which determines the required dimension of IAAI and IAGI.

ULPR is the name of the user-supplied line-processing routine. It must be declared EXTERNAL in the routine that calls MAPBLM, so that the compiler and loader will know that it is the name of a routine to be called instead of a variable. The user routine ULPR will be called once for each piece of a boundary line resulting from the masking process; it may decide to draw (or to not draw) each such piece. ULPR will be called using a FORTRAN statement like

      CALL ULPR (XCRA,YCRA,NCRA,IAAI,IAGI,NGPS)

where XCRA and YCRA are real arrays holding the normalized device coordinates of NCRA points defining a polyline which is part of some boundary line and IAAI and IAGI are integer arrays holding NGPS area-identifier/group-identifier pairs for the area within which that piece of the line lies. In writing ULPR, the user may rely upon a SET call's having been done which makes it possible to use normalized device coordinates in calls to routines like CURVE, CURVED, GPL, etc. For more details, see the reference document for the package named AREAS and, in particular, the description of the subroutine ARDRLN.

MAPDRW

Draws a complete map, as described by the current values of the internal parameters of EZMAP. 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 routines that MAPDRW would have called, but call MPLNDR (which see, below) instead of MAPLOT.

Usage

Just call it. MAPDRW calls MAPINT (if the value of the internal parameter 'IN' indicates that initialization is required), MAPGRD, MAPLBL, and MAPLOT, in that order.

Users may sometimes wish to call directly the routines that MAPDRW calls. For example, they sometimes want to change the aspect ratio of a map drawn by EZMAP to something other than that implied by the projection selected; in order to do this, it is necessary to put calls to GETSET and SET in between the call to MAPINT and the calls to MAPGRD, MAPLBL, and MAPLOT. This is possible only if the user is calling those routines directly (rather than indirectly, by calling MAPDRW).

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", and "mpex10".

Arguments

None.

MAPEOD (NOUT,NSEG,IDLS,IDRS,NPTS,PNTS)

To examine each outline-dataset segment.

Usage

MAPEOD is called by MAPLOT to examine each segment in an outline dataset just before it is plotted and by MAPBLA to examine each segment in an outline dataset just before it is added to an area map. The default version of MAPEOD does nothing. A user-supplied version may cause selected segments to be deleted (to reduce the clutter in northern Canada, for example). Note that this routine is not called by any of the EZMAPB routines; for the same purpose, they call the routine MPCHLN.

See the examples named "mpex03", "mpex05", and "mpex09".

Arguments

NOUT (an input expression of type INTEGER) is the number of the outline dataset from which the segment comes, as follows:

NOUT Dataset from which the segment came
1 'CO' - Continental outlines only.
2 'US' - U.S. state outlines only.
3 'PS' - Continental, U.S. state, and international outlines.
4 'PO' - Continental and international outlines.

NOUT	Dataset from which the segment came
1	'CO' - Continental outlines only.
2	'US' - U.S. state outlines only.
3	'PS' - Continental, U.S. state, and international outlines.
4	'PO' - Continental and international outlines.

NSEG (an input expression of type INTEGER) is the number of the segment within the outline dataset. The maps in the example named "mpex09" show segment numbers for the outline dataset 'CO'; the program may be modified to produce maps showing segment numbers for any outline dataset.

IDLS and IDRS (input expressions of type INTEGER) are identifiers for the areas to the left and right, respectively, of the segment. (Left and right are defined from the standpoint of a viewer standing at point 1 of the segment and looking toward point 2.) For a complete list of area identifiers, see the section named "AREA IDENTIFIERS".

NPTS (an input/output variable of type INTEGER), on entry, is the number of points defining the outline segment. NPTS may be zeroed by MAPEOD to suppress any use of the segment on the map.

PNTS (an input/output array, dimensioned 2*NPTS, of type REAL) is an array of coordinates. PNTS(1) and PNTS(2) are the latitude and longitude of the first point, PNTS(3) and PNTS(4) the latitude and longitude of the second point, ... PNTS(2*NPTS-1) and PNTS(2*NPTS) the latitude and longitude of the last point. All values are in degrees. Longitudes are all between -180 and +180; no segment crosses the meridian at -180 (+180) degrees.

MAPFST (RLAT,RLON)

Draws lines on a map - used in conjunction with MAPVEC.

Usage

The statement

      CALL MAPFST (RLAT,RLON)

is equivalent to the statement

      CALL MAPIT (RLAT,RLON,0)

See the description of MAPIT.

Arguments

RLAT and RLON (input expressions of type REAL) are defined in the same way as for MAPIT (which see).

MAPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)

Calculates the latitudes and longitudes of points on the shortest great circle route between two given points on the surface of the globe.

Usage

The statement

      CALL MAPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)

defines the positions of two points, A and B, on the globe and the number of equally-spaced points, NOPI, to be interpolated along the great circle route from A to B. The latitudes and longitudes of the interpolated points are returned to the caller in the arrays RLTI and RLNI. If the points A and B are exactly opposite one another on the globe, the code does not fail, but the direction of the great circle route will be somewhat unpredictable (since, in that case, there is more than one great circle route joining the two points).

Arguments

ALAT and ALON (input expressions of type REAL) specify the latitude and longitude of the point A.

BLAT and BLON (input expressions of type REAL) specify the latitude and longitude of the point B.

NOPI (an input expression of type INTEGER) specifies the number of equally-spaced points to be interpolated along the great circle from A to B.

RLTI and RLNI (output arrays of type REAL, each dimensioned at least NOPI) are the latitudes and longitudes of the interpolated points. Each lat/lon pair defines one of the interpolated points; the points are in order of increasing distance from A. The positions of the points A and B themselves are not returned in these arrays; only the positions of the interpolated points are.

MAPGRD

Draws a lat/lon grid.

Usage

The statement

      CALL MAPGRD

draws a grid consisting of lines of latitude (parallels) and lines of longitude (meridians). If EZMAP needs initialization or if there is an uncleared NCAR Graphics error or if the parameter 'GR' is less than or equal to zero, MAPGRD does nothing. The values of the parameters 'GP', 'GN', and 'GT' also affect the drawing of the grid.

The grid is drawn using calls to MAPIT and MAPIQ. By default, MAPGRD forces the value of the internal parameter 'DL' to zero, so that the grid will be drawn using calls to the routines FRSTD and VECTD, in the dash package. MAPGRD also calls the dash-package routine DASHDB to force the current dash pattern to the value specified by the internal parameter 'DA'. Before returning control to the user, MAPGRD restores the original value of 'DL' and the original dash pattern. A user version of the routine MAPUSR may be supplied to change the way in which the grid lines are drawn (as shown in the example "mpex09").

Arguments

None.

MAPGRM (IAMA,XCRA,YCRA,MCRA, . . . )

(The remaining arguments are IAAI, IAGI, NOGI, and ULPR.)

Draws lines of latitude and longitude masked against an existing area map. The example "eezmpa" described in the section "EXAMPLES" shows how MAPGRM may be used to limit the drawing of these lines to areas over ocean, but there are other possible uses.

Usage

The FORTRAN statement

      CALL MAPGRM (IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

is used to draw lines of latitude and longitude masked against the existing area map in the array IAMA.

MAPGRM is just like MAPGRD, except that the grid lines are drawn using calls to MAPITM and MAPIQM, which does the masking of the lines against an area map and passes the pieces resulting from the masking process along to a user-provided line-drawing routine.

See the examples named "eezmpa", "tezmpa", and "tezmpb".

Arguments

IAMA (an input/output array, dimensioned as specified in a call to the AREAS routine ARINAM, of type INTEGER) is the array containing the area map against which lines of latitude and longitude are to be masked. The area map must have been initialized by a call to ARINAM; it may contain edges added to it by calling MAPBLA, as is the case in the example named "eezmpa", or it may contain a different set of edges to create some other desired effect. For example, an area map might be created that defines a region of interest, within which user data is available and within which lines of latitude and longitude are to be drawn. For more details, see the reference document for the package named AREAS.

XCRA and YCRA (scratch arrays, dimensioned at least MCRA, of type REAL) are to be used by MAPGRM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR.

MCRA (an input expression of type INTEGER) is the dimension of the arrays XCRA and YCRA.

IAAI and IAGI (scratch arrays, dimensioned at least NOGI, of type INTEGER) are to be used by MAPGRM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR. The mnemonics stand for "Integer Array of Area Identifiers" and "Integer Array of Group Identifiers", respectively.

ULPR is the name of the user-supplied line-processing routine. It must be declared EXTERNAL in the routine that calls MAPGRM, so that the compiler and loader will know that it is the name of a routine to be called instead of a variable. The user routine ULPR will be called once for each piece of a latitude/longitude line resulting from the masking process; it may decide to draw (or to not draw) each such piece. ULPR will be called using a FORTRAN statement like

      CALL ULPR (XCRA,YCRA,NCRA,IAAI,IAGI,NGPS)

where XCRA and YCRA are real arrays holding the normalized device coordinates of NCRA points defining a polyline which is part of some latitude/longitude line and IAAI and IAGI are integer arrays holding NGPS area-identifier/group-identifier pairs for the area within which that piece of the line lies. In writing ULPR, the user may rely upon a SET call's having been done which makes it possible to use normalized device coordinates in calls to routines like CURVE, CURVED, GPL, etc. For more details, see the reference document for the package named AREAS and, in particular, the description of the subroutine ARDRLN.

MAPGTx (PNAM,xVAL) or MPGETx (PNAM,xVAL)

Gets the current value of a specified EZMAP parameter. An alternate name, more nearly consistent with those used in other NCAR Graphics packages, is provided for this routine.

Usage

Use one of the four statements

      CALL MAPGTC (PNAM,CVAL) or CALL MPGETC (PNAM,CVAL)
      CALL MAPGTI (PNAM,IVAL) or CALL MPGETI (PNAM,IVAL)
      CALL MAPGTL (PNAM,LVAL) or CALL MPGETL (PNAM,LVAL)
      CALL MAPGTR (PNAM,RVAL) or CALL MPGETR (PNAM,RVAL)

depending on whether the value to be retrieved is of type CHARACTER, INTEGER, LOGICAL, or REAL. The values of some parameters may be retrieved in more than one way. For example, the value of the initialization flag may be retrieved as a logical quantity (.TRUE. or .FALSE.) or as an integer (non-zero or zero).

See the examples named "mpex07" and "mpex08".

Arguments

PNAM (an input expression of type CHARACTER) specifies the name of the parameter to get. Only the first two characters of the string are examined. See the section "INTERNAL PARAMETERS" for a list of all the internal parameters whose values may be retrieved.

xVAL (an output variable of type CHARACTER, INTEGER, LOGICAL, or REAL, depending on which routine is called) receives the value of the parameter specified by PNAM.

MAPINT

Initialization.

Usage

The statement

      CALL MAPINT

initializes the EZMAP package. This is required initially and again after a call to any of the routines MAPPOS, MAPROJ, or MAPSET. The flag 'IN', which may be retrieved by a call to MAPGTI or MAPGTL, indicates whether or not initialization is required at a given time. As of now (April, 1987), no parameter change by means of a call to MAPSTx forces re-initialization; only calls to MAPPOS, MAPROJ, and MAPSET do.

To clarify the use of MAPINT: Once the internal parameters describing a map transformation are completely defined, MAPINT must be called; it computes as many of the transformation parameters as possible, so that, when MAPTRN is called, it can return the u/v coordinates corresponding to a particular lat/lon position as quickly as possible. If the transformation is changed, MAPINT must be re-called before the next call to MAPTRN. Routines which call MAPTRN and therefore depend on MAPINT's having been called are as follows: MAPBLA, MAPFST, MAPGRD, MAPGRM, MAPIQ, MAPIQA, MAPIQM, MAPIT, MAPITA, MAPITM, MAPLBL, MAPLOT, MAPTRA, MAPTRI, MAPVEC, MPLNAM, MPLNDM, MPLNDR, and SUPCON. Routines which change the transformation in some way and therefore require MAPINT to be re-called are as follows: MAPPOS, MAPROJ, and MAPSET. If one is just doing a single plot, one does the parameter-setting calls that define the transformation, calls MAPINT to initialize, and then calls the various routines that draw the plot; in this case, a single call to MAPINT is all that is necessary.

One of the things that MAPINT does is call the SPPS routine SET to define the mapping from the u/v (projection) plane to the x/y (plotter) plane, so that u/v coordinates returned by the routines MAPTRA and MAPTRN can be used directly (as "user" coordinates) in calls to other NCAR Graphics routines. The user must be careful not to interfere with this process by doing an inappropriate call to SET in between calling MAPINT and calling other routines that depend on the proper SET call's having been done; if such a call must be done, the routine MAPRS (q.v.) may be used to restore the SET call done by MAPINT.

See the examples named "mpex09", "mpex10", and "eezmpa".

Arguments

None.

MAPIQ

Terminate a string of calls to MAPIT.

Usage

The statement

      CALL MAPIQ

flushes MAPIT's buffers. It is particularly important that this be done before a STOP or a CALL FRAME and before changing the color index, dash pattern, etc.

See the description of MAPIT, below.

See the example named "mpexfi".

Arguments

None.

MAPIQA (IAMA,IGID,IAIL,IAIR)

Terminate a string of calls to MAPITA.

Usage

The statement

      CALL MAPIQA (IAMA,IGID,IAIL,IAIR)

flushes MAPITA's buffers. It is particularly important that this be done before attempting to use the area map in the array IAMA for something.

See the description of MAPITA, below.

See the example named "cpex08", which is descibed in the reference document for the package named CONPACK.

Arguments

IAMA, IGID, IAIL, and IAIR are all as described for the routine MAPITA (described below).

MAPIQD

Terminate a string of calls to MAPITD.

Usage

The statement

      CALL MAPIQD

flushes MAPITD's buffers. It is particularly important that this be done before a STOP or a CALL FRAME and before changing the color index, dash pattern, etc.

See the description of MAPITD, below.

Arguments

None.

MAPIQM (IAMA,XCRA,YCRA,MCRA, . . . )

(The remaining arguments are IAAI, IAGI, NOGI, and ULPR.)

Terminates a string of calls to the routine MAPITM.

Usage

The statement

      CALL MAPIQM (IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

flushes MAPITM's buffers. It is particularly important that this be done before a STOP, a CALL FRAME, or a call to change line color, width, dash pattern, etc.

See the description of MAPITM, below.

There is currently no example available for the routine MAPIQM.

Arguments

IAMA, XCRA, YCRA, MCRA, IAAI, IAGI, NOGI, and ULPR are all as described for the routine MAPITM (described below).

MAPIT (RLAT,RLON,IFST)

Draws lines on a map.

Usage

MAPIT is used to draw lines on a map; it is called by various EZMAP routines (MAPLOT, MAPGRD, MAPVEC, and MPLNDR) and may also be called directly by the user. MAPIT attempts to omit non-visible portions of lines and to handle "cross-over" - a jump from one end of the map to the other caused by the projection's having slit the globe along some half of a great circle and laid it open with the two sides of the slit at opposite ends of the map. Cross-over can occur on cylindrical and conical projections; MAPIT handles it gracefully on the former and not quite so well on the latter.

The EZMAP parameter 'DL' determines whether MAPIT draws solid lines or dotted lines. Dotted lines are drawn using calls to POINTS. Solid lines are drawn using calls to DASHD, FRSTD, and VECTD. The EZMAP parameters 'DD' and 'MV' also affect MAPIT's behavior. See the description of these parameters in the section "INTERNAL PARAMETERS".

A sequence of calls to MAPIT should be followed by a call to MAPIQ (which see, above) to flush its buffers before a STOP, a CALL FRAME, or a call to change the color index, line width, dash pattern, or the like.

Beware of intermingling calls to MAPIT and calls to MAPITD; the two routines share buffer space and intermingling the calls will have undesirable effects.

Because the entire line segment joining the points in two contiguous pen-down calls to MAPIT is considered visible if both of the points are visible and invisible if both of the points are invisible, such points should not be too far apart on the globe.

See the example named "mpexfi".

Arguments

RLAT and RLON (input expressions, of type REAL) specify the latitude and longitude of a point to which the "pen" is to be moved. Both are given in degrees. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

IFST (an input expression, of type INTEGER) is 0 to do a "pen-up" move, 1 to do a "pen-down" move only if the distance from the last point to the new point is greater than 'MV' plotter units, and 2 or greater to do a "pen-down" move regardless of the distance from the last point to the new one.

MAPITA (RLAT,RLON,IFST,IAMA,IGID,IAIL,IAIR)

Usage

The routines MAPITA and MAPIQA may be used to add lines defined by a set of user-specified latitudes and longitudes to an area map; they attempt to omit non-visible portions of lines and to handle "cross-over", in the same way that MAPIT does.

MAPITA is called like the EZMAP routine MAPIT (which see, above) but has some additional arguments:

      CALL MAPITA (RLAT,RLON,IFST,IAMA,IGID,IAIL,IAIR)

Additional arguments are the area map array IAMA, a group identifier IGID, and left and right area identifiers IAIL and IAIR. MAPIQA is called like the EZMAP routine MAPIQ, to terminate a series of calls to MAPITA and to flush the buffers; it has the same additional arguments:

      CALL MAPIQA (IAMA,IGID,IAIL,IAIR)

The additional arguments are passed by MAPITA and MAPIQA to the routine AREDAM, in the package named AREAS, for which a reference document is available.

See the example named "cpex08", which is described in the reference document for the package named CONPACK.

Arguments

IAMA (an input/output array of type INTEGER, dimensioned as specified in a call to the AREAS initialization routine ARINAM) is the area map to which lines in MAPITA's buffer are to be added.

IGID (an input expression of type INTEGER) is the group identifier to be passed to the AREAS routine AREDAM when the lines in MAPITA's buffer are added to the area map in IAMA.

IAIL (an input expression of type INTEGER) is the left area identifier to be passed to the AREAS routine AREDAM when the lines in MAPITA's buffer are added to the area map in IAMA.

IAIR (an input expression of type INTEGER) is the right area identifier to be passed to the AREAS routine AREDAM when the lines in MAPITA's buffer are added to the area map in IAMA.

MAPITD (RLAT,RLON,IFST)

Draws lines on a map using the new dash package DASHPACK.

Usage

MAPITD is used to draw lines on a map; it is not called by any of the EZMAP routines, but is intended to be called directly by the user. MAPITD is just like MAPIT except that it uses the new dash package DASHPACK instead of the old DASHCHAR; it attempts to omit non-visible portions of lines and to handle "cross-over" - a jump from one end of the map to the other caused by the projection's having slit the globe along some half of a great circle and laid it open with the two sides of the slit at opposite ends of the map. Cross-over can occur on cylindrical and conical projections; MAPITD handles it gracefully on the former and not quite so well on the latter.

The EZMAP parameter 'DL' determines whether MAPITD draws solid lines or dotted lines. Dotted lines are drawn using calls to POINTS. Solid lines are drawn using calls to DPFRST, DPVECT, and DPLAST. The EZMAP parameters 'DD' and 'MV' also affect MAPITD's behavior. See the descriptions of these parameters in the section "INTERNAL PARAMETERS".

A sequence of calls to MAPITD should be followed by a call to MAPIQD (which see, above) to flush its buffers before a STOP, a CALL FRAME, or a call to change the color index, line width, dash pattern, or the like.

Beware of intermingling calls to MAPIT and calls to MAPITD; the two routines share buffer space and intermingling the calls will have undesirable effects.

Because the entire line segment joining the points in two contiguous pen-down calls to MAPITD is considered visible if both of the points are visible and invisible if both of the points are invisible, such points should not be too far apart on the globe.

Arguments

MAPITM (RLAT,RLON,IFST,IAMA,XCRA,YCRA,MCRA, . . . )

(The remaining arguments are IAAI, IAGI, NOGI, and ULPR.)

Usage

The routines MAPITM and MAPIQM may be used to draw lines defined by a set of user-specified latitudes and longitudes on a map, masked by the areas defined by an area map (perhaps one created by a call to MAPBLA or perhaps one created by a set of calls to routines in the package AREAS); like MAPIT and MAPIQ, they attempt to omit non-visible portions of lines and to handle "cross-over".

MAPITM is called like the EZMAP routine MAPIT (which see, above) but has some additional arguments:

      CALL MAPITM (RLAT,RLON,IFST,IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

Additional arguments are the area-map array IAMA, coordinate arrays XCRA and YCRA, dimensioned MCRA, integer arrays IAAI and IAGI, dimensioned NOGI, and a user-provided line-processing routine named ULPR. MAPIQM is called like the EZMAP routine MAPIQ, to terminate a series of calls to MAPITM and to flush the buffers; it has the same additional arguments:

      CALL MAPIQM (IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

The additional arguments are passed by MAPITM and MAPIQM to the routine ARDRLN, in the package named AREAS, for which a reference document is available.

No example is currently available for MAPITM.

Arguments

IAMA (an input/output array of type INTEGER, dimensioned as specified in a call to the AREAS initialization routine ARINAM) is the array containing the area map against which lines drawn by MAPIQM will be masked.

XCRA and YCRA (scratch arrays of type REAL, each dimensioned MCRA) are to be passed by MAPIQM to the AREAS routine ARDRLN, which uses them in calls to the user line-processing routine ULPR. They will hold the X and Y coordinates of points in the fractional coordinate system defining some portion of the projection of a user-defined polyline on the globe.

MCRA (an input expression of type INTEGER) is the size of each of the arrays XCRA and YCRA. The value of MCRA must be at least two. For most applications, the value 100 works nicely.

IAAI and IAGI (scratch arrays of type INTEGER, each dimensioned NOGI) are to be passed by MAPIQM to the AREAS routine ARDRLN, which uses them in calls to the user line-processing routine ULPR. They will hold area identifier/group identifier pairs for the area containing the polyline fragment defined by XCRA and YCRA.

NOGI (an input expression of type INTEGER) is the size of each of the arrays IAAI and IAGI. The value of NOGI must be greater than or equal to the number of groups of edges placed in the area map in IAMA.

ULPR is the name of a user-provided line-processing routine. This name must appear in an EXTERNAL statement in the routine that calls MAPITM, so that the compiler and loader will know that it is the name of a routine to be called, rather than the name of a variable.

MAPLBL

Labels the map.

Usage

The statement

      CALL MAPLBL

if the parameter 'LA' is set appropriately, labels the international date line (ID), the equator (EQ), the Greenwich Meridian (GM), and the poles (NP and SP), and, if the parameter 'PE' is set appropriately, draws the perimeter of the map. If EZMAP needs initialization or if there is an uncleared NCAR Graphics error, MAPLBL does nothing.

See the example named "eezmpa".

Arguments

None.

MAPLOT

Draws geographical 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 (which see, below).

Usage

The statement

      CALL MAPLOT

draws the continental and/or international and/or U.S. state outlines selected by the EZMAP parameter 'OU'; the parameter 'DO' determines whether solid lines or dotted lines are used. If EZMAP currently needs initialization or if there is an uncleared NCAR Graphics error, MAPLOT does nothing.

The outlines are drawn using calls to MAPIT and MAPIQ. By default, MAPLOT forces the value of the internal parameter 'DL' equal to the value of the internal parameter 'DO'; it also supplies the dash package with a solid-line dash pattern. When 'DO' is zero, the outlines are drawn using calls to the routines FRSTD and VECTD, in the dash package, and this gives solid lines. When 'DO' is non-zero, the outlines are drawn using calls to the SPPS routine POINTS, which gives dotted lines. Before returning control to the user, MAPLOT restores the original value of 'DL' and the original dash pattern. A user version of the routine MAPUSR may be supplied to change the way in which the outlines are drawn (as shown in the example "mpex09").

See the examples named "mpex09" and "eezmpa".

Arguments

None.

MAPPOS (XLOW,XROW,YBOW,YTOW)

Positions the map on the plotter frame.

Usage

The statement

      CALL MAPPOS (XLOW,XROW,YBOW,YTOW)

sets four EZMAP parameters specifying the position of a window in the plotter frame within which maps are to be drawn. Each of the arguments is between 0. and 1., inclusive, and specifies the position of one edge of the window, as a fraction of the distance from left to right, or from bottom to top, across the window. The map is centered within the window and made as large as possible, but maintains its intrinsic shape (aspect ratio).

If it is desired to give a map a different aspect ratio than that implied by the projection being used, it will be necessary to insert, immediately after the call to MAPINT, an appropriate call to SET to override the one done by MAPINT and therefore to specify precisely the mapping of the u/v plane into a desired viewport on the plotter frame. Typically, one might call GETSET to find out what arguments 5-8 should be in one's own call to SET. Note that, if MAPDRW is being called, that call will have to be replaced by calls directly to MAPINT, MAPGRD, MAPLBL, and MAPLOT, in order to allow one's own call to SET to be placed immediately after the call to MAPINT.

See the examples named "mpex04", "mpex05", "mpex06", and "mpex07".

Arguments

XLOW (an input expression, of type REAL) specifies the position of the left edge of the window. The default is .05.

XROW (an input expression, of type REAL) specifies the position of the right edge of the window. The default is .95.

YBOW (an input expression, of type REAL) specifies the position of the bottom edge of the window. The default is .05.

YTOW (an input expression, of type REAL) specifies the position of the top edge of the window. The default is .95.

MAPROJ (JPRJ,PLAT,PLON,ROTA)

Set the projection to be used.

Usage

The statement

      CALL MAPROJ (JPRJ,PLAT,PLON,ROTA)

sets EZMAP parameters specifying the projection to be used for subsequent maps.

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", "mpex09", "mpex10", and "eezmpa".

Arguments

JPRJ (an input expression, of type CHARACTER) defines the desired projection type. All the possible values are two characters in length; these are the possibilities:

The conic projection:

'LC' - Lambert conformal conic with two standard parallels.

The azimuthal projections:

'ST' - Stereographic.
'OR' - Orthographic. The EZMAP parameter 'SA' will be zeroed. See the note below.
'LE' - Lambert equal area.
'GN' - Gnomonic.
'AE' - Azimuthal equidistant.
'SV' - Satellite-view. If the EZMAP parameter 'SA' is less than or equal to 1., it will be reset to 6.631 (the value for a satellite in a geosynchronous orbit). See the note below.

The cylindrical projections:

'CE' - Cylindrical equidistant.
'ME' - Mercator.
'MO' - Mollweide-type.

Note: The orthographic and satellite-view projections have the same internal identifier. The EZMAP parameter 'SA' determines which will be used. If a call to MAPROJ selecting one or the other is followed by a call to MAPSTR resetting 'SA', it may have the effect of causing the other to be used. See the description of 'SA', below, in the description of the routine MAPSTx.

PLAT, PLON, and ROTA (input expressions, of type REAL) are angular quantities, in degrees. How they are used depends on the value of JPRJ, as follows:

If JPRJ is not equal to 'LC': PLAT and PLON define the latitude and longitude of the pole of the projection - the point on the globe which is to project to the origin of the u/v plane. PLAT must be between -90. and +90., inclusive, positive in the northern hemisphere, negative in the southern. PLON must be between -180. and +180., inclusive, positive to the east, and negative to the west, of Greenwich. ROTA is the angle between the v axis and north at the origin. It is taken to be positive if the angular movement from north to the v axis is counter-clockwise, negative otherwise. If the origin is at the north pole, "north" is considered to be in the direction of PLON+180. If the origin is at the south pole, "north" is considered to be in the direction of PLON. For the cylindrical projections, the axis of the projection is parallel to the v axis.
If JPRJ is equal to 'LC': PLON defines the central meridian of the projection, and PLAT and ROTA define the two standard parallels. If PLAT and ROTA are equal, a simpler conic projection, with one standard parallel, is used.

For more detailed descriptions of the projections, see the section named "PROJECTIONS".

MAPRS

Re-calls SET.

Usage

The statement

      CALL MAPRS

repeats the SET call last done by the routine MAPINT. This might be used when user lines are to be plotted over a map generated in a different overlay (e.g., using a flash buffer), and when the system plot package does not reside in an outer overlay.

No example is available for MAPRS.

Arguments

None.

MAPRST (IFNO)

Restores the state of EZMAP saved by an earlier call to MAPSAV.

Usage

The statement

      CALL MAPRST (IFNO)

restores EZMAP to a previously saved state (frequently the default state) by reading, from the unit specified by IFNO, values of all user-settable parameters, and then executing MAPINT.

No example is available for MAPRST.

Arguments

IFNO (an input expression, of type INTEGER) is the number of a unit from which a single unformatted record is to be read. It is the user's responsibility to position this unit. MAPRST does not rewind it, either before or after reading the record.

MAPSAV (IFNO)

Saves the current state of EZMAP for later restoration by MAPRST.

Usage

The statement

      CALL MAPSAV (IFNO)

saves the current state of EZMAP (frequently the default state) by writing, on the unit specified by IFNO, the current values of all the user-settable parameters.

No example is available for MAPSAV.

Arguments

IFNO (an input expression, of type INTEGER) is the number of a unit to which a single unformatted record is to be written. It is the user's responsibility to position this unit. MAPSAV does not rewind it, either before or after writing the record.

MAPSET (JLTS,PLM1,PLM2,PLM3,PLM4)

To specify the rectangular portion of the u/v plane to be drawn.

Usage

The statement

      CALL MAPSET (JLTS,PLM1,PLM2,PLM3,PLM4)

specifies what portion of the u/v plane is to be plotted.

See the examples named "mpex01", "mpex02", "mpex04", "mpex07", "mpex09", "mpex10", and "eezmpa".

Arguments

JLTS (an input expression, of type CHARACTER) is a character string specifying how the limits of the map are to be chosen. There are five possibilites, as follows:

JLTS='MA' (MAXIMUM). The maximum useful area produced by the projection is plotted. PLM1, PLM2, PLM3, and PLM4 are not used.
JLTS='CO' (CORNERS). The points (PLM1,PLM2) and (PLM3,PLM4) are to be at opposite corners of the map. PLM1 and PLM3 are latitudes, in degrees. PLM2 and PLM4 are longitudes, in degrees. If a cylindrical projection is being used, the first point should be on the left edge of the map and the second point on the right edge; otherwise, the order makes no difference. Note that, even though the specified points will be at the corners of the map, you are not guaranteed that a point having a latitude between PLM1 and PLM3 and a longitude between PLM2 and PLM4 will be on the map; if that is what you want, you should use the "GRID" option, described below.
JLTS='PO' (POINTS). PLM1, PLM2, PLM3, and PLM4 are two-element arrays giving the latitudes and longitudes, in degrees, of four points which are to be on the edges of the rectangular map. If a cylindrical projection is being used, the first point should be on the left edge and the second point on the right edge; otherwise, the order makes no difference.
JLTS='AN' (ANGLES). PLM1, PLM2, PLM3, and PLM4 are positive angles, in degrees, representing angular distances from a point on the map to the left, right, bottom, and top edges of the map, respectively. For most projections, these angles are measured with the center of the earth at the vertex and represent angular distances from the point which projects to the origin of the u/v plane; on a satellite-view projection, they are measured with the satellite at the vertex and represent angular deviations from the line of sight. Angular limits are particularly useful for polar projections and for the satellite-view projection; they are not appropriate for the Lambert conformal conic and an error will result if one attempts to use JLTS='AN' with JPRJ='LC'.
JLTS='LI' (LIMITS). PLM1, PLM2, PLM3, and PLM4 specify the minimum value of u, the maximum value of u, the minimum value of v, and the maximum value of v, respectively. Knowledge of the projection equations is necessary in order to use this option correctly.
JLTS='GR' (GRID). PLM1, PLM2, PLM3, and PLM4 specify a minimum latitude, a minimum longitude, a maximum latitude, and a maximum longitude, in degrees. The map limits will be set up in such a way that an entire "grid" of data in the area defined by these limits will be visible on the map.

PLM1, PLM2, PLM3, and PLM4 (input arrays, dimensioned 2, of type REAL) are as described above, depending on the value of JLTS. Note that each is a two-element array. Strictly speaking, the FORTRAN standard requires that they be declared as such, even when only the first element of each array is used.

MAPSTx (PNAM,xVAL) or MPSETx (PNAM,xVAL)

To set the values of certain EZMAP parameters. An alternate name, more nearly consistent with those used in other NCAR Graphics packages, is provided for this routine

Usage

Use one of the four statements

      CALL MAPSTC (PNAM,CVAL) or CALL MPSETC (PNAM,CVAL)
      CALL MAPSTI (PNAM,IVAL) or CALL MPSETI (PNAM,IVAL)
      CALL MAPSTL (PNAM,LVAL) or CALL MPSETL (PNAM,LVAL)
      CALL MAPSTR (PNAM,RVAL) or CALL MPSETR (PNAM,RVAL)

depending on whether the value to be set is of type CHARACTER, INTEGER, LOGICAL, or REAL. Some parameters may be set in more than one way. For example, the parameter 'GR', which specifies the grid spacing, may be given the value 10.0 in either of two ways:

      CALL MAPSTI ('GR',10)
      CALL MAPSTR ('GR',10.)

The flag which controls dotting of outlines may be turned on using either of these calls:

      CALL MAPSTI ('DO',1)
      CALL MAPSTL ('DO',.TRUE.)

The important point to remember is that the last character of the routine name implies the type of its second argument.

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", "mpex08", "mpex09", "mpex10", "mpexfi", and "eezmpa".

Arguments

PNAM (an input expression, of type CHARACTER*2) specifies the name of an internal parameter whose value is to be set. Only the first two characters of this string are examined.

xVAL (an input expression of type CHARACTER, INTEGER, LOGICAL, or REAL, depending on which routine is called) contains the value to be given to the parameter specified by PNAM.

See the section "INTERNAL PARAMETERS" for descriptions of all the internal parameters.

MAPTRA (RLAT,RLON,UVAL,VVAL)

To project points.

MAPTRA is just like MAPTRN except that, if a point being projected is outside the boundary of the map (as defined by the last call to MAPSET and by the value of the internal parameter 'EL'), a special value is returned to signal this condition; see the sub-section named "Arguments", below. (The default version of the CONPACK routine named CPMPXY now calls MAPTRA, rather than MAPTRN; it was for this purpose that MAPTRA was created, but users may wish to call it, as well.)

Usage

The statement

      CALL MAPTRA (RLAT,RLON,UVAL,VVAL)

is used to find the projection in the u/v plane of a point whose latitude and longitude are known. MAPTRA may be called at any time after EZMAP has been initialized (by calling MAPINT or otherwise).

Currently, no example is available for MAPTRA.

Arguments

RLAT and RLON (input expressions, of type REAL) are the latitude and longitude, respectively, of a point on the globe. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

UVAL and VVAL (output variables, of type REAL) define the point (UVAL,VVAL) that is the projection in the u/v plane of (RLAT,RLON). The units of UVAL and VVAL depend on the projection.

If the point is not projectable or if it is outside the boundary of the map, as defined by the last call to MAPSET and by the value of the parameter 'EL', UVAL is returned equal to 1.E12.

MAPTRI (UVAL,VVAL,RLAT,RLON)

To perform inverse transformations.

Usage

The statement

      CALL MAPTRI (UVAL,VVAL,RLAT,RLON)

is used to find the latitude and longitude of a point whose projection in the u/v plane is known. MAPTRI may be called at any time after EZMAP has been initialized (by calling MAPINT or otherwise).

See the example named "mpex10".

Arguments

UVAL and VVAL (input expressions, of type REAL) define the point (UVAL,VVAL) that is the projection in the u/v plane of the point whose latitude and longitude are desired. The units of UVAL and VVAL depend on the projection.

RLAT and RLON (output variables, of type REAL) are the latitude and longitude, respectively, of the point, in degrees. RLAT will be between -90. and +90., inclusive; RLON will be between -180. and +180., inclusive.

If the point (UVAL,VVAL) is not the projection of some point of the globe or is outside the boundary of the map, RLAT and RLON are returned equal to 1.E12.

MAPTRN (RLAT,RLON,UVAL,VVAL)

To project points.

Usage

The statement

      CALL MAPTRN (RLAT,RLON,UVAL,VVAL)

is used to find the projection in the u/v plane of a point whose latitude and longitude are known. MAPTRN may be called at any time after EZMAP has been initialized (by calling MAPINT or otherwise).

See the example named "mpex09".

Arguments

RLAT and RLON (input expressions, of type REAL)are the latitude and longitude, respectively, of a point on the globe. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

UVAL and VVAL (output variables, of type REAL) define the point (UVAL,VVAL) that is the projection in the u/v plane of (RLAT,RLON). The units of UVAL and VVAL depend on the projection.

If the point is not projectable, UVAL is returned equal to 1.E12. Note that, if the point is projectable, but outside the boundary of the map, as defined by the last call to MAPSET, its u and v coordinates are still returned by MAPTRN. The user must do the test required to determine if the point is within limits, if that is necessary.

MAPUSR (IPRT)

This routine is called by EZMAP routines that draw the various parts of a map, to allow for user changes in the appearance of the map. Note, however, that MAPUSR is not called by either of the EZMAPB routines MPLNDM or MPLNDR.

Usage

EZMAP routines (with the exception of MPLNDM and MPLNDR, which instead call MPCHNL - which see, below) execute the statement

      CALL MAPUSR (IPRT)

just before and just after each portion of a map is drawn. The default version of MAPUSR does nothing.

A user-supplied version of MAPUSR may set/reset the dotting parameter 'DL', the DASHCHAR dash pattern, the color index, etc., so as to achieve a desired effect.

See the example named "mpex08".

Arguments

IPRT (input expression, of type INTEGER), if positive, says that a particular part of the map is about to be drawn, as follows:

IPRT Part of map about to be drawn
1 Perimeter.
2 Grid.
3 Labels.
4 Limb lines.
5 Continental outlines.
6 U.S. state outlines.
7 International outlines.

IPRT	Part of map about to be drawn
1	Perimeter.
2	Grid.
3	Labels.
4	Limb lines.
5	Continental outlines.
6	U.S. state outlines.
7	International outlines.

If IPRT is negative, it says that drawing of the last part is complete. The absolute value of IPRT will be one of the above values. Changed quantities should be restored.

MAPVEC (RLAT,RLON)

Draws lines on a map - used in conjunction with MAPFST.

Usage

The statement

      CALL MAPVEC (RLAT,RLON)

is equivalent to the statement

      CALL MAPIT (RLAT,RLON,1)

See the description of MAPIT.

Arguments

RLAT and RLON (input expressions, of type REAL) are defined as for MAPIT (which see).

MPCHLN (IACT,ILTY,IOAL,IOAR,NPTS,PNTS)

This routine is called repeatedly as boundary lines are processed by MPLNAM, MPLNDM, and MPLNDR. The default version of the routine does nothing.

Usage

The statement

      CALL MPCHLN (IACT,ILTY,IOAL,IOAR,NPTS,PNTS)

is executed by each of the routines MPLNAM, MPLNDM, and MPLNDR just before and just after the processing of each boundary line read from a specified map database. A user-supplied version may take action to change various characteristics of the lines. For example, the area identifiers to be used for the line can be changed, the line can be deleted entirely, and line styles, colors, and widths can be set.

See the example named "mpex11".

Arguments

IACT (an input expression of type INTEGER) specifies which of the EZMAPB routines has called MPCHLN and what that routine is doing or has done with the boundary line defined by the arguments NPTS and PNTS. IACT is positive if the line is about to be processed, negative if the line was just processed; its absolute value is 1 if the call comes from MPLNAM (which puts lines into an area map), 2 if the call comes from MPLNDM (which draws lines masked by some area map), and 3 if the call comes from MPLNDR (which just draws lines).

ILTY (an input expression of type INTEGER) specifies the type of the line: 1 => a line separating land from water, 2 => a line separating one "continent" from another (as, for example, Africa from Eurasia, North America from Central America, or Central America from South America), 3 => a line separating one country from another, 4 => a line separating one state from another, and 5 => a line separating one county from another.

IOAL and IOAR (input/output variables of type INTEGER) are the identifiers of the areas to the left and right, respectively, of the line. (Left and right are defined from the standpoint of a viewer standing at point 1 of the line and looking toward point 2.) The values of IOAL and IOAR may be changed by a knowledgeable user.

NPTS (an input/output variable of type INTEGER), on entry, is the number of points defining the line. NPTS may be zeroed by MPCHLN to suppress any use of the line by the calling routine.

PNTS (an input/output array, dimensioned 2*NPTS, of type REAL) is an array of point coordinates. PNTS(1) and PNTS(2) are the latitude and longitude of the first point, PNTS(3) and PNTS(4) the latitude and longitude of the second point, ... PNTS(2*NPTS-1) and PNTS(2*NPTS) the latitude and longitude of the last point. All values are in degrees. Longitudes are all between -180 and +180; no segment crosses the meridian at -180 (+180) degrees.

MPFNME(IAIN,ILVL)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the full name of the area, including the prepended names of all containing (parent) areas, up to and including a specified level. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then the following are true:

    MPFNME(IMAD,5) = 'Madeline Island (Lake Superior)'
    MPFNME(IMAD,4) = 'Wisconsin - Madeline Island (Lake Superior)'
    MPFNME(IMAD,3) = 'United States - Conterminous US - Wisconsin -
					    Madeline Island (Lake Superior)'
    MPFNME(IMAD,2) = 'North America - United States - Conterminous US -
				Wisconsin - Madeline Island (Lake Superior)'
    MPFNME(IMAD,1) = 'Land - North America - United States - Conterminous
			   US - Wisconsin - Madeline Island (Lake Superior)'

To get the full name of the area, at a specified level, that contains the area having a specified area identifier, use MPFNME in combination with MPIOSA (which see). For example,

    MPFNME(MPIOSA(IMAD,5),5) = 'Madeline Island (Lake Superior)'
    MPFNME(MPIOSA(IMAD,4),4) = 'Wisconsin - Madeline Island (Lake Superior)'
    MPFNME(MPIOSA(IMAD,3),3) = 'United States - Conterminous US'
    MPFNME(MPIOSA(IMAD,2),2) = 'North America'
    MPFNME(MPIOSA(IMAD,1),1) = 'Land'

Usage

The statements

      CHARACTER*128 MPFNME,FNME
      ...

      FNME=MPFNME(IAIN,ILVL)

retrieve in FNME the full name of the area with area identifier IAIN, including the prepended names of containing (parent) areas, up to the level ILVL.

See the example named "mpex12".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

ILVL is an input expression of type INTEGER, specifying the highest level of containing (parent) name to be included in the returned full name.

MPGETx (PNAM,xVAL) and MPSETx (PNAM,xVAL)

These routines are alternate entry points for MAPGTx and MAPSTx, respectively. See the descriptions of those routines.

MPGLTY (ILTY)

Retrieve the type of the line currently being drawn by MPLNDM.

Usage

The statement

      CALL MPGLTY (ILTY)

may be placed inside a line-processing routine whose name is used in a call to MPLNDM to retrieve, in ILTY, the type of the line being processed. This information may be used to determine how the line is to be drawn.

See the example named "mpex11".

Arguments

ILTY (an output variable of type INTEGER) is the type of the line: 1 => a line separating land from water, 2 => a line separating one "continent" from another (as, for example, Africa from Eurasia, North America from Central America, or Central America from South America), 3 => a line separating one country from another, 4 => a line separating one state from another, and 5 => a line separating one county from another. If the current line is used on more than one level (as, for example, a portion of the California coastline, which is used on all five levels), then the value of ILTY will be the smallest of the numerical values that apply.

MPIATY(IAIN)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the area type of the area. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPIATY(IMAD) is 4, implying that this island is a portion of a state.

Usage

The statement

      IATY=MPIATY(IAIN)

retrieves in IATY the area type of the area with area identifier IAIN.

See the example named "mpex12".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

MPIFNB(CHRS)

This is a simple utility function that finds the index of the first non-blank character in a character string.

Usage

The statement

      IFNB=MPIFNB(CHRS)

sets the value of IFNB to the index (between 1 and LEN(CHRS)) of the first non-blank character in the character string CHRS.

Arguments

CHRS is an input expression of type CHARACTER.

MPILNB(CHRS)

This is a simple utility function that finds the index of the last non-blank character in a character string.

Usage

The statement

      ILNB=MPILNB(CHRS)

sets the value of ILNB to the index (between 1 and LEN(CHRS)) of the last non-blank character in the character string CHRS.

Arguments

CHRS is an input expression of type CHARACTER.

MPIOLA(IAIN,ILVL)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the area identifier of the largest area, at a specified level, that contains it. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPIOLA(IMAD,3) is the area identifier of an area called "United States".

Usage

The statement

      IOLA=MPIOLA(IAIN,ILVL)

retrieves in IOLA the area identifier of the largest area, at level ILVL, that contains the area with area identifier IAIN.

See the examples named "mpex11", "mpex11", and "tezmpb".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

ILVL is an input expression of type INTEGER, specifying the level of the containing area to be found.

MPIOSA(IAIN,ILVL)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the area identifier of the smallest area, at a specified level, that contains it. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPIOSA(IMAD,3) is the area identifier of the area called "Conterminous US".

Usage

The statement

      IOSA=MPIOSA(IAIN,ILVL)

retrieves in IOSA the area identifier of the smallest area, at level ILVL, that contains the area with area identifier IAIN.

See the examples named "mpex11", "mpex11", and "tezmpb".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

ILVL is an input expression of type INTEGER, specifying the level of the containing area to be found.

MPIPAI(IAIN,IAIP)

(The name MPIPAI stands for "MaP, Is Part of Area with Identifier ...".)

Given the area identifiers of two of the areas defined by whatever database was last read by the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function has a non-zero value if and only if the first area is part of the second area. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", ICUS is the area identifier of the area called 'Conterminous US', and IRUS is the area identifier of the area called 'Russia', then MPIPAI(IMAD,ICUS) has a non-zero value, but MPIPAI(IMAD,IRUS) does not.

Usage

The statement

      IPRT=MPIPAI(IAIN,IAIP)

sets IPRT non-zero if and only if the area having area identifier IAIN is a part of the area having area identifier IAIP.

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a first area of interest.

IAIP is an input expression of type INTEGER, specifying the area identifier of a second area of interest.

MPIPAN(IAIN,ANME)

(The name MPIPAN stands for "MaP, Is Part of Area with Name ... ".)

Given the area identifier of one of the areas defined by whatever database was last read by the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI and a name, this function has a non-zero value if and only if the area with the specified area identifier is part of some area with the specified name. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPIPAN(IMAD,'Conterminous US') has a non-zero value, but MPIPAN(IMAD,'Russia') does not.

Usage

The statement

      IPRT=MPIPAN(IAIN,ANME)

sets IPRT non-zero if and only if the area having area identifier IAIN is a part of some area having the name ANME.

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

ANME is an input expression of type CHARACTER, specifying a name of interest.

MPIPAR(IAIN)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the area identifier of that area's containing (parent) area. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPIPAR(IMAD) is the area identifier of the area called "Wisconsin".

Usage

The statement

      IPAR=MPIPAR(IAIN)

retrieves in IPAR the area identifier of the parent of the area with area identifier IAIN.

See the example named "mpex12".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

MPISCI(IAIN)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns a suggested color index for that area. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPISCI(IMAD) has the value 6. The suggested color indices are defined in such a way as to ensure that areas that touch each other have different color indices.

To get a suggested color index for the area, at a specified level, that contains the area with a specified area identifier, use MPISCI in combination with MPIOSA (which see). For example,

    MPISCI(MPIOSA(IMAD,5)) = 6 (color index for "Wisconsin" or a part thereof)
    MPISCI(MPIOSA(IMAD,4)) = 6 (color index for "Wisconsin" or a part thereof)
    MPISCI(MPIOSA(IMAD,3)) = 3 (color index for "Conterminous US")
    MPISCI(MPIOSA(IMAD,2)) = 5 (color index for "North America")
    MPISCI(MPIOSA(IMAD,1)) = 2 (color index for "Land")

Usage

The statement

      ISCI=MPISCI(IAIN)

retrieves in ISCI the suggested color index for the area with area identifier IAIN.

See the examples named "mpex11", "mpex12", and "tezmpb".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

MPLNAM (FLNM,ILVL,IAMA)

Reads a specified EZMAP database and sends boundary lines from it to a specified area map.

Usage

The statement

      CALL MPLNAM (FLNM,ILVL,IAMA)

adds boundary lines to the area map in the array IAMA. The area map must previously have been initialized by calling the routine ARINAM, in the package AREAS, using a statement like "CALL ARINAM (IAMA,LAMA)", where LAMA is the length of the array IAMA. The area map may subsequently be used in various ways; for example, one may call the AREAS routine ARSCAM to draw a solid-filled map.

One or two groups of boundary lines are added to the area map by a call to MPLNAM. The first, having group identifier 'G1' (default value 1), consists of a perimeter (either rectangular or elliptical, depending on the value of the internal parameter 'EL') and the set of projected boundary lines implied by the user's selection of a map database and level. For certain projections, a limb line may also be included.

See the examples named "mpex11" and "tezmpb".

Arguments

FLNM is an input expression of type CHARACTER, specifying the name of the database to be used. MPLNAM will first look for the files of the specified database in the current working directory; if the files are not found there, MPLNAM will look for them in the NCAR Graphics database directory. The database created in 1998 and provided as part of Version 4.1 of NCAR Graphics has the name "Earth..1".

ILVL (an input expression of type INTEGER) specifies the level at which the database is to be used. The value 1 says to use only land/water boundaries, the value 2 says to add continental boundaries (like the boundary which separates Africa from Eurasia), the value 3 says to add the the boundaries of countries, and the value 4 says to add states. (The value 5 will eventually be used to add counties.)

IAMA (an input/output array of type INTEGER) is the area map array to which boundary lines are to be added.

MPLNDM (FLNM,ILVL,IAMA,XCRA,YCRA,MCRA, . . . )

(The remaining arguments are IAAI, IAGI, NOGI, and ULPR.)

Reads a specified EZMAP database and draws boundary lines from it, masked by a specified area map.

Usage

The statement

      CALL MPLNDM (FLNM,ILVL,IAMA,XCRA,YCRA,MCRA,IAAI,IAGI,NOGI,ULPR)

is used to draw the lines defined by the map database whose name is FLNM, masked against the area map in the array IAMA.

MPLNDM is much like MPLNDR, except that the boundary lines are drawn using calls to MAPITM and MAPIQM, which does the masking of the lines against an area map and passes the pieces resulting from the masking process along to a user-provided line-drawing routine.

See the example named "mpex11".

Arguments

FLNM is an input expression of type CHARACTER, specifying the name of the database to be used. MPLNDM will first look for the files of the specified database in the current working directory; if the files are not found there, MPLNDM will look for them in the NCAR Graphics database directory. The database created in 1998 and provided as part of Version 4.1 of NCAR Graphics has the name "Earth..1".

XCRA and YCRA (scratch arrays, dimensioned at least MCRA, of type REAL) are to be used by MPLNDM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR.

MCRA (an input expression of type INTEGER) is the dimension of the arrays XCRA and YCRA.

IAAI and IAGI (scratch arrays, dimensioned at least NOGI, of type INTEGER) are to be used by MPLNDM in calls to the AREAS routine ARDRLN; they will eventually be used in calls to the user-provided line-processing routine ULPR. The mnemonics stand for "Integer Array of Area Identifiers" and "Integer Array of Group Identifiers", respectively.

ULPR is the name of the user-supplied line-processing routine. It must be declared EXTERNAL in the routine that calls MPLNDM, so that the compiler and loader will know that it is the name of a routine to be called instead of a variable. The user routine ULPR will be called once for each piece of a boundary line resulting from the masking process; it may decide to draw (or to not draw) each such piece. ULPR will be called using a FORTRAN statement like

      CALL ULPR (XCRA,YCRA,NCRA,IAAI,IAGI,NGPS)

MPLNDR (FLNM,ILVL)

Reads a specified EZMAP database and draws boundary lines from it.

Usage

The statement

      CALL MPLNDR (FLNM,ILVL)

draws the lines defined by the map database whose name is FLNM; the EZMAP internal parameter 'DO' determines whether solid lines or dotted lines are used. If EZMAP currently needs initialization, MPLNDR does nothing except read some information from the map database, so that subsequent calls to EZMAPB functions will work properly.

The outlines are drawn using calls to MAPIT and MAPIQ. By default, MPLNDR forces the value of the internal parameter 'DL' equal to the value of the internal parameter 'DO'; it also supplies the dash package with a solid-line dash pattern. When 'DO' is zero, the outlines are drawn using calls to the routines FRSTD and VECTD, in the dash package, and this gives solid lines. When 'DO' is non-zero, the outlines are drawn using calls to the SPPS routine POINTS, which gives dotted lines. Before returning control to the user, MAPLOT restores the original value of 'DL' and the original dash pattern. A user version of the routine MPCHLN may be supplied to change the way in which the outlines are drawn.

See the example named "tezmpb".

Arguments

FLNM is an input expression of type CHARACTER, specifying the name of the database to be used. MPLNDR will first look for the files of the specified database in the current working directory; if the files are not found there, MPLNDR will look for them in the NCAR Graphics database directory. The database created in 1998 and provided as part of Version 4.1 of NCAR Graphics has the name "Earth..1".

MPLNRI (FLNM)

Reads information from a specified EZMAP database.

Usage

The statement

      CALL MPLNRI (FLNM)

causes information about the database whose name is specified by FLNM to be read into EZMAPB common blocks. Subsequent references to functions like MPIATY, MPISCI, and so on make use of this data.

See the example named "mpex12".

Arguments

FLNM is an input expression of type CHARACTER, specifying the name of the database to be used. MPLNRI will first look for the files of the specified database in the current working directory; if the files are not found there, MPLNRI will look for them in the NCAR Graphics database directory. The database created in 1998 and provided as part of Version 4.1 of NCAR Graphics has the name "Earth..1".

MPNAME(IAIN)

Given the area identifier of one of the areas defined by whatever database was last read by one of the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, and MPLNRI, this function returns the name of the area. For example, if IMAD is the area identifier of the little island in Lake Superior called "Lake Madeline", then MPNAME(IMAD) = 'Madeline Island (Lake Superior)'.

To get the name of the area, at a specified level, that contains an area with a specified area identifier, use MPNAME in combination with MPIOSA and/or MPIOLA (which see). For example,

    MPNAME(MPIOLA(IMAD,5)) = Madeline Island (Lake Superior)
    MPNAME(MPIOLA(IMAD,4)) = Wisconsin
    MPNAME(MPIOLA(IMAD,3)) = United States
    MPNAME(MPIOLA(IMAD,2)) = North America
    MPNAME(MPIOLA(IMAD,1)) = Land
    and
    MPNAME(MPIOSA(IMAD,5)) = Madeline Island (Lake Superior)
    MPNAME(MPIOSA(IMAD,4)) = Madeline Island (Lake Superior)
    MPNAME(MPIOSA(IMAD,3)) = Conterminous US
    MPNAME(MPIOSA(IMAD,2)) = North America
    MPNAME(MPIOSA(IMAD,1)) = Land

Usage

The statements

      CHARACTER*64 MPNAME,NAME
      ...

      NAME=MPNAME(IAIN)

retrieve in NAME the name of the area with area identifier IAIN.

See the examples named "mpex11" and "mpex12".

Arguments

IAIN is an input expression of type INTEGER, specifying the area identifier of a particular area of interest.

MPRSET

Resets the internal state of EZMAP to the default.

Usage

The statement

      CALL MPRSET

may be used to reset the values of the internal parameters of EZMAP to the default and then recall the initialization routine MAPINT.

Arguments

None.

SUPCON (RLAT,RLON,UVAL,VVAL)

An old equivalent of the new routine MAPTRN. Provided for compatibility with earlier versions of EZMAP/SUPMAP. If efficiency is a consideration, bypass this routine and call MAPTRN directly.

Usage

The statement

      CALL SUPCON (RLAT,RLON,UVAL,VVAL)

is exactly equivalent to the statement

      CALL MAPTRN (RLAT,RLON,UVAL,VVAL)

Arguments

RLAT, RLON, UVAL, and VVAL are defined as for MAPTRN (which is described above).

SUPMAP (JPRJ,PLAT,PLON,ROTA, . . . )

(The remaining arguments are PLM1, PLM2, PLM3, PLM4, JLTS, JGRD, IOUT, IDOT, and IERR.)

An implementation of the routine from which EZMAP grew.

Usage

The statement

      CALL SUPMAP (JPRJ,PLAT,PLON,ROTA,PLM1,PLM2,PLM3,PLM4,JLTS,
     +             JGRD,IOUT,IDOT,IERR)

creates a map of a desired portion of the globe, according to a desired projection, with desired outlines drawn in, and with lines of latitude and longitude at desired intervals. An appropriate call to the routine SET is performed, and the routine SUPCON (which see) is initialized so that the user may map points of known latitude and longitude to points in the u/v plane and use the u/v coordinates to draw objects on the map produced by SUPMAP.

See the examples named "mpex03", "mpex08", and "mpexfi".

Arguments

JPRJ (input expression, of type INTEGER) defines the projection type and indicates whether or not continental outlines are to be plotted, as follows:

IABS(JPRJ) defines the projection type, as follows (values less than 1 or greater than 10 are treated as 1 or 10, respectively):

IABS(JPRJ) Projection Type
1 Stereographic.
2 Orthographic.
3 Lambert conformal conic.
4 Lambert equal area.
5 Gnomonic.
6 Azimuthal equidistant.
7 Satellite view.
8 Cylindrical equidistant.
9 Mercator.
10 Mollweide-type.

IABS(JPRJ)	Projection Type
1	Stereographic.
2	Orthographic.
3	Lambert conformal conic.
4	Lambert equal area.
5	Gnomonic.
6	Azimuthal equidistant.
7	Satellite view.
8	Cylindrical equidistant.
9	Mercator.
10	Mollweide-type.

: Using the value 2 causes the EZMAP parameter 'SA' to be zeroed. ('SA', if greater than 1., says that a satellite-view projection, rather than an orthographic projection, is to be used, and specifies the distance of the satellite from the center of the earth, in units of earth radii.)
: Using the value 7 causes 'SA' to be examined. If it has a non-zero value, the value is left alone. If it has a zero value, its value is reset to 6.631, which is about right for a satellite in a geosynchronous equatorial orbit.

The sign of JPRJ, when IOUT is -1, 0, or +1, indicates whether the continental outlines are to be plotted or not. See IOUT, below.

PLAT, PLON, and ROTA (input expressions, of type REAL) define the origin of the projection and its rotation angle and are used in the same way as they would be in a call to the routine MAPROJ (which see).

JLTS (input expression, of type INTEGER), and PLM1, PLM2, PLM3, and PLM4 (input arrays, dimensioned 2, of type REAL) specify the rectangular limits of the map. These arguments are used in the same way as they would be in a call to MAPSET (which see), except that JLTS is an integer instead of a character string. IABS(JLTS) may take on the values 1 through 5, as follows:

IABS(JLTS) Equivalent character string in a call to MAPSET
1 'MA' - maximal area desired.
2 'CO' - corner points given in PLM1, PLM2, PLM3, and PLM4.
3 'LI' - U/V limits given in PLM1, PLM2, PLM3, and PLM4.
4 'AN' - angles given in PLM1, PLM2, PLM3, and PLM4.
5 'PO' - edge points given in PLM1, PLM2, PLM3, and PLM4.

IABS(JLTS)	Equivalent character string in a call to MAPSET
1	'MA' - maximal area desired.
2	'CO' - corner points given in PLM1, PLM2, PLM3, and PLM4.
3	'LI' - U/V limits given in PLM1, PLM2, PLM3, and PLM4.
4	'AN' - angles given in PLM1, PLM2, PLM3, and PLM4.
5	'PO' - edge points given in PLM1, PLM2, PLM3, and PLM4.

At one time, the sign of JLTS specified whether or not a line of text was to be written at the bottom of the plot produced. This line may no longer be written and the sign of JLTS is therefore ignored.

JGRD (input expression, of type INTEGER) is used in the following way: The value of "MOD(IABS(JGRD),1000)" is the value, in degrees, of the interval at which lines of latitude and longitude are to be plotted. If the given interval is zero, grid lines and labels are not plotted. If JGRD is less than zero, the perimeter is not plotted. Set JGRD to -1000 to suppress both grid lines and perimeter and to +1000 to suppress the grid lines, but leave the perimeter. The value -0 may have a meaning on ones' complement machines, but should be avoided; use -1000 instead.

IOUT (input expression, of type INTEGER) has the value 0 to suppress U.S. state outlines, and the value -1 or +1 to plot U.S. state outlines. In both of these cases, the sign of JPRJ indicates whether continental outlines are to be plotted (JPRJ positive) or not (JPRJ negative). Originally, SUPMAP recognized only these values of IOUT; now, if IOUT is less than 0 or greater than 1, the sign of JPRJ is ignored, and IOUT selects an outline group, as follows:

IOUT Outline group selected
-2 or less 'NO' (no outlines)
2 'CO' (continental outlines)
3 'US' (U.S. state outlines)
4 'PS' (continental outlines plus international outlines plus U.S. state outlines)
5 or greater 'PO' (continental outlines plus international outlines)

IOUT	Outline group selected
-2 or less	'NO' (no outlines)
2	'CO' (continental outlines)
3	'US' (U.S. state outlines)
4	'PS' (continental outlines plus international outlines plus U.S. state outlines)
5 or greater	'PO' (continental outlines plus international outlines)

At one time, the sign of IOUT specified whether or not a line of text was to be written on the print output unit. This may no longer be done.

IDOT (input expression, of type INTEGER) is a 0 to get continuous outlines, a 1 to get dotted outlines.

IERR (output variable, of type INTEGER) is the only output parameter. A non-zero value indicates that an error has occurred. The section "ERROR CONDITIONS" lists the possible values of IERR.

INTERNAL PARAMETERS

EZMAP has a large group of internal parameters, each of which affects the behavior of one or more of the EZMAP routines. The current values of the internal parameters may be retrieved using the routines MAPGTC, MAPGTI, MAPGTL, and MAPGTR. The values of most of the internal parameters may be reset using the routines MAPSTC, MAPSTI, MAPSTL, and MAPSTR; some of the parameters are intended for retrieval only and may not be given new values in this way. In the following table are listed, in alphabetical order, all of the internal parameters of EZMAP:

Name Type Description
'AR' C For retrieval only. The value of the map limits specifier JLTS from the last call to MAPSET. The default value is 'MA'.
'Cn' I "n" is an integer between 1 and 7. Each 'Cn', if zero or greater, specifies the color index of some part of the map. The user must do the calls to GKS routines to define the color indices. The default value of each 'Cn' is -1, indicating no change in color index from one part of the map to another.
'C1' I Color index for perimeter. See 'Cn', above.
'C2' I Color index for grid. See 'Cn', above.
'C3' I Color index for labels. See 'Cn', above.
'C4' I Color index for limb lines. See 'Cn', above.
'C5' I Color index for continent outlines. See 'Cn', above.
'C6' I Color index for state outlines. See 'Cn', above.
'C7' I Color index for outlines of countries of the world. See 'Cn', above.
'DA' I Dashed-line pattern for the grids. A 16-bit quantity. The default is 21845 (octal 52525 or binary 0101010101010101).
'DD' I,R Distance between dots along a dotted line drawn by MAPIT. The default value is 12 (out of 4096; see 'RE', below).
'DL' I,L If true (non-zero), user calls to MAPIT draw dotted lines. The default is false (zero); lines drawn by MAPIT are solid or dashed, depending on the current state of the DASHCHAR package. 'DL' may be reset by a user version of MAPUSR or MPCHLN to change the way in which the perimeter, the grid, the limb lines, and the outlines are drawn.
'DO' I,L If true (non-zero), outlines are dotted. The default is false (zero); outlines are solid.
'EL' I,L If true (non-zero), requests an elliptical perimeter: only that part of the map which falls inside an ellipse inscribed within the normal rectangular perimeter is drawn. This is particularly appropriate for use with azimuthal projections and angular limits specifying a square, in which case the ellipse becomes a circle, but it will work for any map. The default value is false (zero).
'GD' R The distance between points used to draw the grid, in degrees. The default value is 1.; user values must fall between .001 and 10.
'GP' I,R Specifies the way in which the grid, if drawn, is to be modified near the poles on projections which map the poles into single points; 'GP' is given a value of the form "1000*GLAT+GLON", where GLAT is an integer between 0 and 90 and GLON is a positive real between 0 and 360.
If GLAT is zero, all the latitude lines of the grid are drawn; if GLAT is non-zero, latitude lines at latitudes from GLAT to 90, inclusive (South or North) are omitted.
If GLON is zero, no longitude lines are drawn near the poles; if GLON is non-zero, only longitude lines of the grid at multiples of GLON are drawn near the poles.
Examples: "'GP'=0" says "draw all the latitude lines of the grid; omit longitude lines of the grid near the poles." "'GP'=1" says "draw entire grid." "'GP'=75045" says "suppress latitude lines of the grid above 75N and below 75S; near the poles, draw the longitude lines of the grid only at multiples of 45 degrees." The default is "'GP'=90", which says "draw all latitude lines of the grid; near the poles, omit longitude lines of the grid except those at multiples of 90 degrees".
'GR' I,R The desired grid spacing, in degrees. (Note that, when 'GT' and/or 'GN' have values greater than zero, they are used in place of 'GR'.) Giving 'GR' a value less than or equal to zero suppresses the grid. The default value of 'GR' is 10 degrees.
'GT' and 'GN' I,R The desired spacings of latitude and longitude grid lines, respectively (in degrees); if either is less than or equal to zero, the value of 'GR' is used instead.
'G1' I The group identifier to be used by MAPBLA or MPLNAM when putting into the area map the group of edges that define the division of the plotter frame into the projected images of geographic entities.
'G2' I The group identifier to be used by MAPBLA or MPLNAM when putting into the area map the group of edges that define the division of the plotter frame into vertical strips.
'IN' I,L For retrieval only. Initialization flag. If true (non-zero), it says that EZMAP is in need of initialization (by a CALL MAPINT). The default value is true (non-zero).
'LA' I,L If true (non-zero), label the meridians and the poles. The default is true (non-zero).
'LS' I Controls label size. A character width, to be used in a call to PWRIT. The default value is 1, which gives a character width of 12 plotter units.
'MV' I,R Minimum vector length for MAPIT. A point closer to the previous point than this is omitted. The default value is 4 (out of 4096; see 'RE', below).
'OU' C Says which set of outline data MAPLOT, MAPBLA, and MAPBLM are to use. The possible values are 'NO' (no outlines), 'CO' (continental outlines), 'US', (U.S. state outlines), 'PS' (continental outlines plus international outlines plus U.S outlines), and 'PO' (continental outlines plus international outlines). The default is 'CO'.
'PE' I,L If true (non-zero), draw the perimeter (a rectangle or an ellipse, depending on the value of 'EL'). The default is true (non-zero).
'PN' I,R For retrieval only. The value of PLON from the last call to MAPROJ. The default value is zero.
'PR' C For retrieval only. The value of the projection specifier JPRJ from the last call to MAPROJ. The default value is 'CE'.
'PT' I,R For retrieval only. The value of PLAT from the last call to MAPROJ. The default value is zero.
'Pn' I,R For retrieval only. "n" is an integer from 1 to 8, inclusive. Retrieves values from the call to MAPSET. 'P1' through 'P4' specify PLM1(1), PLM2(1), PLM3(1), and PLM4(1), while 'P5' through 'P8' specify PLM1(2), PLM2(2), PLM3(2), and PLM4(2). Default values are all zero.
'RE' I,R The width of the target plotter, in plotter units. The default value is 4096.
'RO' I,R For retrieval only. The value of ROTA from the last call to MAPROJ. The default value is zero.
'SA' I,R If 'SA' is greater than 1., a satellite-view projection replaces the orthographic. The value is the distance of the satellite from the center of the earth, in multiples of the earth's radius. The default value is zero. See also 'S1' and 'S2', below.
'S1' and 'S2' I,R Used only when 'SA' is greater than 1. Both are angles, in degrees. 'S1' measures the angle between the line to the center of the earth and the line of sight (to which the projection plane is perpendicular). If 'S1' is zero, the projection shows the earth as seen by a satellite looking straight down; call this the "basic view". If 'S1' is non-zero, 'S2' measures the angle from the positive u axis of the basic view to the line OP, where O is the origin of the basic view and P is the projection of the desired line of sight on the basic view. 'S2' is positive if measured counter-clockwise.
'SR' R A search radius, in degrees, used by MAPINT in finding the latitude/longitude range of a map. The default value is 1.; user values must lie between .001 and 10. Should not be changed except by advice of a consultant.
'VS' I The vertical-stripping parameter, which determines whether MAPBLA and MPLNAM put into the area map edge group 'G2', defining a set of vertical strips. A negative or zero value of 'VS' prevents MAPBLA and MPLNAM from doing this. A value greater than zero requests that it be done and specifies the number of vertical strips to be created. The default value of 'VS' is 1.
'XL', 'XR', 'YB', and 'YT' R For retrieval only. The values of the arguments XLOW, XROW, YBOW, and YTOW from the last call to MAPPOS. Defaults are .05, .95, .05, and .95, respectively.

Name	Type	Description
'AR'	C	For retrieval only. The value of the map limits specifier JLTS from the last call to MAPSET. The default value is 'MA'.
'Cn'	I	"n" is an integer between 1 and 7. Each 'Cn', if zero or greater, specifies the color index of some part of the map. The user must do the calls to GKS routines to define the color indices. The default value of each 'Cn' is -1, indicating no change in color index from one part of the map to another.
'C1'	I	Color index for perimeter. See 'Cn', above.
'C2'	I	Color index for grid. See 'Cn', above.
'C3'	I	Color index for labels. See 'Cn', above.
'C4'	I	Color index for limb lines. See 'Cn', above.
'C5'	I	Color index for continent outlines. See 'Cn', above.
'C6'	I	Color index for state outlines. See 'Cn', above.
'C7'	I	Color index for outlines of countries of the world. See 'Cn', above.
'DA'	I	Dashed-line pattern for the grids. A 16-bit quantity. The default is 21845 (octal 52525 or binary 0101010101010101).
'DD'	I,R	Distance between dots along a dotted line drawn by MAPIT. The default value is 12 (out of 4096; see 'RE', below).
'DL'	I,L	If true (non-zero), user calls to MAPIT draw dotted lines. The default is false (zero); lines drawn by MAPIT are solid or dashed, depending on the current state of the DASHCHAR package. 'DL' may be reset by a user version of MAPUSR or MPCHLN to change the way in which the perimeter, the grid, the limb lines, and the outlines are drawn.
'DO'	I,L	If true (non-zero), outlines are dotted. The default is false (zero); outlines are solid.
'EL'	I,L	If true (non-zero), requests an elliptical perimeter: only that part of the map which falls inside an ellipse inscribed within the normal rectangular perimeter is drawn. This is particularly appropriate for use with azimuthal projections and angular limits specifying a square, in which case the ellipse becomes a circle, but it will work for any map. The default value is false (zero).
'GD'	R	The distance between points used to draw the grid, in degrees. The default value is 1.; user values must fall between .001 and 10.
'GP'	I,R	Specifies the way in which the grid, if drawn, is to be modified near the poles on projections which map the poles into single points; 'GP' is given a value of the form "1000*GLAT+GLON", where GLAT is an integer between 0 and 90 and GLON is a positive real between 0 and 360. If GLAT is zero, all the latitude lines of the grid are drawn; if GLAT is non-zero, latitude lines at latitudes from GLAT to 90, inclusive (South or North) are omitted. If GLON is zero, no longitude lines are drawn near the poles; if GLON is non-zero, only longitude lines of the grid at multiples of GLON are drawn near the poles. Examples: "'GP'=0" says "draw all the latitude lines of the grid; omit longitude lines of the grid near the poles." "'GP'=1" says "draw entire grid." "'GP'=75045" says "suppress latitude lines of the grid above 75N and below 75S; near the poles, draw the longitude lines of the grid only at multiples of 45 degrees." The default is "'GP'=90", which says "draw all latitude lines of the grid; near the poles, omit longitude lines of the grid except those at multiples of 90 degrees".
'GR'	I,R	The desired grid spacing, in degrees. (Note that, when 'GT' and/or 'GN' have values greater than zero, they are used in place of 'GR'.) Giving 'GR' a value less than or equal to zero suppresses the grid. The default value of 'GR' is 10 degrees.
'GT' and 'GN'	I,R	The desired spacings of latitude and longitude grid lines, respectively (in degrees); if either is less than or equal to zero, the value of 'GR' is used instead.
'G1'	I	The group identifier to be used by MAPBLA or MPLNAM when putting into the area map the group of edges that define the division of the plotter frame into the projected images of geographic entities.
'G2'	I	The group identifier to be used by MAPBLA or MPLNAM when putting into the area map the group of edges that define the division of the plotter frame into vertical strips.
'IN'	I,L	For retrieval only. Initialization flag. If true (non-zero), it says that EZMAP is in need of initialization (by a CALL MAPINT). The default value is true (non-zero).
'LA'	I,L	If true (non-zero), label the meridians and the poles. The default is true (non-zero).
'LS'	I	Controls label size. A character width, to be used in a call to PWRIT. The default value is 1, which gives a character width of 12 plotter units.
'MV'	I,R	Minimum vector length for MAPIT. A point closer to the previous point than this is omitted. The default value is 4 (out of 4096; see 'RE', below).
'OU'	C	Says which set of outline data MAPLOT, MAPBLA, and MAPBLM are to use. The possible values are 'NO' (no outlines), 'CO' (continental outlines), 'US', (U.S. state outlines), 'PS' (continental outlines plus international outlines plus U.S outlines), and 'PO' (continental outlines plus international outlines). The default is 'CO'.
'PE'	I,L	If true (non-zero), draw the perimeter (a rectangle or an ellipse, depending on the value of 'EL'). The default is true (non-zero).
'PN'	I,R	For retrieval only. The value of PLON from the last call to MAPROJ. The default value is zero.
'PR'	C	For retrieval only. The value of the projection specifier JPRJ from the last call to MAPROJ. The default value is 'CE'.
'PT'	I,R	For retrieval only. The value of PLAT from the last call to MAPROJ. The default value is zero.
'Pn'	I,R	For retrieval only. "n" is an integer from 1 to 8, inclusive. Retrieves values from the call to MAPSET. 'P1' through 'P4' specify PLM1(1), PLM2(1), PLM3(1), and PLM4(1), while 'P5' through 'P8' specify PLM1(2), PLM2(2), PLM3(2), and PLM4(2). Default values are all zero.
'RE'	I,R	The width of the target plotter, in plotter units. The default value is 4096.
'RO'	I,R	For retrieval only. The value of ROTA from the last call to MAPROJ. The default value is zero.
'SA'	I,R	If 'SA' is greater than 1., a satellite-view projection replaces the orthographic. The value is the distance of the satellite from the center of the earth, in multiples of the earth's radius. The default value is zero. See also 'S1' and 'S2', below.
'S1' and 'S2'	I,R	Used only when 'SA' is greater than 1. Both are angles, in degrees. 'S1' measures the angle between the line to the center of the earth and the line of sight (to which the projection plane is perpendicular). If 'S1' is zero, the projection shows the earth as seen by a satellite looking straight down; call this the "basic view". If 'S1' is non-zero, 'S2' measures the angle from the positive u axis of the basic view to the line OP, where O is the origin of the basic view and P is the projection of the desired line of sight on the basic view. 'S2' is positive if measured counter-clockwise.
'SR'	R	A search radius, in degrees, used by MAPINT in finding the latitude/longitude range of a map. The default value is 1.; user values must lie between .001 and 10. Should not be changed except by advice of a consultant.
'VS'	I	The vertical-stripping parameter, which determines whether MAPBLA and MPLNAM put into the area map edge group 'G2', defining a set of vertical strips. A negative or zero value of 'VS' prevents MAPBLA and MPLNAM from doing this. A value greater than zero requests that it be done and specifies the number of vertical strips to be created. The default value of 'VS' is 1.
'XL', 'XR', 'YB', and 'YT'	R	For retrieval only. The values of the arguments XLOW, XROW, YBOW, and YTOW from the last call to MAPPOS. Defaults are .05, .95, .05, and .95, respectively.

ERROR HANDLING

When an EZMAP routine detects an error condition, it calls the routine SETER, which is the principal routine in the error-handling package for NCAR Graphics. (There is a programmer document describing SETER and associated routines; see that document for complete information about error-handling in NCAR Graphics.)

By default, SETER prints a line and STOPs. The line printed will look something like this:

  ERROR    3 IN MAPTRN - ATTEMPT TO USE NON-EXISTENT PROJECTION

The error number ("3", in the example) may be of use to a consultant (to determine exactly where the error occurred), but is not otherwise meaningful. The actual error message consists of the name of the routine in which the error occurred ("MAPTRN", in the example), a blank, a minus sign, another blank, and, lastly, a short description of the error.

All errors are "recoverable" in the sense that, if the user program puts SETER into "recovery mode", control will be returned to the caller of the EZMAP routine in which the error occurred. In some cases, it is then possible to take remedial action to get around whatever problem has occurred; in any case, the error flag can be cleared and execution of the user's program can continue.

When SETER is in recovery mode (and, occasionally, even when it is not), error messages may have a somewhat more complicated form, like this:

  SUPCON/MAPTRN - ATTEMPT TO USE NON-EXISTENT PROJECTION

What this particular error message says is that SUPCON called MAPTRN, which detected an error condition and called SETER. Upon getting control back from MAPTRN, SUPCON detected the fact that MAPTRN had logged an error. It augmented the error message by prepending its own name, followed by a slash, and then passed control back to the user. Of course, there can be more than two such levels of routine calls indicated in the error message: in a few cases, seven or eight routine names may be listed, each separated from the next by a slash.

The various error conditions in EZMAP are described in the list below. Each bulleted item includes an error message and a thumb-nail description of the error. The items in the list are arranged in alphabetical order. If you get an error message with one or more prefixed subroutine names, as described above, omit them and look up the result in this list. Note that, since EZMAP routines sometimes call other routines, elsewhere in NCAR Graphics, that can detect error conditions and call SETER, the error message you get by calling an EZMAP routine may not be listed here, but in the programmer document for some other package.

MAPBLA - UNCLEARED PRIOR ERROR

: When MAPBLA was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPBLM - UNCLEARED PRIOR ERROR

: When MAPBLM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPCHI - ERROR EXIT FROM GQPLCI

: MAPCHI is an internal routine used to manage color, intensity, dash patterns, etc. The GKS routine GQPLCI, which is called to get the current value of the polyline color index, has returned a non-zero error code.

MAPCHI - ERROR EXIT FROM GQPMCI

: MAPCHI is an internal routine used to manage color, intensity, dash patterns, etc. The GKS routine GQPMCI, which is called to get the current value of the polymarker color index, has returned a non-zero error code.

MAPCHI - ERROR EXIT FROM GQTXCI

: MAPCHI is an internal routine used to manage color, intensity, dash patterns, etc. The GKS routine GQTXCI, which is called to get the current value of the text color index, has returned a non-zero error code.

MAPDRW - UNCLEARED PRIOR ERROR

: When MAPDRW was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPFST - UNCLEARED PRIOR ERROR

: When MAPFST was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGCI - UNCLEARED PRIOR ERROR

: When MAPGCI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGRD - UNCLEARED PRIOR ERROR

: When MAPGRD was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGRM - UNCLEARED PRIOR ERROR

: When MAPGRM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGTC - UNCLEARED PRIOR ERROR

: When MAPGTC was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGTC - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPGTC is not recognizable as the name of an internal parameter of EZMAP.

MAPGTI - UNCLEARED PRIOR ERROR

: When MAPGTI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGTI - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPGTI is not recognizable as the name of an internal parameter of EZMAP.

MAPGTL - UNCLEARED PRIOR ERROR

: When MAPGTL was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGTL - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPGTL is not recognizable as the name of an internal parameter of EZMAP.

MAPGTR - UNCLEARED PRIOR ERROR

: When MAPGTR was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPGTR - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPGTR is not recognizable as the name of an internal parameter of EZMAP.

MAPINT - ANGULAR LIMITS TOO GREAT

: In a preceding call to MAPSET, JLTS = 'AN' was used, and the accompanying values of PLM1, PLM2, PLM3, and/or PLM4 were too large for the selected projection type.

MAPINT - ATTEMPT TO USE NON-EXISTENT PROJECTION

: Somehow, an internal variable that says what projection type to use has been given an illegal value. Under normal conditions, that's pretty hard to do; it may be that core has been overstored.

MAPINT - MAP HAS ZERO AREA

: The current internal parameters specify a map with zero area.

MAPINT - MAP LIMITS INAPPROPRIATE

: This can happen when you select a Lambert conformal conic projection and then try to use angular limits, which is a no-no. It can also happen when you try to specify the map limits using a point that is not projectable under the current projection.

MAPINT - UNCLEARED PRIOR ERROR

: When MAPINT was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPIO - EOF ENCOUNTERED IN OUTLINE DATASET

: MAPIO is an internal routine that is used to read the geographic outline dataset. Something is wrong with the dataset.

MAPIO - ERROR ON READ OF OUTLINE DATASET

: MAPIO is an internal routine that is used to read the geographic outline dataset. Something is wrong with the dataset.

MAPIQ - UNCLEARED PRIOR ERROR

: When MAPIQ was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPIQA - UNCLEARED PRIOR ERROR

: When MAPIQA was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPIQM - UNCLEARED PRIOR ERROR

: When MAPIQM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPIT - UNCLEARED PRIOR ERROR

: When MAPIT was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPITA - UNCLEARED PRIOR ERROR

: When MAPITA was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPITM - UNCLEARED PRIOR ERROR

: When MAPITM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPLBL - UNCLEARED PRIOR ERROR

: When MAPLBL was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPLMB - UNCLEARED PRIOR ERROR

: When MAPLMB was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPLOT - UNCLEARED PRIOR ERROR

: When MAPLOT was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPPOS - ARGUMENTS ARE INCORRECT

: In a call to MAPPOS, either 1) one of the arguments is outside the range from 0. to 1., or 2) argument 1 is greater than or equal to argument 2, or 3) argument 3 is greater than or equal to argument 4.

MAPPOS - UNCLEARED PRIOR ERROR

: When MAPPOS was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPROJ - UNCLEARED PRIOR ERROR

: When MAPROJ was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPROJ - UNKNOWN PROJECTION NAME

: The first argument in a call to MAPROJ is not recognizable as the name of one of the projections provided by EZMAP.

MAPRS - UNCLEARED PRIOR ERROR

: When MAPRS was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPRST - EOF ON READ

: An EOF was encountered while attempting to read back parameter values written by MAPSAV. Remember that the user is responsible for all positioning of the file used.

MAPRST - ERROR ON READ

: A FORTRAN read error occurred while attempting to read back parameter values written by MAPSAV. Remember that the user is responsible for all positioning of the file used.

MAPRST - UNCLEARED PRIOR ERROR

: When MAPRST was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSAV - ERROR ON WRITE

: A FORTRAN write error occurred. This most likely means that the user-provided logical file number is incorrect.

MAPSAV - UNCLEARED PRIOR ERROR

: When MAPSAV was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSET - UNCLEARED PRIOR ERROR

: When MAPSET was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSET - UNKNOWN MAP AREA SPECIFIER

: The first argument in a call to MAPSET is not recognizable as the name of one of the map area specification methods provided by EZMAP.

MAPSTC - UNCLEARED PRIOR ERROR

: When MAPSTC was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSTC - UNKNOWN OUTLINE NAME

: The second argument in a call to MAPSTC is not recognizable as the name of one of the outline datasets provided by EZMAP.

MAPSTC - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPSTC is not recognizable as the name of an internal parameter of EZMAP.

MAPSTI - UNCLEARED PRIOR ERROR

: When MAPSTI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSTI - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPSTI is not recognizable as the name of an internal parameter of EZMAP.

MAPSTL - UNCLEARED PRIOR ERROR

: When MAPSTL was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSTL - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPSTL is not recognizable as the name of an internal parameter of EZMAP.

MAPSTR - UNCLEARED PRIOR ERROR

: When MAPSTR was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPSTR - UNKNOWN PARAMETER NAME

: The first argument in a call to MAPSTR is not recognizable as the name of an internal parameter of EZMAP.

MAPTRA - UNCLEARED PRIOR ERROR

: When MAPTRA was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPTRI - UNCLEARED PRIOR ERROR

: When MAPTRI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPTRN - ATTEMPT TO USE NON-EXISTENT PROJECTION

: Somehow, an internal variable that says what projection type to use has been given an illegal value. Under normal conditions, that's pretty hard to do; it may be that core has been overstored.

MAPTRN - UNCLEARED PRIOR ERROR

: When MAPTRN was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MAPVEC - UNCLEARED PRIOR ERROR

: When MAPVEC was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPGETC - UNCLEARED PRIOR ERROR

: When MPGETC was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPGETI - UNCLEARED PRIOR ERROR

: When MPGETI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPGETL - UNCLEARED PRIOR ERROR

: When MPGETL was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPGETR - UNCLEARED PRIOR ERROR

: When MPGETR was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPLNAM - Can't form name of ".names" file

: Either the name of the NCAR Graphics database directory could not be retrieved or it was too long or it was returned in an incorrect form.

MPLNAM - Can't open the ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNAM - Can't open the ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNAM - Read bad index from ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened and information was read from it, but the information appears to be flawed.

MPLNAM - Read error on ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNAM - Read error on ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNAM - UNCLEARED PRIOR ERROR

: When MPLNAM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPLNDM - Can't form name of ".names" file

: Either the name of the NCAR Graphics database directory could not be retrieved or it was too long or it was returned in an incorrect form.

MPLNDM - Can't open the ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNDM - Can't open the ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNDM - Read bad index from ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened and information was read from it, but the information appears to be flawed.

MPLNDM - Read error on ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNDM - Read error on ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNDM - UNCLEARED PRIOR ERROR

: When MPLNDM was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPLNDR - Can't form name of ".names" file

: Either the name of the NCAR Graphics database directory could not be retrieved or it was too long or it was returned in an incorrect form.

MPLNDR - Can't open the ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNDR - Can't open the ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNDR - Read bad index from ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened and information was read from it, but the information appears to be flawed.

MPLNDR - Read error on ".lines" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNDR - Read error on ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNDR - UNCLEARED PRIOR ERROR

: When MPLNDR was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPLNRI - Can't form name of ".names" file

: Either the name of the NCAR Graphics database directory could not be retrieved or it was too long or it was returned in an incorrect form.

MPLNRI - Can't open the ".names" file

: The file named "database_name.lines" (where "database_name" is the value of the argument FLNM) could not be opened, either in the local directory or in the NCAR Graphics database directory. Either it doesn't exist or it has the wrong permissions.

MPLNRI - Read bad index from ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened and information was read from it, but the information appears to be flawed.

MPLNRI - Read error on ".names" file

: The file named "database_name.names" (where "database_name" is the value of the argument FLNM) was found and opened, but attempting to read it returned an error flag.

MPLNRI - UNCLEARED PRIOR ERROR

: When MPLNRI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPSETC - UNCLEARED PRIOR ERROR

: When MPSETC was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPSETI - UNCLEARED PRIOR ERROR

: When MPSETI was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPSETL - UNCLEARED PRIOR ERROR

: When MPSETL was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

MPSETR - UNCLEARED PRIOR ERROR

: When MPSETR was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

SUPCON - UNCLEARED PRIOR ERROR

: When SUPCON was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

SUPMAP - UNCLEARED PRIOR ERROR

: When SUPMAP was called, there was an unrecovered outstanding error. The routine does not continue: it forces the error message for the outstanding error to be printed and then substitutes this one for it.

EXAMPLES

On a Unix system on which NCAR Graphics has been installed, the command "ncargex" may be used to acquire the code for and run the following examples illustrating various capabilities of EZMAP:

Example "mpex01" shows the United States on a Lambert conformal conic.
Example "mpex02" shows Africa on a stereographic projection, with an elliptical perimeter.
Example "mpex03" shows simplified continental outlines on a Mercator projection.It uses a version of MAPEOD which scrubs all but the principal land masses. The left and right area identifiers are used to determine which segments to keep and which to scrub. Segment-number information, obtained by running the program shown in example 9, could have been used instead.
Example "mpex04" shows the world in three parts, using stereographic projections for the poles and a Mercator projection for the equatorial belt.
Example "mpex05" shows maximal-area plots for all types of EZMAP projections.
Example "mpex06" shows the effect of the rotation angle ROTA on a satellite-view projection.
Example "mpex07" presents a scheme for labelling the meridians on certain types of maps. It is difficult to write an algorithm for doing this in general.
Example "mpex08" demonstrates how the routine MAPUSR is used.
Example "mpex09" shows the numbering of segments in the outline dataset 'CO' and presents a program which may be used to obtain such plots for the other outline datasets. This example is somewhat out of date, since the segment numbers are only of use in a user version of the routine named MAPEOD and it is probably better now to use the left and right area identifiers, rather than the segment numbers, in deciding which outline segments to keep and which to omit.The technique used to break the maps into rectangular pieces and present each piece individually may be useful in its own right.
(frame 1)
Example "mpex10" shows how to use the routine MAPTRI and the cell-array capability of GKS to obtain what is essentially a contour map of a data field defined on the surface of the globe.
Example "mpex11" shows three different portions of the earth as represented by the database "Earth..1", which was added to EZMAP in April, 1998. On each frame, there are three concentric circles. Within the innermost circle, the dataset is shown at level 4 (which includes states); within the surrounding ring, the dataset is shown at level 3 (which includes countries, but not states); within the ring around that, the dataset is shown at level 2 (including continents and pseudo-continents, but no countries or states); outside the largest ring, the dataset is shown at level 1 (including land-water boundaries, but nothing else.)
(frame 1)
Example "mpex12" does not draw a plot. It only produces print output. It illustrates how to use EZMAPB routines that retrieve information about the areas defined by a database.
Example "mpexfi" (the "final" example for EZMAP itself) shows how to draw lines, defined by points for which one has the latitudes and longitudes, on a map produced by EZMAP.
Example "tezmap" produces a number of frames; it is intended to demonstrate minimal functioning of EZMAP.
(frame 1)
Example "tezmpa" shows a solid-colored map of a portion of Northern Europe, with lines of latitude and longitude over ocean only. The outline data used are from the outline dataset 'PO'. Compare the plot with that produced by "tezmpb".
Example "tezmpb" shows a solid-colored map of a portion of Northern Europe, with lines of latitude and longitude over ocean only. The outline data used are from the map database "Earth..1". Compare the plot with that produced by "tezmpa".
Example "eezmpa" shows a solid-colored map of the world on a Mercator projection, with lines of latitude and longitude over ocean only.

Many of the above example programs use a subroutine named BNDARY to draw a boundary line indicating where the edge of the plotter frame is. This subroutine is not a part of EZMAP or of the NCAR plot package. When you run one of these, the code for the subroutine BNDARY will be put in a file named "mpexcc.f".

The following CONPACK example illustrates the use of the satellite-view projection and various routines from the package EZMAPA:

Example "cpex10" shows a view of the western United States as seen from a satellite above Washington, D.C. Within seven degrees of Boulder, Colorado, color-filled contour bands are shown. The EZMAPA routine MAPBLM is used with an appropriate area map, allowing state boundaries to be in black over the contoured area and in white elsewhere. The EZMAP routine MAPGRM is used with an appropriate area map, allowing 1-degree grid lines to be drawn outside the contoured area, but not inside it. Mapping capabilities of PLOTCHAR are used to create state labels that appear to be written on the surface of the globe and projected along with it.

AREA IDENTIFIERS

Prior to 1998, there were four EZMAP outline datasets, indexed as follows:

Index Name Contents
1 'CO' Continental outlines only.
2 'US' U.S. state outlines only.
3 'PS' Continental, U.S. state, and international outlines.
4 'PO' Continental and international outlines.

Index	Name	Contents
1	'CO'	Continental outlines only.
2	'US'	U.S. state outlines only.
3	'PS'	Continental, U.S. state, and international outlines.
4	'PO'	Continental and international outlines.

These datasets were accessed by calling one or more of the routines MAPBLA, MAPBLM, and MAPLOT. Associated with each outline segment in the old datasets were two integers identifying, respectively, the areas to the left and right of the outline segment. These "area identifiers" could be used, in a user version of the subroutine MAPEOD, to cull unwanted segments from a map; they also allowed the user to produce solid-color maps. This table shows the association between the old area identifiers and the names of the areas they identified.

In 1998, a new map database was created, called "Earth..1". It has a different structure and is accessed using the EZMAPB routines MPLNAM, MPLNDM, MPLNDR, MPLNRI. The areas defined by the new database also have numeric area identifiers, but specific numeric values should not be embedded in user programs; instead, area names should be used. The names of the areas defined by the new database are shown in this table.

MISCELLANY

History

About 1963, R. L. Parker of UCSD wrote the original code, named SUPERMAP, using outline data generated by Hershey. This was adapted for use at NCAR by Lee, in 1968. Revisions occurred in January, 1969, and in May, 1971. The code was put in standard NSSL form in October, 1973. Further revisions occurred in July, 1974, in August, 1976, and in July, 1978. In late 1984 and early 1985, the code was heavily revised to achieve compatibility with FORTRAN-77 and GKS, to remove errors, to augment the outline datasets, and to add enough controls to make user modification of the code unnecessary. In 1987, certain changes were made as part of preparing to introduce the solid-color routine named MAPBLA: A routine named MAPEOS was removed and a routine named MAPEOD was implemented in its place; intensity parameters 'I1', 'I2', etc., were removed and the color-index parameters 'C1', 'C2', etc. were implemented instead. Later in 1987, the routines of EZMAPA were made available. In 1992, an inverse-transformation routine was added to the package. In 1998, the routines of EZMAPB and the new database "Earth..1" were added.

Cicely Ridley, Jay Chalmers, and Dave Kennison (the current curator) have all had a hand in the creation of EZMAP.

Resolution of Datasets

Data points in the continental-outline portions of the 'CO', 'PO', and 'PS' outline datasets are about one degree apart and the coordinates are accurate to .01 degree. Data points in the U.S. state outlines in the 'PS' and 'US' outline datasets and in the new database "Earth..1" are about .05 degrees apart and the coordinates are accurate to .001 degree. Both the spacing and the accuracy of the international boundaries in all the old and new datasets falls somewhere between these two extremes.

References

Hershey, A.V., "The Plotting of Maps on a CRT Printer." NWL Report no. 1844, 1963.

Lee, Tso-Hwa, "Students' Summary Reports, Work-Study Program in Scientific Computing". NCAR, 1968.

Parker, R.L., "2UCSD SUPERMAP: World Plotting Package".

Steers, J.A., "An Introduction to the Study of Map Projections". University of London Press, 1962.

Ezmap, A Map-Drawing Package

Table of Contents

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments

Usage

Arguments