CLPTEN ( point, ents, nopts, iopts, optdta, mdist, elist, epoint, csparm, 
==========================================================================
         props, nprops, ifail )
         ======================

  Finds the closest point on an entity to a given point.

Receives:
  KI_vec_position           point          --- point
  KI_tag_list_entity       *ents           --- entities
 <KI_int_nitems>           *nopts          --- number of options
  KI_cod_clop               iopts[nopts]   --- options
  KI_tag_list_dbl           optdta[nopts]  --- option data

Returns:
 <KI_dbl_distance>         *mdist          --- minimum distance
  KI_tag_list_<entity>     *elist          --- entity list
  KI_vec_position           epoint         --- point on entity
 <KI_dbl>                   csparm[2]      --- curve or surface parameters
  KI_tag_list_int          *props          --- properties
 <KI_int_nitems>           *nprops         --- no. of properties
  KI_cod_error             *ifail          --- failure indicator

Specific errors:
  KI_missing_geom           Topology without geometry supplied
  KI_wrong_entity_in_list   Unsupported entity type supplied in list
  KI_wrong_entity           Unsupported entity type supplied
  KI_bad_option_data        bad option data supplied
  KI_closest_approach_failed failed to find closest approach

Description:

  Given an entity or list of entities ('ents'), CLPTEN will determine an
  entity point ('epoint') which is the minimum distance ('mdist') from the
  received 'point'. Only one 'epoint' will be returned, regardless of how many
  possible points achieve the minimum distance.

  The following entity types are supported:
      - Geometrical: point, curve, and surface.
      - Topological: vertex, edge, face, and body.

  Curves and surfaces must be legally attachable to edges and faces, and must
  be G1 continuous.

  The returned entity list ('elist') will contain two components:
       - The first list component will be the tag of the (received) entity
         upon which the solution was found to lie.
       - The second list component will indicate a sub-topology upon which the
         solution was found to lie. This sub-topology will be either a face,
         edge or vertex, belonging to a received entity. If the solution does
         not lie on sub-topology a 'NULTAG' will be returned.

  If either of the entities in the list has a tolerance associated with it, the
  solution on that entity will only be accurate and unique up to the tolerance
  of the entity.

  Solution Parametrisation:
  When appropriate a curve parameter or 2 surface parameters will be returned in
  the 'csparm' array. This array is of length 2, but for the curve parameter
  case the 2nd array entry should be ignored.
   What parametrisation is used is firstly dependent upon the geometry of
  the entity returned and secondly upon the geometry of the sub-topology (if
  identified). The table below indicates what parametrisation is used and when:

















     ----------------------------------------------------------------------
    |   Entity    |  Identified Sub-topology  |     Geometry used for      |
    |             |                           |  solution parametrisation  |
    |-------------|---------------------------|----------------------------|
    |             |                           |                            |
    |   point     |         none              |          none              |
    |   curve     |         none              |          curve             |
    |  surface    |         none              |         surface            |
    |             |                           |                            |
    |   vertex    |         none              |          none              |
    |             |                           |                            |
    |    edge     |         none              |     curve of the edge      |
    |    edge     |        vertex             |     curve of the edge      |
    |             |                           |                            |
    |    face     |         none              |    surface of the face     |
    |    face     |         edge              |    surface of the face     |
    |    face     |        vertex             |    surface of the face     |
    |             |                           |                            |
    |    body     |         face              |    surface of the face     |
    |    body     |         edge              |     curve of the edge      |
    |    body     |        vertex             |          none              |
    |             |                           |                            |
     ----------------------------------------------------------------------

   The curve and surface parameter values returned, will be the same as would
  be returned by the parametrisation functions ENPAPC, and ENPAPS.

  Options:
  Various options are available through the use of 'nopts' 'iopts' & 'optdta'.
  'nopts' specifies the number of options requested, 'iopts' is an array of
  option types, and 'optdta' is an array of lists of corresponding option data.
  Some options are only available for restricted cases.

  The following 3 options are available regardless of how many entities
  or what entity types are supplied:
      - An upper bound on the minimum distance to be computed may be supplied.
        If such a bound is supplied the minimum distance achieved will only be
        identified if it is less than the bound.
      - A lower bound on the minimum distance. For this option, if the closest
        approach between an 'entity' and 'point' is found to be less than this
        bound, no solution will be determined and a token will be returned to
        indicate that the minimum distance is less than this bound.
      - A tolerance on the accuracy of the minimum distance measurement. This
        will allow slacker computation of minimum distance, when the
        default accuracy is not required. The default accuracy will be the
        linear precision of the modeller (set up by SEMODP). If supplied the
        tolerance must not be less than the default value.

  If both lower and upper bounds are supplied it is illegal for the lower bound
  to be greater than the upper bound.


  The following additional options will be available but only for limited
  cases. These options must only be allowed to refer to a single entity,
  and not a list of entities nor a single component of an entity list.
        - For a single curve or edge, a curve parameter estimate may be
          supplied.
        - For a single surface or face, surface parameter estimates may be
          supplied.
        - For a single curve, surface, edge, or face, a position vector estimate
          may be supplied. Such an estimate is expected to be on or close to the
          entity.

  Both parameter and position vector estimates cannot be supplied for an entity.




  The table below details the tokens and data required for the options.


      ------------------------------------------------------------------------
     |            Option         |  Token   |    Option Data (real values)    |
     |---------------------------|--------- |---------------------------------|
     |                           |          |                                 |
     | 1. To supply an upper     |  CLOPUP  |  1 real: the upper bound        |
     |    distance bound         |          |                                 |
     |                           |          |                                 |
     | 2. To supply a lower      |  CLOPLW  |  1 real: the lower bound        |
     |    distance bound         |          |                                 |
     |                           |          |                                 |
     | 3. To supply a tolerance  |  CLOPTL  |  1 real: the tolerance          |
     |                           |          |                                 |
     | 4. To supply a pvec       |  CLOPPT  |  3 reals: vector estimate       |
     |    estimate               |          |                                 |
     |                           |          |                                 |
     | 5. To supply a parameter  |  CLOPP1  |  1 or 2 reals:                  |
     |    estimate               |          |  1 curve                        |
     |                           |          |  or 2 surface parameters        |
     |                           |          |                                 |
      ------------------------------------------------------------------------

  Properties:
  A list of tokens, 'props' is returned to indicate the following:
      - The solution as being a regional solution upon the entity (i.e it is
        possible to move along the entity from the solution point without the
        distance changing)                                          : RTCLRS
        The identification of such a regional solution is not guaranteed.
      - No solution being returned because the distance was found to be less
        than the lower bound                                        : RTCLLB
      - No solution being returned because no distance was found to be less than
        the upper bound                                             : RTCLUB
      - For a body only, the distance as being negative. The distance will be
        classified as negative if the 'point' lies inside the body  : RTCLND