# Compaq Fortran
User Manual for
Tru64 UNIX and
Linux Alpha Systems

Previous | Contents | Index

# Chapter 10
Converting Unformatted Numeric Data

This chapter contains the following topics:

- Section 10.1, Endian Order of Numeric Formats
- Section 10.2, Little Endian Floating-Point Format
- Section 10.3, Native and Supported Nonnative Numeric Formats
- Section 10.4, Limitations of Numeric Conversion
- Section 10.5, Methods of Specifying the Unformatted Numeric Format
- Section 10.6, Additional Information on Nonnative Data

# 10.1 Endian Order of Numeric Formats

Data storage uses a convention of either little endian or big endian storage, depending on the computer. The storage convention generally applies to numeric values that span multiple bytes.

Little endian storage occurs when:

- The least significant bit (LSB) value is in the byte with the lowest address.
- The most significant bit (MSB) value is in the byte with the highest address.
- The address of the numeric value is the byte containing the LSB. Subsequent bytes with higher addresses contain more significant bits.

Big endian storage occurs when:

- The least significant bit (LSB) value is in the byte with the highest address.
- The most significant bit (MSB) value is in the byte with the lowest address.
- The address of the numeric value is the byte containing the MSB. Subsequent bytes with higher addresses contain less significant bits.

Figure 10-1 shows the difference between the two byte-ordering schemes.

Figure 10-1 Little Endian and Big Endian Storage of an INTEGER Value

Moving data files between little endian and big endian computers requires that the data be converted.

# 10.2 Little Endian Floating-Point Format

On Compaq Tru64 UNIX and Linux systems, Compaq Fortran supports the following little endian floating-point formats in memory:

Floating-Point Size | Format in Memory
--- | ---
KIND=4 | IEEE S_float
KIND=8 | IEEE T_float
KIND=16 | Compaq IEEE style X_float

If your program needs to read or write unformatted data files containing a floating-point format that differs from the format in memory for that data size, you can request that the unformatted data be converted.

Converting unformatted data is generally faster than converting formatted data and is less likely to lose precision for floating-point numbers.

# 10.3 Native and Supported Nonnative Numeric Formats

Compaq Fortran provides the capability for programs to read and write unformatted data (originally written using unformatted I/O statements) in several nonnative floating-point formats and in big endian INTEGER or floating-point format.

When reading a nonnative unformatted format, the nonnative format on disk must be converted to native format in memory. Similarly, native data in memory can be written to a nonnative unformatted format. If a converted nonnative value is outside the range of the native data type, a run-time message appears (listed in Table 8-3).

Supported native and nonnative floating-point formats include:

- Standard IEEE little endian floating-point formats1 and little endian integers. These formats are found on Compaq Tru64 UNIX Alpha systems, Compaq OpenVMS Alpha systems, Microsoft Windows NT systems, IBM-compatible PC systems, and Linux Alpha systems.
  On Tru64 UNIX and Linux systems, these are the native (in memory) floating-point and integer formats.
- Standard IEEE big endian floating-point formats1 and big endian integers found on most Sun systems, most Hewlett-Packard systems (such as HP-UX systems), and IBM's RISC System/6000 systems.
- Compaq VAX little endian floating-point formats and little endian integers supported by Compaq Fortran for OpenVMS VAX systems and Compaq Fortran for OpenVMS Alpha systems.
- Big endian proprietary floating-point formats and big endian integers associated with CRAY (CRAY systems).
- Big endian proprietary floating-point formats and big endian integers associated with IBM (the IBM's System\370 and similar systems).

The native memory format uses little endian integers and little endian IEEE floating-point formats, as follows:

- INTEGER and LOGICAL declarations of one, two, four, or eight bytes (intrinsic kinds 1, 2, 4, and 8). You can specify the integer data length by using an explicit data declaration (kind parameter or size specifier). All INTEGER and LOGICAL declarations without a kind parameter or size specifier will be four bytes in length. To request an 8-byte size for all INTEGER and LOGICAL declarations without a kind parameter or size specifier, use an `f90` command-line option on Tru64 UNIX systems or and `fort` command-line option on Linux systems (see Section 9.2.1).
- IEEE S_float format for single-precision 4-byte REAL and 8-byte COMPLEX declarations (KIND=4). You can specify the real or complex data length by using an explicit data declaration (kind parameter or size specifier). For all REAL or COMPLEX declarations without a kind parameter or size specifier, this is the default size unless you use an `f90` command-line option to request double-precision sizes (see Section 9.4.1).
- IEEE T_float format for double-precision 8-byte REAL and 16-byte COMPLEX declarations (KIND=8). You can specify the real or complex data length by using an explicit data declaration (kind parameter or size specifier). To request double-precision sizes for all REAL or COMPLEX declarations without a kind parameter or size specifier, you can use an `f90` command-line option (see Section 9.4.1).
- Compaq IEEE style X_float format for extended-precision 16-byte REAL and 32-byte COMPLEX declarations (KIND=16). You can specify the real data length by using an explicit data declaration (kind parameter or size specifier). To request extended-precision sizes for all DOUBLE PRECISION or DOUBLE COMPLEX declarations, you can use an `f90` command-line option (see Section 9.4.1).

Table 10-1 lists the keywords for the supported unformatted file data formats. Use the appropriate keyword after the `-convert` option (such as `-convert cray` ) or as an environment variable value (see Section 10.5.1 and Section 10.5.2).

Table 10-1 Unformatted Numeric Formats, Keywords, and Supported Data Types
Recognized Keyword1 | Description
--- | ---
BIG_ENDIAN | Big endian integer data of the appropriate INTEGER size (one, two, four, or eight bytes) and big endian IEEE floating-point formats for REAL and COMPLEX single- and double- and extended-precision numbers. INTEGER (KIND=1) or INTEGER*1 data is the same for little endian and big endian.
CRAY | Big endian integer data of the appropriate INTEGER size (one, two, four, or eight bytes) and big endian CRAY proprietary floating-point format for REAL and COMPLEX single- and double-precision numbers.
FDX | Native little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following little endian Compaq proprietary floating-point formats: VAX F_float for REAL (KIND=4) and COMPLEX (KIND=4) VAX D_float for REAL (KIND=8) and COMPLEX (KIND=8) IEEE style X_float for REAL (KIND=16) and COMPLEX (KIND=16)
FGX | Native little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following little endian Compaq proprietary floating-point formats: VAX F_float for REAL (KIND=4) and COMPLEX (KIND=4) VAX G_float for REAL (KIND=8) and COMPLEX (KIND=8) IEEE style X_float for REAL (KIND=16) and COMPLEX (KIND=16)
IBM | Big endian integer data of the appropriate INTEGER size (one, two, or four bytes) and big endian IBM proprietary (System\370 and similar) floating-point format for REAL and COMPLEX single- and double-precision numbers.
LITTLE_ENDIAN | Native little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following native little endian IEEE floating-point formats: S_float for REAL (KIND=4) and COMPLEX (KIND=4) T_float for REAL (KIND=8) and COMPLEX (KIND=8) IEEE style X_float for REAL (KIND=16) and COMPLEX (KIND=16)
NATIVE | No conversion occurs between memory and disk. This is the default for unformatted files.
VAXD | Native little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following little endian VAX Compaq proprietary floating-point formats: VAX F_float for REAL (KIND=4) and COMPLEX (KIND=4) VAX D_float for REAL (KIND=8) and COMPLEX (KIND=8) VAX H_float for REAL (KIND=16) and COMPLEX (KIND=16)
VAXG | Native little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following little endian VAX Compaq proprietary floating-point formats: VAX F_float for REAL (KIND=4) and COMPLEX (KIND=4) VAX G_float for REAL (KIND=8) and COMPLEX (KIND=8) VAX H_float for REAL (KIND=16) and COMPLEX (KIND=16)

1When using the data type as a `-convert` keyword option on the `f90` command line, the data type keyword must be in lowercase, such as `-convert big_endian`.

While this solution is not expected to fulfill all floating-point conversion needs, it provides the capability to read and write various types of unformatted nonnative floating-point data.

For More Information:

- On porting OpenVMS Fortran data files to a Tru64 UNIX Alpha or a Linux Alpha system for use by Compaq Fortran, see Section A.4.
- On ranges and the format of native IEEE floating-point data types, see Table 9-1 and Section 9.4.
- On ranges and the format of VAX floating-point data types, see Section A.4.3.
- On specifying the size of INTEGER declarations (without a kind) using an `f90` command-line option, see Section 9.2.1.
- On specifying the size of LOGICAL declarations (without a kind) using an `f90` command-line option, see Section 9.3.
- On specifying the size of REAL or COMPLEX declarations (without a kind) using an `f90` command-line option, see Section 9.4.1.
- On data declarations and other Compaq Fortran language information, see the Compaq Fortran Language Reference Manual.

Note #### 1 IEEE floating-point formats are defined in the IEEE Standard for Binary Floating-Point Arithmetic, ANSI/IEEE Standard 754-1985, Institute of Electrical and Electronics Engineers, August 1985.

# 10.4 Limitations of Numeric Conversion

The Compaq Fortran floating-point conversion solution is not expected to fulfill all floating-point conversion needs.

Data (variables) contained in derived types and record structures (specified in a STRUCTURE statement) are not converted. When the variables are later examined as separate fields by the program, they will remain in the binary format they were stored in on disk, unless the program is modified.

If a program reads an I/O record containing multiple floating-point fields into an integer array (instead of their respective variables), the fields will not be converted. When the fields are later examined as separate fields by the program, they will remain in the binary format they were stored in on disk, unless the program is modified.

With EQUIVALENCE statements, the data type of the variable named in the I/O statement is used.

# 10.5 Methods of Specifying the Unformatted Numeric Format

The five methods you can use to specify the type of nonnative (or native) format are as follows:

- Set an environment variable for a specific unit number before the file is opened. The environment variable is named `FORT_CONVERTn` , where `n` is the unit number.
- Set an environment variable for a specific file name extension before the file is opened. The environment variable is named `FORT_CONVERT.ext` , where `ext` is the file name extension (suffix).
- Add the CONVERT specifier to the OPEN statement for a specific unit number.
- Compile the program with an OPTIONS statement that specifies the /CONVERT=keyword qualifier. This method affects all unit numbers using unformatted data specified by the program.
- Compile the program with the appropriate command-line option `-convert keyword` . This method affects all unit numbers using unformatted data specified by the program.

If you specify more than one method, the order of precedence when you open a file with unformatted data is:

1. Check for a `FORT_CONVERTn` environment variable
2. Check for a `FORT_CONVERT.ext` environment variable
3. Check the OPEN statement CONVERT specifier
4. Check whether an OPTIONS statement with a /CONVERT=keyword qualifier was present when the program was compiled
5. Check whether the `f90` `-convert keyword` option was used when the program was compiled

If none of these methods are specified, no conversion occurs between disk and memory. Data should therefore be in the native memory format (little endian integer and little endian IEEE format) or otherwise translated by the application program.

Any keyword listed in Table 10-1 can be used with any of these methods.

If you are uncertain about the format, you can do the following:

- Open the file (OPEN statement)
- Use an INQUIRE statement (by unit) that specifies the CONVERT specifier equated to a character variable
- Close the file (CLOSE statement)
- Open the file using the CONVERT variable value obtained from the INQUIRE statement

## 10.5.1 Environment Variable FORT_CONVERTn Method

You can use the environment variable method to specify multiple formats in a single program, usually one format for each unit number. You specify the numeric format at run time by setting the appropriate environment variable before you open that unit number. For example, to specify the numeric format for unit 9, set environment variable `FORT_CONVERT9` to the appropriate value (such as BIG_ENDIAN) before you run the program.

When you open the file, the environment variable is always used, since this method takes precedence over the `f90` command-line option methods. For instance, you might use this method to specify that different unformatted numeric formats for different unit numbers (perhaps in a script file that sets the environment variable before running the program).

For example, assume you have a previously compiled program that reads numeric data from unit 28 and writes it to unit 29 using unformatted I/O statements. You want the program to read nonnative big endian (IEEE floating-point) format from unit 28 and write that data in native little endian format to unit 29.

In this case, the data is converted from big endian IEEE format to native little endian IEEE memory format (S_float, T_float, X_float) when read from unit 28, and then written without conversion in native little endian IEEE format to unit 29.

Without requiring source code modification or recompilation of this program, the following C shell command sequence sets the appropriate environment variables before running the program ( `/usr/userc/conv_ieee.out` ):

    % setenv FORT_CONVERT28 BIG_ENDIAN
    % setenv FORT_CONVERT29 NATIVE
    % /usr/userc/conv_ieee.out

Figure 10-2 shows the data formats used on disk and in memory when the example file `/usr/userc/conv_ieee.out` is run after the environment variables are set with shell commands.

Figure 10-2 Sample Unformatted File Conversion

For More Information:

- On the shell commands you can use to set or unset environment variables, see Appendix B, Compaq Fortran Environment Variables.

## 10.5.2 Environment Variable FORT_CONVERT.ext Method

You can use this method to specify formats in a single program, usually one format for each specified file name extension (suffix). You specify the numeric format at run time by setting the appropriate environment variable before an implicit or explicit OPEN statement to one or more unformatted files.

For example, assume you have a previously compiled program that reads floating-point numeric data from one file and writes to another file using unformatted I/O statements. You want the program to read nonnative big endian (IEEE floating-point) format from a file with a `.dat` file extension suffix and write that data in native little endian format to a file with a suffix of `.data` . In this case, the data is converted from big endian IEEE format to native little endian IEEE memory format when read from `file.dat` , and then written without conversion in native little endian IEEE format to the file with a suffix of `.data` , assuming that environment variables `FORT_CONVERT.DATA` and `FORT_CONVERTn` (for that unit number) are not defined.

Without requiring source code modification or recompilation of this program, the following command sequence sets the appropriate environment variables before running the program ( `/usr/userc/proj2/cvbigend.exe` ):

    % setenv FORT_CONVERT.DAT BIG_ENDIAN
    % /usr/userc/proj2/cvbigend.exe

The `FORT_CONVERTn` method takes precedence over this method. When the appropriate environment variable is set when you open the file, the `FORT_CONVERT.ext` environment variable is used if a `FORT_CONVERTn` environment variable is not set for the unit number.

The `FORT_CONVERTn` and `FORT_CONVERT.ext` environment variable methods take precedence over the other methods. For instance, you might use this method to specify that a unit number will use a particular format instead of the format specified in the program (perhaps for a one-time file conversion).

The file name extension (suffix) is case-sensitive. The extension must be part of the file name (not the directory path).

## 10.5.3 OPEN Statement CONVERT='keyword' Method

You can use the OPEN statement method to specify multiple formats in a single program, usually one format for each specified unit number. This method requires an explicit file OPEN statement to specify the numeric format of the file for that unit number.

This method takes precedence over the OPTIONS statement or the `-convert keyword` method, but has a lower precedence than the environment variable methods.

The following source code shows an OPEN statement coded for unformatted VAXD numeric data (read from unit 15), and an OPEN statement coded for unformatted native little endian format (written to unit 20). The absence of the CONVERT specifier (in the second OPEN statement) or environment variable `FORT_CONVERT20` indicates native little endian data for unit 20:

    OPEN (CONVERT='VAXD', FILE='graph3.dat', FORM='UNFORMATTED', UNIT=15)
    .
    .
    .
    OPEN (FILE='graph3_ieee.dat', FORM='UNFORMATTED', UNIT=20)

A hard-coded OPEN statement CONVERT specifier keyword value cannot be changed after compile time. However, to allow selection of a particular format at run time, you can equate the CONVERT specifier to a variable and provide the user with a menu that allows selection of the appropriate format (menu choice sets the variable) before the OPEN occurs.

You can also select a particular format for a unit number at run time by using the environment variable method (see Section 10.5.1), which takes precedence over the OPEN statement CONVERT specifier method.

You can issue an INQUIRE statement (by unit number) to an opened file to obtain the current CONVERT option in use.

## 10.5.4 OPTIONS Statement /CONVERT=keyword Method

You can only specify one numeric file format for all unit numbers using this method, unless you also use one of the FORT_CONVERT environment variable methods or the OPEN statement CONVERT specifier method.

You specify the numeric format at compile time and must compile all routines under the same OPTIONS statement CONVERT=keyword qualifier. You can use one source program and compile it using different `f90` commands to create multiple executable programs that each read a certain format.

The environment variables and OPEN CONVERT specifier methods take precedence over this method. For instance, you might use the environment variables or OPEN CONVERT specifier method to specify each unit number that will use a format other than that specified using the `f90` command-line option method. This method takes precedence over the `f90` command `-convert keyword` option method.

You can use OPTIONS statements to specify the appropriate floating-point formats (in memory and in unformatted files) instead of using the corresponding `f90` command-line options. For example, to use VAX G_float (along with VAX F_float and VAX H_float) as the unformatted file format, specify the following OPTIONS statement:

    OPTIONS /CONVERT=VAXG

Because this method affects all unit numbers, you cannot read data in one format and write it in another format using the OPTIONS statement method, unless you use it in combination with one of the environment variable methods or the OPEN statement CONVERT keyword method to specify a different format for a particular unit number.

For More Information:

- On the OPTIONS statement, see the Compaq Fortran Language Reference Manual.

## 10.5.5 Command-Line -convert keyword Option Method

You can specify only one numeric format for all unit numbers by using the command-line option method, unless you also use the environment variable method or CONVERT specifier method.

You specify the numeric format at compile time and must compile all routines under the same `-convert keyword` option. You can use one source program and compile it using different `f90` commands to create multiple executable programs that each read a certain format.

The other methods take precedence over this method. For instance, you might use the environment variables or OPEN CONVERT specifier method to specify each unit number that will use a format other than that specified using the `f90` command-line option method.

For example, the following shell commands compile program `file.f90` to use VAX D_float and F_float data. Data is converted between the file format and the little endian memory format (little endian integers and S_float, T_float, and X_float little endian IEEE floating-point format). The created file, `vaxd_convert.out` , is then run:

    % f90 -convert vaxd -o vaxd_convert.out file.f90
    % vaxd_convert.out

Because this method affects all unit numbers, you cannot read or write data in different formats if you only use the `f90 -convert keyword` method. To specify a different format for a particular unit number, use the `f90 -convert keyword` method in combination with an environment variable method or the OPEN statement CONVERT specifier method.

# 10.6 Additional Information on Nonnative Data

The following information applies to porting nonnative data:

- When porting source code along with the unformatted data, vendors might use different units for specifying the record length (RECL specifier, see Section 7.4.4) of unformatted files. While formatted files are specified in units of characters (bytes), unformatted files are specified in longword units for Compaq Fortran and some other vendors. The Fortran 90 standard, in Section 9.3.4.5, states: "If the file is being connected for unformatted input/output, the length is measured in processor-dependent units."1
- Certain vendors apply different OPEN statement defaults to determine the record type. The default record type (RECORDTYPE) with Compaq Fortran depends on the values for the ACCESS and FORM specifiers for the OPEN statement, as described in the Compaq Fortran Language Reference Manual.
- Certain vendors use a different identifier for the logical data types, such as hex FF instead of 01 to denote `true` .
- Source code being ported might be coded specifically for big endian use.

For More Information:

- On OPEN statement specifiers, see the Compaq Fortran Language Reference Manual.
- On Compaq Fortran file characteristics, see Section 7.4, Types of Files and File Characteristics.
- On Compaq Fortran record types, see Section 7.4.3, Record Types, Record Overhead, and Maximum Record Length and Section 7.10, Format of Compaq Fortran Record Types.

Note #### 1 American National Standard Fortran 90, ANSI X3.198-1991, and International Standards Organization standard ISO/IEC 1539:1991

Previous | Next | Contents | Index