The DIGITAL Fortran 90 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.4 Methods of Specifying the Unformatted Numeric Format

The four 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.
• Add the CONVERT specifier to the OPEN statement for a specific unit number.
• Compiling 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.
• Compiling the program with the appropriate f90 option -convert keyword . This 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 an environment variable first
2. Check the OPEN statement CONVERT specifier
3. Check whether an OPTIONS statement with a /CONVERT=(keyword) qualifier was present when the program was compiled
4. 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

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 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.

10.4.2 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 method.

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.4.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.4.3 OPTIONS Statement /CONVERT=keyword Method

You can only specify one numeric file format for all unit numbers using this method, unless you also use the FORT_CONVERTn environment variable or 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 could use one source program and compile it using different f90 commands to create multiple executable programs that each read a certain format.

The environment variable and OPEN CONVERT specifier methods take precedence over this method. For instance, you might use the environment variable or OPEN CONVERT specifier method to specify each unit number that will use a format other than that specified using the f90 command 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 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 the environment variable method 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 DIGITAL Fortran Language Reference Manual.

10.4.4 f90 Command -convert keyword Option Method

You can specify only one numeric format for all unit numbers by using the f90 command 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 (the keyword must be in lowercase) or the equivalent OPTIONS statement. 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 variable or OPEN CONVERT specifier method to specify each unit number that will use a format other than that specified using the f90 command 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 the environment variable method or the OPEN statement CONVERT specifier method.

10.4.5 Additional Notes on Nonnative Data

The following notes apply 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 DIGITAL 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."¹
• Certain vendors apply different OPEN statement defaults to determine the record type. The default record type (RECORDTYPE) with DIGITAL Fortran 90 depends on the values for the ACCESS and FORM specifiers for the OPEN statement, as described in the DIGITAL 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 DIGITAL Fortran Language Reference Manual.
• On DIGITAL Fortran 90 file characteristics, see the Section 7.4.
• On DIGITAL Fortran 90 record types, see Section 7.4.3 and Section 7.8.

This chapter provides information on the following topics:

• Passing data arguments and function return values by using DIGITAL Fortran 90 procedures and subprograms ( Section 11.1)
• Using the cDEC$ ALIAS and cDEC$ ATTRIBUTES directives ( Section 11.2) to:
  • Specify an alternate name (alias) for external subprograms
  • Change the way certain arguments are passed
  • Request that C language rules be used for external names and arguments being passed
• Passing data arguments and function return values between DIGITAL Fortran 90 and DIGITAL Fortran 77 procedures and subprograms ( Section 11.3)
• Passing data arguments and function return values between DIGITAL Fortran 90 and C functions on DIGITAL UNIX systems ( Section 11.4)

The bounds of the main program are usually defined by using PROGRAM and END or END PROGRAM statements. Within the main program, you can define entities related to calling a function or subroutine, including modules and interface blocks.

A function or subroutine is considered a subprogram. A subprogram can accept one or more data values passed from the calling routine; the values are called arguments.

There are two types of arguments:

• Actual arguments are specified in the subprogram call.
• Dummy arguments are variables within the function or subroutine that receive the values (from the actual arguments).

The following methods define the interface between procedures:

• Declare and name a function with a FUNCTION statement and terminate the function definition with an END FUNCTION statement. Set the value of the data to be returned to the calling routine by using the function name as a variable in an assignment statement (or by specifying RESULT in a FUNCTION statement).
  Reference a function by using its name in an expression.
• Declare and name a subroutine with a SUBROUTINE statement and terminate the subroutine definition with an END SUBROUTINE statement. No value is returned by a subroutine.
  Reference a subroutine by using its name in a CALL statement (or use a defined assignment statement).
• For an external subprogram, depending on the type of arguments or function return values, you may need to declare an explicit interface to the arguments and function return value by using an interface block.
  Declare and name an interface block with an INTERFACE statement and terminate the interface block definition with an END INTERFACE statement. The interface body that appears between these two statements consists of function or subroutine specification statements.
• You can make data, specifications, definitions, procedure interfaces, or procedures globally available to the appropriate parts of your program by using a module (use association).
  Declare a module with a MODULE statement and terminate the module definition with an END MODULE statement. Include the definitions and other information contained within the module in appropriate parts of your program with a USE statement. A module can contain interface blocks, function and subroutine declarations, data declarations, and other information.

For More Information:

On the DIGITAL Fortran 90 language, including statement functions and defined assignment statements not described in this manual, see the DIGITAL Fortran Language Reference Manual.

11.1.1 Explicit and Implicit Interfaces

An explicit interface occurs when the properties of the subprogram interface are known within the scope of the function or subroutine reference. For example, the function reference or CALL statement occurs at a point where the function or subroutine definition is known through host or use association. Intrinsic procedures also have an explicit interface.

An implicit interface occurs when the properties of the subprogram interface are not known within the scope of the function or subroutine reference. In this case, the procedure data interface is unknown to the compiler. For example, external routines (EXTERNAL statement) that have not been defined in an interface block have an implicit interface.

In most cases, you can use a procedure interface block to make an implicit interface an explicit one. An explicit interface provides the following advantages over an implicit interface:

• Better compile-time argument checking and fewer run-time errors
• In some cases, faster run-time performance
• Ease of locating problems in source files since the features help to make the interface self-documenting
• Allows use of some language features that require an explicit interface, such as array function return values.
• When passing certain types of arguments between DIGITAL Fortran 90 and non-Fortran languages, an explicit interface may be needed. For example, detailed information about an assumed-shape array argument can be obtained from a DIGITAL Fortran 90 array descriptor. An array descriptor is generated when an appropriate explicit interface is used for certain types of array arguments.
• In parallel HPF programs executed with the DIGITAL Parallel Software Environment, an explicit interface is needed in order to avoid remapping of distributed data at the procedure interface. For more information, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

For More Information:

On DIGITAL Fortran 90 array descriptors, see Section 11.1.7.

11.1.2 Types of DIGITAL Fortran 90 Subprograms

There are three major types of subprograms:

• A subprogram might be local to a single program unit (known only within its host). Since the subprogram definition and all its references are contained within the same program unit, it is called an internal subprogram.
  An internal subprogram has an explicit interface.
• A subprogram needed in multiple program units should be placed within a module. To create a module subprogram within a module, add a CONTAINS statement followed by the subprogram code. A module subprogram can also contain internal subprograms.
  A module subprogram has an explicit interface in those program units that reference the module with a USE statement (unless it is declared PRIVATE).
• External subprograms are needed in multiple program units but cannot be placed in a module. This makes their procedure interface unknown in the program unit in which the reference occurs. Examples of external subprograms include general-purpose library routines in standard libraries and subprograms written in other languages, like C or Ada.
  Unless an external subprogram has an associated interface block, it has an implicit interface. To provide an explicit interface for an external subprogram, create a procedure interface block (see Section 11.1.3).
  For subprograms with no explicit interface, declare the subprogram name as external. You can do this by using the EXTERNAL statement within the program unit where the external subprogram reference occurs. This allows the linker to resolve the reference.
  An external subprogram must not contain PUBLIC or PRIVATE statements.

Procedure interface blocks allow you to specify an explicit interface for a subprogram as well as define generic procedure names. This section limits discussion to those interface blocks used to provide an explicit subprogram interface. For complete information on interface blocks, see the DIGITAL Fortran Language Reference Manual.

The components of a procedure interface block follow:

• Begin a procedure interface block with an INTERFACE statement. Unless you are defining a generic procedure name, user-defined operator, or user-defined assignment, only the word INTERFACE is needed.
• To provide the interface body, copy the procedure specification statements from the actual subprogram, including:
  • The FUNCTION or SUBROUTINE statements.
  • The interface body. For a procedure interface block, this includes specification (declaration) statements for the dummy arguments and a function return value (omit data assignment, FORMAT, ENTRY, DATA, and related statements).
    The interface body can include USE statements to obtain definitions.
    In parallel HPF programs, any DISTRIBUTE, ALIGN, and INHERIT (!HPF) directives for the dummy arguments must also be included. For more information about procedure interface blocks for parallel HPF programs, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.
  • The END FUNCTION or END SUBROUTINE statements.
• Terminate the interface block with an END INTERFACE statement.
• To make the procedure interface block available to multiple program units, you can do one of the following:
  • Place the procedure interface block in a module. Reference the module with a USE statement in each program unit that references the subprogram (use association).
  • Place the procedure interface block in each program unit that references the subprogram.

For an example of a module that contains a procedure interface block, see Section 1.3.