Example 3. Creating a Cartesian-to-Polar transformation.

The following arrangement might be used to create a transformation called MYTRAN from the FOR and INV arrays defined earlier:

*  Declare variables.
      INCLUDE 'SAE_PAR'
      INCLUDE 'TRN_PAR'                                    [1]
      CHARACTER PREC * ( TRN__SZPRC ), COMM * 80
      CHARACTER * ( DAT__SZLOC ) ELOC, LOCTR

*  Get a locator ELOC to an existing HDS structure.
      <a call to DAT_ASSOC or DAT_FIND, for instance>

*  Specify the arithmetic precision and make a comment.
      PREC = '_REAL:'                                      [2]
      COMM = '2-d Cartesian (x,y) --> 2-d Polar (r,theta)  [3]

*  Create the transformation.
      CALL TRN_NEW( NVIN, NVOUT, FOR, INV, PREC, COMM,     [4][5]
     :              ELOC, 'MYTRAN', LOCTR, STATUS )

Programming notes:

1. The symbolic constant TRN__SZPRC is defined in the include file TRN_PAR. It is used to declare the length of the character variable PREC which will contain a precision specification.

2. PREC specifies the type of arithmetic to be used when the transformation functions are evaluated and has been assigned the value `_REAL:', which is recommended for general use. This indicates that single precision (real) arithmetic should normally be used but that the precision may be increased if double precision data are being processed. This is discussed further in Section .

3. The `-->' (or `<--') character sequence may be used in comment strings to indicate the direction of the forward mapping. If the transformation is subsequently inverted (Section ), then the `-->' and `<--' symbols will be interchanged so that the comment remains valid. Comments may be of any length.

4. TRN_NEW will check the transformation functions for correct syntax and consistent use of variable names before the transformation is created. However, no check is performed to determine whether the forward and inverse transformation functions actually define a pair of complementary mappings. It is the caller's responsibility to ensure that this is so.

5. On successful exit from TRN_NEW, the LOCTR argument returns an HDS locator associated with the newly created transformation.