Specify the Data Format

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

Download PDF

ID 767251

Date 7/13/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-8AE928C0-92CF-4CC1-B77C-960A00CE5CD6

View Details

Specify the Data Format

There are a number of methods for specifying a non-native numeric format for unformatted data:

Environment Variable FORT_CONVERT.ext or FORT_CONVERT_ext Method

Set an environment variable for a specific file name extension before the file is opened. The environment variable is named FORT_CONVERT.ext or FORT_CONVERT_ext, where ext is the file name extension (suffix).
Environment Variable FORT_CONVERTn Method

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.
Environment Variable F_UFMTENDIAN Method

Set an environment variable for a set of units before the application is executed. The environment variable is named F_UFMTENDIAN.
OPEN Statement CONVERT Method

Specify the CONVERT keyword in the OPEN statement for a specific unit number.
OPTIONS Statement Method

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.
Compiler Option -convert or /convert Method

Compile the program with the appropriate compiler option, which affects all unit numbers that use unformatted data specified by the program. Use the convert compiler option.

If none of these methods are specified, the native LITTLE_ENDIAN format is assumed (no conversion occurs between disk and memory).

Any keyword listed in Supported Native and Non-native Numeric Formats can be used with any of these methods, except for the Environment Variable F_UFMTENDIAN Method, which supports only LITTLE_ENDIAN and BIG_ENDIAN.

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

Check for an environment variable (FORT_CONVERTn) for the specified unit number (applies to any file opened on a particular unit).
Check for an environment variable (FORT_CONVERT.ext is checked before FORT_CONVERT_ext) for the specified file name extension (applies to all files opened with the specified file name extension).
Check for an environment variable (F_UFMTENDIAN) for the specified unit number (or for all units).

NOTE:

This environment variable is checked only when the application starts executing.
Check the OPEN statement CONVERT specifier.
Check whether an OPTIONS statement with a CONVERT:keyword qualifier was present when the program was compiled.
Check whether the convert compiler option was present when the program was compiled.

Environment Variable FORT_CONVERT.ext or FORT_CONVERT_ext Method

Use this method to specify a non-native numeric format for each specified file name extension (suffix). Specify the numeric format at runtime by setting the appropriate environment variable before an implicit or explicit OPEN to one or more unformatted files. Use the format FORT_CONVERT.ext or FORT_CONVERT_ext (where ext is the file extension or suffix). The FORT_CONVERT.ext environment variable is checked before FORT_CONVERT_ext environment variable (if ext is the same).

For example, assume you have a previously compiled program that reads numeric data from one file and writes to another file using unformatted I/O statements. You want the program to read non-native big endian (IEEE floating-point) format from a file with a .dat file extension and write that data in native little endian format to a file with an extension of .data. In this case, the data is converted from big endian IEEE format to native little endian IEEE memory format (IEEE binary32 and IEEE binary64) 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 a program, the following command sets the appropriate environment variables before running the program:

Linux*

setenv FORT_CONVERT.DAT BIG_ENDIAN

Windows*

set FORT_CONVERT.DAT=BIG_ENDIAN

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 or FORT_CONVERT_ext environment variable is used if a FORT_CONVERTn environment variable is not set for the unit number.

The FORT_CONVERTn and the FORT_CONVERT.ext or 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).

You can set the appropriate environment variable using the format FORT_CONVERT.ext or FORT_CONVERT_ext. If you also use Intel® Fortran on Linux* systems, consider using the FORT_CONVERT_ext form, because a dot (.) cannot be used for environment variable names on certain Linux* command shells. If you do define both FORT_CONVERT.ext and FORT_CONVERT_ext for the same extension (ext), the file defined by FORT_CONVERT.ext is used.

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

Environment Variable FORT_CONVERTn Method

You can use this method to specify a non-native numeric format for each specified unit number. You specify the numeric format at runtime by setting the appropriate environment variable before an implicit or explicit OPEN to that unit number.

When the appropriate environment variable is set when you open the file, the environment variable is always used because this method takes precedence over the other methods. For example, 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).

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 non-native 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 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 command sequence sets the appropriate environment variables before running a program.

Linux

setenv FORT_CONVERT28 BIG_ENDIAN
setenv FORT_CONVERT29 NATIVE

Windows

set FORT_CONVERT28=BIG_ENDIAN 
set FORT_CONVERT29=NATIVE

The following figure shows the data formats used on disk and in memory when the program is run after the environment variables are set.

Sample Unformatted File Conversion

This method takes precedence over other methods.

Environment Variable F_UFMTENDIAN Method

This little-endian-big-endian conversion feature is intended for Fortran unformatted input/output operations. It enables the development and processing of files with little-endian and big-endian data organization.

The F_UFMTENDIAN environment variable is processed once at the beginning of program execution. Whatever it specifies for specific units or for all units continues for the rest of the execution.

Specify the numbers of the units to be used for conversion purposes by setting F_UFMTENDIAN. Then, the READ/WRITE statements that use these unit numbers will perform relevant conversions. Other READ/WRITE statements will work in the usual way.

General Syntax for F_UFMTENDIAN

In the general case, the variable consists of two parts divided by a semicolon. No spaces are allowed inside the F_UFMTENDIAN value:

F_UFMTENDIAN=MODE | [MODE;] EXCEPTION

where:

MODE = big | little
EXCEPTION = big:ULIST | little:ULIST | ULIST
ULIST = U | ULIST,U
U = decimal | decimal -decimal

MODE defines current format of data, represented in the files; it can be omitted.

The keyword little means that the data has little endian format and will not be converted. This is the default.

The keyword big means that the data has big endian format and will be converted.
EXCEPTION is intended to define the list of exclusions for MODE.EXCEPTION keyword (little or big) defines data format in the files that are connected to the units from the EXCEPTION list. This value overrides MODE value for the units listed.

The EXCEPTION keyword and the colon can be omitted. The default when the keyword is omitted is big.
Each list member U is a simple unit number or a number of units. The number of list members is limited to 64.
decimal is a non-negative decimal number less than 232.

Converted data should have basic data types or arrays of basic data types. Derived data types are disabled.

Error messages may be issued during the little-endian-to-big-endian conversion. They are all fatal.

On Linux* systems, the command line for the variable setting in the shell is:

Sh: export F_UFMTENDIAN=MODE;EXCEPTION

NOTE:

The environment variable value should be enclosed in quotes if the semicolon is present.

The environment variable can also have the following syntax:

F_UFMTENDIAN=u[,u] . . .

Examples

F_UFMTENDIAN=big

All input/output operations perform conversion from big-endian to little-endian on READ and from little-endian to big-endian on WRITE.
F_UFMTENDIAN="little;big:10,20"

or F_UFMTENDIAN=big:10,20

or F_UFMTENDIAN=10,20

The input/output operations perform big-endian to little endian conversion only on unit numbers 10 and 20.
F_UFMTENDIAN="big;little:8"

No conversion operation occurs on unit number 8. On all other units, the input/output operations perform big-endian to little-endian conversion.
F_UFMTENDIAN=10-20

The input/output operations perform big-endian to little-endian conversion on units 10, 11, 12 , ... 19, 20.

Assume you set F_UFMTENDIAN=10,100 and run the following program.

integer*4   cc4
integer*8   cc8
integer*4   c4
integer*8   c8
c4 = 456
c8 = 789  

! prepare a little endian representation of data

open(11,file='lit.tmp',form='unformatted')
write(11) c8
write(11) c4
close(11)

! prepare a big endian representation of data

open(10,file='big.tmp',form='unformatted')
write(10) c8
write(10) c4
close(10)

! read big endian data and operate with them on 
!  little endian machine.

open(100,file='big.tmp',form='unformatted')
read(100) cc8
read(100) cc4

! Any operation with data, which have been read

! . . .
close(100)
stop
end

Now compare lit.tmp and big.tmp files with the help of the od utility:

> od -t x4 lit.tmp
0000000 00000008 00000315 00000000 00000008
0000020 00000004 000001c8 00000004
0000034
> od -t x4 big.tmp
0000000 08000000 00000000 15030000 08000000
0000020 04000000 c8010000 04000000
0000034

You can see that the byte order is different in these files.

OPEN Statement CONVERT Method

Use this method to specify a non-native numeric 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 and the compiler option CONVERT[:] keyword method, but has a lower precedence than the environment variable methods.

For example, the following source code shows how the OPEN statement would be coded to read unformatted VAXD numeric data from unit 15, which might be processed and possibly written in native little endian format to unit 20 (the absence of the CONVERT keyword or environment variables FORT_CONVERT20, FORT_CONVERT.dat, or FORT_CONVERT_dat indicates native little endian data for unit 20):

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

A hard-coded OPEN statement CONVERT keyword value cannot be changed after compile time. However, to allow selection of a particular format at runtime, equate the CONVERT keyword 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 at runtime for a unit number by using one of the environment variable methods ( Environment Variable FORT_CONVERTn Method, Environment Variable FORT_CONVERT.ext or FORT_CONVERT_ext Method, or Environment Variable F_UFMTENDIAN Method), which take precedence over the OPEN statement CONVERTkeyword method.

OPTIONS Statement Method

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

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

The environment variable methods and the OPEN statement CONVERT=keyword method take precedence over this method. For example, you might use the FORT_CONVERTn environment variable or OPEN CONVERT=keyword method to specify each unit number that will use a format other than that specified using the ifortoption method.

This method takes precedence over the ifortconvert[:]keyword compiler 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 ifort command qualifiers. For example, to use VAX F_floating, G_floating, and H_floating 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, 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, see the OPTIONS statement.

Compiler Option -convert or /convert Method

You can only specify one numeric format for all unformatted file unit numbers using the convert compiler option unless you also use one (or more) of the previous data format methods.

You specify the numeric format at compile time and must compile all routines under the same convert keyword compiler option. You can use the same source program and compile it using different ifort commands (or the equivalent in the IDE) to create multiple executable programs that each read a certain format.

If you specify other methods, the other methods take precedence over using this method. For instance, you might use the environment variable or OPEN statement CONVERT specifier method to specify each unit number that will use a format different than that specified using the convert keyword compiler option method for all other unit numbers.

For example, the following command compiles program file.for to use VAX D_floating (and F_floating) floating-point data for all unit numbers (unless superseded by one of the other methods). Data is converted between the file format and the little endian memory format (little endian integers, IEEE binary32, IEEE binary64, and IEEE binary128 little endian IEEE* floating-point format). The created file, vconvert.exe, can then be run:

Linux and macOS

ifort file.for -o vconvert.exe -convert vaxd

Windows

  ifort file.for /convert:vaxd /link /out:vconvert.exe

Because this method affects all unformatted file unit numbers, you cannot read data in one format and write it in another file format using only the convert keyword compiler option. You can if you use it in combination with the environment variable methods or the OPEN statement CONVERT specifier method to specify a different format for a particular unit number.

Parent topic: Data Portability

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

Specify the Data Format

Environment Variable FORT_CONVERT.ext or FORT_CONVERT_ext Method

Environment Variable FORT_CONVERTn Method

Environment Variable F_UFMTENDIAN Method

OPEN Statement CONVERT Method

OPTIONS Statement Method

Compiler Option -convert or /convert Method

See Also