# マニュアルページ convert_external.3m

## 名前

         convert_external - 外部バイナリデータ形式の変換

## 形式

         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_signed,
              convert_external_unsigned,
              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 ;     /* 書式のアーキテクチャ */
              enum convert_external_type_t type ;     /* 書式の型 */
              int size ;                    /* 書式サイズ、バイト (8 ビット) 数で */
              } 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() は C プログラムで使用され、SPARC 以外のシ
         ステム上のバイナリデータと SPARC バイナリデータとの間で変換
         を行います。データは、符号つき整数、符号なし整数、浮動小数点
         数です。convert_external() は Fortran プログラムの (CALL
         CONVERT_EXTERNAL(...)) で同様の目的で使用されます。このと
         き、すべての引数は参照による呼び出しが行われます。

         convert_external_t 型は、サポート形式の列挙です。各アーキテ
         クチャに対し、サイズが 1、2、4、8、16 バイトの符号つきまたは
         符号なしの整数と、4、8、10、12、16 バイトの浮動小数点型がサ
         ポートされます。変換元または変換先に正しくないサイズが指定さ
         れた場合、変換は行われず、(1<<fp_division) を返します。変換
         元と変換先のサイズが正しければ、この例外が起こることはありま
         せん。

         サポートされているアーキテクチャと形式は次のとおりです。

    external_t       ビッグ/リトル   float*4   float*8   float*10   float*12   float*16

    アーキテクチャ   エンディアン     形式      形式       形式       形式       形式

    sparc               ビッグ        IEEE      IEEE       なし     MC68881      IEEE
                                     単精度    倍精度               拡張精度   4 倍精度

    pc                  リトル        IEEE      IEEE      i80x87    i80960KB     IEEE
                                     単精度    倍精度    拡張精度   拡張精度   4 倍精度

    vax                 リトル        VAX F     VAX D      なし       なし      VAX H

    vaxg                リトル        VAX F     VAX G      なし       なし      VAX H

    s370                ビッグ        S/370     S/370      なし       なし      S/370
                                     単精度    倍精度                          拡張精度

    cray                ビッグ        なし     Cray-1      なし       なし      Cray-1
                                               単精度                           倍精度

         MC68000 と SPARC は同じビッグエンディアン形式です。Intel PC
         は、8086/8087、80x86/7、80486 のどれも同じリトルエンディアン
         形式です。表の中の ``なし'' は、サイズが適当でないことを表し
         ています。この場合、変換は行いません。``IEEE 4 倍精度 ''
         は、IEEE 単精度および倍精度を 15 の指数ビット、1 つの暗黙的
         有効ビット、112 の暗黙的有効ビットを持つ形式へのビッグまたは
         リトルエンディアン拡張を示します。

## 使用法

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

              excep
                   関数値は、変換中に検出されたすべての例外の累計値で
                   す。個々の例外を検出することが重要な場合、1 度に 1
                   つのデータ項目だけを変換するように n を 1 にしてく
                   ださい。

              src_p
                   連続配列として格納された変更対象のデータへのポイン
                   タ。ポインタは境界合わせをする必要がないことを強調
                   するために char * で宣言されます。ただし、同じプロ
                   グラムでそれ以後 SPARC 形式に変更するデータは、適
                   切に境界合わせしなければなりません。

              dst_p
                   連続配列として格納された変更後のデータへのポイン
                   タ。

              src_format
                   変換元データの形式についての記述。

              dst_format
                   変換先データの形式についての記述。

              rounding
                   変換先データに適用する丸めモード。

              n    変換対象のデータ項目の数。

         以下の丸めモードを選択できます。最初の丸めモードは、ほとんど
         すべてのアプリケーションの要求を満たすように意図されていま
         す。

         (int) convert_external_common
              符号つき整数または符号なし整数形式の変換先をゼロ方向に
              丸める (2.9 は 2 に、-2.9 は -2 に丸める)
              IEEE 浮動小数点形式の変換先を最も近いバイアスされていな
              い値に丸める。
              VAX 浮動小数点形式の変換先を最も近いバイアスされた値に
              丸める。
              IBM 370 と Cray の浮動小数点形式の変換先をゼロ方向に丸
              める。

         (int) convert_external_biased
              最も近いバイアスされた値に丸める (整数の変換先の場合、
              1.5 は 2 に、2.5 は 3 に丸める)。

         (int) convert_external_away
              ゼロからの丸め (整数の変換先の場合、2.1 は 3, -2.1 は
              -3 に丸める)。

         (int) fp_nearest, fp_tozero, fp_positive, fp_negative
              IEEE 754 で規定されているモードの 1 つで丸めを行う。

         変換後、 (excep & (1 << fp_invalid)) != 0 が真であれば、1 つ
         以上の無効例外が発生します。他の例外もこれと同じ方法で定義さ
         れています。

         fp_invalid
              (1) 入力引数に IEEE シグナルを発生する NaN また は  VAX
              の 予約済みオペランドが指定された、(2) 入力引数が無限大
              で、かつ変換先が符号付き整数型または符号なし整数型 だっ
              た、 (3) 浮動小数点型に無限大表記がなかった、のいずれか
              の場合。

         fp_overflow
              入力引数が有限数で大きかったが、通常の丸め誤差だけが 原
              因 で変換先の形式で表現できなかった場合。変換先の形式が
              符号つき整数または符号なし整数型の場合、fp_overflow  は
              整数オーバーフローを表します。

         fp_underflow
              入力引数が有限数で小さかったが、通常の丸め誤差だけが 原
              因で変換先の形式で表現できなかった場合。この例外は、変
              換先が浮動小数点型の場合にだけ発生します。

         fp_inexact
              入力引数は有限数だったが、変換先の形式で正確に表現でき
              なかった場合。

         fp_division
              変換元または変換先の形式がサポートされていない。変換は
              行われません。

         外部データを SPARC 形式に変換し、SPARC 上で処理を 行なった
         後、そのデータを外部形式に戻す場合、SPARC 上の変換と処理で例
         外が発生することはありませんが、この作業全体を外部システム上
         で行なった場合と同じ結果が得られることはほとんどありません。

## 使用例

      外部システム上でのデータの生成
         次のコードは、外部システム上で Fortran を用いてバイナリ浮動
         小数点データを作成するための代表的な方法を示しています。

                      REAL A(100)
                      WRITE(9) A

      C による外部データから SPARC 内部形式への変換
         上記のバイナリ・データファイルが Cray コンピュータ上のテープ
         で作成され、そのテープが SPARC システム上で読み込まれたとし
         ます。バイアスされた丸めを用いて、IEEE 倍精度浮動小数点形式
         に変換するには、次のようにします。

         #include <sunmath.h>

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

         /*    ここで、Cray のデータを配列 datasrc に読み込む ...  */

         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);

         /*
          * 通常、不正確例外は問題にしないので、
          * 次の操作を行う。
          */

         excep &= ~(1 << fp_inexact);

         /*
          * この例では他の例外が発生する可能性がある。
          * そのような例外の発生場所は、次のようにして見つけることができます
          */
         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) {
                 /* datadest[i] についての特定の操作 */
             }
         }

      Fortran による SPARC 内部データから外部形式への変換
         SPARC プログラムで作成したデータを IBM PC に読み込ませ る に
         は、次のようにして変換します。

              #include <floatingpoint.h>

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

              c        ここで配列 datasrc を作成 ...

                      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        発生する可能性がある唯一の例外は、シグナルを発生する NaN を
              c        変換することによる fp_invalid

              c        ここで、IBM PC が読み込むことのできるファイルにデータを書き出す

## 関連項目

         dd(1M)
              外部システムからテープを読み込む場合

         xdr(3N)
              任意のデータ構造をマシンに依存した方法で書式化する場合

## 注意事項

         変換は一度に 1 段階ずつ行われます。まず、変換元データから す
         べての入力を正確に保持するのに十分な内部形式に変換した後、内
         部データを変換先の形式に変換します。したがって、変換元と変換
         先のデータの組み合わせは自由ですが、ある特定の書式から別の書
         式に変換するように書かれたプログラムを使用する場合よりも効率
         的ではありません。