%N pgscrn %F $MIR/src/pgscrn.f
%D Set color representation by name
%B
      SUBROUTINE PGSCRN(CI, NAME, IER)
      INTEGER CI
      CHARACTER*(*) NAME
      INTEGER IER

 Set color representation: i.e., define the color to be
 associated with a color index.  Ignored for devices which do not
 support variable color or intensity.  This is an alternative to
 routine PGSCR. The color representation is defined by name instead
 of (R,G,B) components.

 Color names are defined in an external file which is read the first
 time that PGSCRN is called. The name of the external file is
 found as follows:
 1. if environment variable (logical name) PGPLOT_RGB is defined,
    its value is used as the file name;
 2. otherwise, if environment variable PGPLOT_DIR is defined, a
    file "rgb.txt" in the directory named by this environment
    variable is used;
 3. otherwise, file "rgb.txt" in the current directory is used.
 If all of these fail to find a file, an error is reported and
 the routine does nothing.

 Each line of the file
 defines one color, with four blank- or tab-separated fields per
 line. The first three fields are the R, G, B components, which
 are integers in the range 0 (zero intensity) to 255 (maximum
 intensity). The fourth field is the color name. The color name
 may include embedded blanks. Example:

 255   0   0 red
 255 105 180 hot pink
 255 255 255 white
   0   0   0 black

 Arguments:
  CI     (input)  : the color index to be defined, in the range 0-max.
                    If the color index greater than the device
                    maximum is specified, the call is ignored. Color
                    index 0 applies to the background color.
  NAME   (input)  : the name of the color to be associated with
                    this color index. This name must be in the
                    external file. The names are not case-sensitive.
                    If the color is not listed in the file, the
                    color representation is not changed.
  IER    (output) : returns 0 if the routine was successful, 1
                    if an error occurred (either the external file
                    could not be read, or the requested color was
                    not defined in the file).
