CVTDISTANC      CONVERT DISTANCE                       TAAMETB

The Convert  Distance  command allows  a conversion  from  one type  of
value  such as meters  to a different  type such  as miles.   The input
value  may be up to 9 digits with 2  decimals.  The output value may be
any combination of 15/0,  15/2, or 15/5.   Conversions can be made  for
millimeters,  centimeters,  meters,  kilometers, inches,  feet,  yards,
miles, cable lengths, fathoms, and furlongs.

Some rounding occurs.  All results are half adjusted

A typical series of commands would be:

DCL        &MILES *DEC LEN(15 2)
.
CVTDISTANC FROMTYPE(*METERS) FROMVALUE(1700)
TOTYPE(*MILES) TOVALUEB(&MILES)

The &MILES return value would contain '1.06'.

It  is possible to get  a value and  a sub value.   For example, if you
want  to convert  meters  to  both  feet  and  inches,  you  could  use
CVTDISTANC with TOVALUEC and  use the whole number as  feet.  Then take
the 5 digit decimal value and convert it to inches.

Conversion values to centimeters
--------------------------------

The input  value is converted to centimeters  and then converted to the
return value based on:

1 Millimeter = .10 centimeters
1 Meter      = 100 centimeters
1 Kilometer  = 100,000 centimeters
1 Inch       = 2.54 centimeters
1 Foot       = 30.48 centimeters
1 Yard       = 91.44 centimeters
1 Mile       = 160,934.30 centimeters
1 Cable      = 21,945.6 centimeters
1 Fathom     = 182.88 centimeters
1 Furlong    = 20,116.8 centimeters

CVTDISTANC escape messages you can monitor for
----------------------------------------------

TAA9891    The result value is too large for the return variable

Escape messages from based on functions will be re-sent.

CVTDISTANC Command parameters                         *CMD
-----------------------------

FROMTYPE      The From Type of  value to be converted.   It must  be
one    of    *MILLIMETERS,    *CENTIMETERS,    METERS,
*KILOMETERS,  *INCHES, *FEET, *YARDS,  *MILES, *CABLES
(cable lengths), *FATHOMS, or *FURLONGS.

FROMVALUE     The  value to be converted.  It  may be up to 9 digits
with 2 decimals.

TOTYPE        The type  to  be converted  to.   It  must  be one  of
*MILLIMETERS,   *CENTIMETERS,   METERS,   *KILOMETERS,
*INCHES,   *FEET,   *YARDS,  *MILES,   *CABLES  (cable
lengths), *FATHOMS, or *FURLONGS.

TOVALUEA      The return  value with  the converted  answer  without
decimals.   The value  is half  adjusted.  A  variable
must be named that is declared as *DEC LEN(15 0).

TOVALUEB      The  return  value with  the converted  answer  with 2
decimals.  The  value is  half adjusted.   A  variable
must be named that is declared as *DEC LEN(15 2).

TOVALUEC      The  return value  with the  converted  answer with  5
decimals.   The value  is half  adjusted.   A variable
must be named that is declared as *DEC LEN(15 5).

Restrictions
------------

Because  CVTDISTANC returns  a variable, the  command may  only be used
in a CL type program.

Prerequisites
-------------

The following TAA Tools must be on your system:

SNDESCINF       Send escape information
SNDESCMSG       Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

Object        Type    Attribute      Src member    Src file
------        ----    ---------      ----------    ----------

CVTDISTANC    *CMD                   TAAMETB       QATTCMD
TAAMETBC      *PGM       CLP         TAAMETBC      QATTCL
TAAMETBR      *PGM       RPG         TAAMETBR      QATTCL

Added to TAA Productivity tools July 15, 2013