Man Page convert_external.3m


     convert_external - convert external binary data formats


     cc [ flag ... ] file ...  -lsunmath -lm [ library ... ]

     #include <sunmath.h>

     enum convert_external_arch_t = {
          convert_external_sparc, convert_external_pc,
          convert_external_vax, convert_external_vaxg,
          convert_external_s370, convert_external_cray };

     enum convert_external_type_t = {
          convert_external_float };

     enum convert_external_rounding_t = {
          convert_external_common = -1,
          convert_external_biased = -2,
          convert_external_away = -3 };

     typedef struct {
          enum convert_external_arch_t arch ;     /* format architecture */
          enum convert_external_type_t type ;     /* format type */
          int size ;                    /* format size in 8-bit bytes */
          } convert_external_t ;

     fp_exception_field_type convert_external(const char  *src_p,
     convert_external_t       src_format,       char      *dst_p,
     convert_external_t dst_format, int rounding, int n);

     fp_exception_field_type convert_external_(const char *src_p,
     const  convert_external_t  *src_format_p, char *dst_p, const
     convert_external_t  *dst_format_p,  const  int  *rounding_p,
     const int *n_p);


     convert_external() is used in C programs to convert  between
     binary data on non-SPARC systems and SPARC binary data.  The
     data  may  be  signed  integers,   unsigned   integers,   or
     floating-point data.  convert_external_() is used in Fortran
     programs (CALL CONVERT_EXTERNAL(...))  for the same purpose,
     with all parameters call-by-reference.

     The convert_external_t type describes the supported formats;
     for each architecture, signed and unsigned integers of sizes
     1, 2, 4, 8, or 16 bytes, and floating-point types  of  sizes
     4,  8,  10,  12,  or  16 bytes in size are supported.  If an
     improper size is specified for the source or destination, no
     conversion  occurs  and  (1<<fp_division)  is  returned,  an
     exception that can't arise otherwise.

     Supported architectures and formats include

external_t endian- float*4 float*8 float*10 float*12 float*16

architecture ness format format format format format

sparc big IEEE IEEE none MC68881 IEEE

                         single    double               extended     quad

pc little IEEE IEEE i80x87 i80960KB IEEE

                         single    double    extended   extended     quad

vax little VAX F VAX D none none VAX H

vaxg little VAX F VAX G none none VAX H

s370 big S/370 S/370 none none S/370

                         single    double                          extended

cray big none Cray-1 none none Cray-1

                                   single                           double

     Note that MC68000 and SPARC formats are identical big-endian
     formats;  the  Intel  PC formats for 8086/8087, 80x86/7, and
     80486 are identical little-endian.  Table  entries  ``none''
     represent  improper  sizes;  no  conversion  occurs.  ``IEEE
     quad'' refers to the natural big- or little-endian extension
     of  IEEE  single  and  double  precision to a format with 15
     exponent bits, one implicit significand bit, and 112  expli-
     cit significand bits.


     excep = convert_external(src_p, src_format, dst_p, dst_format, rounding, n);

               The function value is an accumulation of  all  the
               exceptions  encountered during the conversion.  If
               detecting individual exceptions  is  important,  n
               should  be  1  so  that only one data item is con-
               verted at a time.

               A pointer to the data to be converted stored as  a
               contiguous  array.  The pointer is declared char *
               to emphasize that there are no alignment  require-
               ments, although data being converted to SPARC for-
               mat for subsequent processing by the same  program
               should be appropriately aligned.

               A pointer to the converted data stored as  a  con-
               tiguous array.

               Description of the format of the source data.

               Description of the format of the destination data.

               The rounding mode  to  apply  to  the  destination

          n    Number of data items to be converted.

     Rounding choices; the first is intended to  be  satisfactory
     for almost all applications:

     (int) convert_external_common
          integer and unsigned destination formats  round  toward
          zero (2.9 rounds to 2, -2.9 rounds to -2),
          IEEE  floating-point  destinations  round  to   nearest
          VAX  floating-point  destinations  round   to   nearest
          IBM 370  and  Cray  floating-point  destinations  round
          toward zero.

     (int) convert_external_biased
          to round to nearest biased (for  integer  destinations,
          1.5 rounds to 2, 2.5 rounds to 3).

     (int) convert_external_away
          to round away from zero (for integer destinations,  2.1
          rounds to 3, -2.1 rounds to -3).

     (int) fp_nearest, fp_tozero, fp_positive, fp_negative
          to obtain rounding in one of  the  modes  specified  in
          IEEE 754.

     After the conversion, if (excep & (1 << fp_invalid))  !=  0,
     then  one or more invalid exceptions occurred; similarly for
     the other exceptions, which are defined this way:

          An input argument was an IEEE signaling NaN  or  a  VAX
          reserved  operand, or an input argument was an infinity
          and the destination was an integer or unsigned type, or
          a floating-point type with no infinity representation.

          An input argument was finite and large but could not be
          represented  in the destination format with only normal
          rounding error; if the destination format is integer or
          unsigned then fp_overflow represents integer overflow.

          An input argument was finite and small and could not be
          represented  in the destination format with only normal
          rounding error.  This can  only  arise  with  floating-
          point destinations.

          An  input  argument  was  finite  but  could   not   be
          represented exactly in the destination format.

          The source or destination formats aren't supported.  No
          conversions are done.

     Note that converting external data to SPARC format, process-
     ing on a SPARC, then converting back to external format will
     almost never yield the same results as processing  the  data
     entirely on the external system, even if the conversions and
     processing yield no exceptions on the SPARC.


  Generating data on an external system
     The following code demonstrates typical  Fortran  generation
     of binary floating-point data on an external system:
                  REAL A(100)
                  WRITE(9) A

  Converting external data to SPARC internal form in C
     Suppose the previous binary data file was created on a  tape
     on  a  Cray  and read on a SPARC system.  To convert to IEEE
     double-precision floating-point  format,  but  using  biased
          #include <sunmath.h>

          char datasrc[800];
          double datadest[100];
          fp_exception_field_type excep;
          int rounding;
          int i;
          convert_external_t src, dest;

          /*    read the Cray data into the array datasrc somehow, then ...  */

          src.arch = convert_external_cray;
          src.type = convert_external_float;
          src.size = 8;
          dest.arch = convert_external_sparc;
          dest.type = convert_external_float;
          dest.size = 8;
          rounding = convert_external_biased;

          excep = convert_external((char *) datasrc, src, (char *) datadest, dest, rounding, 100);

           * usually you aren't interested in inexact exceptions
           * and you'd do this
          excep &= ~(1 << fp_inexact);

           * other exceptions are possible in this example - after the fact,
           * you can find out where they happened this way
          if (excep != 0) for (i = 0 ; i < 100 ; i++) {
              excep = convert_external((char *)&datasrc[8 * i], src, (char *)&datadest[i], dest, rounding, 1);
              if (excep != 0) {
                  /* do something specific about datadest[i] */

  Converting SPARC internal data to external form in Fortran
     Suppose data created in a SPARC program is to be  read  into
     an IBM PC.  To convert,
          #include <floatingpoint.h>

                  REAL*4 datasrc(100)
                  REAL*4 datadest(100)
                  INTEGER excep, convert_external, round
                  INTEGER src(4), dest(4)

          c        create datasrc array somehow, then ...

                  src(1) = convert_external_sparc
                  src(2) = convert_external_float
                  src(3) = 4
                  dest(1) = convert_external_pc
                  dest(2) = convert_external_float
                  dest(3) = 4
                  round = convert_external_common

                  excep = convert_external(datasrc, src, datadest, dest, round, 100)
          c        The only exception that can arise is fp_invalid,
          c        by converting a signaling NaN.

          c        Now write the data out in a file that an IBM PC can read


     dd(1M), for reading tapes from foreign systems; xdr(3N), for
     formatting   arbitrary   data   structures   in  a  machine-
     independent fashion.


     Conversions are performed one at  a  time  by  converting  a
     source  datum  into  an internal format large enough to hold
     any input exactly, then by converting the internal  data  to
     the  destination form.  Thus any pair of source and destina-
     tion formats is permitted, but efficiency is not as high  as
     would  be  the case for programs written to convert from one
     specific format to another.