The XLFRTEOPTS environment variable

                       .-:------------------------------------------.          
                       V                                            |          
>>-XLFRTEOPTS=--+---+----runtime_option_name--=----option_setting---+--+---+-><
                '-"-'                                                  '-"-'   

• An I/O statement is executed.
• The RANDOM_SEED procedure is executed.
• An ALLOCATE statement needs to issue a runtime error message.
• A DEALLOCATE statement needs to issue a runtime error message.
• The multi-threaded implementation of the MATMUL procedure is executed.

aggressive_array_io={yes | no}

Controls whether or not the XL Fortran run time will take advantage of descriptor information when deciding to apply slower or faster algorithms to do array I/O operations. Descriptor information that specifies an array or array section as contiguous can be used to apply the faster algorithms which would otherwise be unsafe if the array or array section was not contiguous. The default is to perform aggressive array I/O operations.

Code executing under the current XL Fortran runtime but compiled with older XL Fortran compilers can cause the aggressive array I/O operations to be unsafe if the older compilers did not set the XL Fortran descriptor information correctly. This can be a problem with code built with old XL Fortran compilers no longer in service or built with XL Fortran compilers not at the latest service levels. Older code should be recompiled, if possible, with the current compiler instead of relying on the use of this option.

buffering={enable | disable_preconn | disable_all}

Determines whether the XL Fortran runtime library performs buffering for I/O operations.

The library reads data from, or writes data to the file system in chunks for READ or WRITE statements, instead of piece by piece. The major benefit of buffering is performance improvement.

If you have applications in which Fortran routines work with routines in other languages or in which a Fortran process works with other processes on the same data file, the data written by Fortran routines may not be seen immediately by other parties (and vice versa), because of the buffering. Also, a Fortran READ statement may read more data than it needs into the I/O buffer and cause the input operation performed by a routine in other languages or another process that is supposed to read the next data item to fail. In these cases, you can use the buffering runtime option to disable the buffering in the XL Fortran runtime library. As a result, a READ statement will read in exactly the data it needs from a file and the data written by a WRITE statement will be flushed out to the file system at the completion of the statement.

Note: I/O buffering is always enabled for files on sequential access devices (such as pipes, terminals, sockets). The setting of the buffering option has no effect on these types of files.

If you disable I/O buffering for a logical unit, you do not need to flush the contents of the I/O buffer for that logical unit with the FLUSH statement or the Fortran service routine flush_.

The suboptions for buffering are as follows:

enable

The Fortran runtime library maintains an I/O buffer for each connected logical unit. The current read-write file pointers that the runtime library maintains might not be synchronized with the read-write pointers of the corresponding files in the file system.

disable_preconn

The Fortran runtime library does not maintain an I/O buffer for each preconnected logical unit (0, 5, and 6). However, it does maintain I/O buffers for all other connected logical units. The current read-write file pointers that the runtime library maintains for the preconnected units are the same as the read-write pointers of the corresponding files in the file system.

disable_all

The Fortran runtime library does not maintain I/O buffers for any logical units.

In the following example, Fortran and C routines read a data file through redirected standard input. First, the main Fortran program reads one integer. Then, the C routine reads one integer. Finally, the main Fortran program reads another integer.

Fortran main program:

integer(4) p1,p2,p3
print *,'Reading p1 in Fortran...'
read(5,*) p1
call c_func(p2)
print *,'Reading p3 in Fortran...'
read(5,*) p3
print *,'p1 p2 p3 Read: ',p1,p2,p3
end

C subroutine (c_func.c):

#include <stdio.h>
void
c_func(int *p2)
{
    int n1 = -1;

    printf("Reading p2 in C...\n");
    setbuf(stdin, NULL);    /* Specifies no buffering for stdin */
    fscanf(stdin,"%d", &n1);
    *p2=n1;
    fflush(stdout);
}

Input data file (infile):

11111
22222
33333
44444

The main program runs by using infile as redirected standard input, as follows:

$ main < infile

If you turn on buffering=disable_preconn, the results are as follows:

Reading p1 in Fortran...
Reading p2 in C...
Reading p3 in Fortran...
p1 p2 p3 Read:  11111 22222 33333

If you turn on buffering=enable, the results are unpredictable.

buffer_size=size

Specifies the size of I/O buffers in bytes instead of using the block size of devices. size must be either -1 or an integer value that is greater than or equal to 4096. The default, -1, uses the block size of the device where the file resides.

Using this option can reduce the amount of memory used for I/O buffers when an application runs out of memory because the block size of devices is very large and the application opens many files at the same time.

Note the following when using this runtime option:

• Preconnected units remain unaffected by this option. Their buffer size is the same as the block size of the device where they reside except when the block size is larger than 64KB, in which case the buffer size is set to 64KB.
• This runtime option does not apply to files on a tape device or logical volume.
• Specifying the buffer size with the SETRTEOPTS procedure overrides any value previously set by the XLFRTEOPTS environment variable or SETRTEOPTS procedure. The resetting of this option does not affect units that have already been opened.

cnverr={yes | no}

If you set this runtime option to no, the program does not obey the IOSTAT= and ERR= specifiers for I/O statements that encounter conversion errors. Instead, it performs default recovery actions (regardless of the setting of err_recovery) and may issue warning messages (depending on the setting of xrf_messages).

Related information: For more information about conversion errors, see Data transfer statements in the XL Fortran Language Reference. For more information about IOSTAT values, see Conditions and IOSTAT values in the XL Fortran Language Reference.

cpu_time_type={usertime | systime | alltime | total_usertime | total_systime | total_alltime}

Determines the measure of time returned by a call to CPU_TIME(TIME).

The suboptions for cpu_time_type are as follows:

usertime

Returns the user time of a process.

systime

Returns the system time of a process.

alltime

Returns the sum of the user and system time of a process.

total_usertime

Returns the total user time of a process. The total user time is the sum of the user time of a process and the total user times of its child processes, if any.

total_systime

Returns the total system time of a process. The total system time is the sum of the system time of the current process and the total system times of its child processes, if any.

total_alltime

Returns the total user and system time of a process. The total user and system time is the sum of the user and system time of the current process and the total user and system times of their child processes, if any.

default_recl={64 | 32}

Allows you to determine the default record size for sequential files opened without a RECL= specifier. The suboptions are as follows:

64

Uses a 64-bit value as the default record size.

32

Uses a 32-bit value as the default record size.

The default_recl runtime option applies only in 64-bit mode. In 32-bit mode, default_recl is ignored and the record size is 32-bit.

Use default_recl when porting 32-bit programs to 64-bit mode where a 64-bit record length will not fit into the specified integer variable. Consider the following:

INTEGER(4) I
OPEN (11)
INQUIRE (11, RECL=i)

A runtime error occurs in the above code sample in 64-bit mode when default_recl=64, since the default record length of 2**63-1 does not fit into the 4-byte integer I. Specifying default_recl=32 ensures a default record size of 2**31-1, which fits into I.

For more information on the RECL= specifier, see the OPEN statement in the XL Fortran Language Reference.

errloc={yes | no}

Controls whether the file name and line number are displayed with an error message if a runtime error condition occurs during I/O or an ALLOCATE/DEALLOCATE statement. By default, the line number and file name appear prepended to the runtime error messages. If errloc=no is specified, runtime error messages are displayed without the source location information.

The errloc runtime option can be specified with the SETRTEOPTS procedure, as well.

erroreof={yes | no}

Determines whether the label specified by the ERR= specifier is to be branched to if no END= specifier is present when an end-of-file condition is encountered.

err_recovery={yes | no}

If you set this runtime option to no, the program stops if there is a recoverable error while executing an I/O statement with no IOSTAT= or ERR= specifiers. By default, the program takes some recovery action and continues when one of these statements encounters a recoverable error. Setting cnverr to yes and err_recovery to no can cause conversion errors to halt the program.

errthrdnum={yes | no}

When errthrdnum=yes is in effect, XL Fortran appends to all error messages the thread number of the running thread that is specified by the omp_get_thread_num routine. For single-threaded programs, the thread number is 0.

If you specify errloc=yes, the thread number is displayed in front of the file name and line number. If the IOMSG= specifier is present in an I/O statement, the thread number is prefixed to the error message and the other part of the message uses the same format as displayed on Standard error.

errtrace={yes | no}

Controls whether a traceback is displayed with an error message if a runtime error condition occurs during an I/O or ALLOCATE/DEALLOCATE statement. Specifying errtrace=no means runtime error messages are displayed without tracebacks.

To show more detailed information in tracebacks, compile with the -qlinedebug or -g option.

Tracebacks are not displayed if either of the following conditions is true:

• You use the IOSTAT=, ERR=, END=, or EOR= specifier in an I/O statement.
• You use the STAT= specifier in an ALLOCATE/DEALLOCATE statement.

For example, in the following sample code, the ERR= specifier is used to branch to some error handling code. Because the I/O statement causing the error specifies ERR=, no traceback is generated. The output is Open error., although errtrace=yes is specified.

program open_error
open(unit=11, file='doesnotexist', status='old', err=200) ! no traceback
close(11)
200 print *, 'Open error.'
end

iostat_end={extended | 2003std}

Sets the IOSTAT values based on the XL Fortran definition or the Fortran 2003 Standard when end-of-file and end-of-record conditions occur. The suboptions are as follows:

extended

Sets the IOSTAT variables based on XL Fortran's definition of values and conditions.

2003std

Sets the IOSTAT variables based on Fortran 2003's definition of values and conditions.

For example, setting the iostat_end=2003std runtime option results in a different IOSTAT value from extensions being returned for the end-of-file condition

    export XLFRTEOPTS=iostat_end=2003std
    character(10) ifl
    integer(4) aa(3), ios
    ifl = "12344321  "
    read(ifl, '(3i4)', iostat=ios) aa ! end-of-file condition occurs and
                                      ! ios is set to -1 instead of -2.

For more information on setting and using IOSTAT values, see the READ , WRITE , and Conditions and IOSTAT values sections in the XL Fortran Language Reference.

intrinthds={num_threads}

Specifies the number of threads for parallel execution of the MATMUL and RANDOM_NUMBER intrinsic procedures. The default value for num_threads when using the MATMUL intrinsic equals the number of processors online. The default value for num_threads when using the RANDOM_NUMBER intrinsic is equal to the number of processors online*2.

Changing the number of threads available to the MATMUL and RANDOM_NUMBER intrinsic procedures can influence performance.

langlvl={ | 90std | 95std | 2003std | 2008std | extended}

Determines the level of support for Fortran standards and extensions to the standards. The values of the suboptions are as follows:

90std

Instructs the compiler to flag any extensions to the Fortran 90 standard I/O statements and formats as errors.

95std

Instructs the compiler to flag any extensions to the Fortran 95 standard I/O statements and formats as errors.

2003std

Instructs the compiler to flag any extensions to the Fortran 2003 standard I/O statements and formats as errors.

For example, setting the langlvl=2003std runtime option results in a runtime error message.

integer(4) aa(100)
call setrteopts("langlvl=2003std")
    ...          ! Write to a unit without explicitly
    ...          ! connecting the unit to a file.
write(10, *) aa  ! The implicit connection to a file does not
    ...          ! comform with Fortran 2003 behavior.

2008std

Instructs the compiler to accept all standard I/O statements and formats that the Fortran 2003 standard specifies, as well as any Fortran 2008 formats that XL Fortran supports. Anything else is flagged as an error.

extended

Instructs that the compiler to accept the Fortran 95 language standard, Fortran 2003 features, the Fortran 2008 features supported by XL Fortran, and extensions, effectively turning off language-level checking.

To obtain support for items that are part of the Fortran 95 standard and are available in XL Fortran (such as namelist comments), you must specify one of the following suboptions:

• 95std
• 2003std
• 2008std
• extended

The following example contains a Fortran 95 extension (the file specifier is missing from the OPEN statement):

program test1

call setrteopts("langlvl=95std")
open(unit=1,access="sequential",form="formatted")

10 format(I3)

write(1,fmt=10) 123

end

Specifying langlvl=95std results in a runtime error message.

The following example contains a Fortran 95 feature (namelist comments) that was not part of Fortran 90:

program test2

INTEGER I
LOGICAL G
NAMELIST /TODAY/G, I

call setrteopts("langlvl=95std:namelist=new")

open(unit=2,file="today.new",form="formatted", &
    & access="sequential", status="old")

read(2,nml=today)
close(2)

end

today.new:

&TODAY  ! This is a comment
I = 123, G=.true. /

If you specify langlvl=95std, no runtime error message is issued. However, if you specify langlvl=90std, a runtime error message is issued.

The err_recovery setting determines whether any resulting errors are treated as recoverable or severe.

multconn={yes | no}

Enables you to access the same file through more than one logical unit simultaneously. With this option, you can read more than one location within a file simultaneously without making a copy of the file.

You can only use multiple connections within the same program for files on random-access devices, such as disk drives. In particular, you cannot use multiple connections within the same program for:

• Files have been connected for write-only (ACTION='WRITE')
• Files on sequential-access devices (such as pipes, terminals, sockets)

To avoid the possibility of damaging the file, keep the following points in mind:

• The second and subsequent OPEN statements for the same file can only be for reading.
• If you initially opened the file for both input and output purposes (ACTION='READWRITE'), the unit connected to the file by the first OPEN becomes read-only (ACCESS='READ') when the second unit is connected. You must close all of the units that are connected to the file and reopen the first unit to restore write access to it.
• Two files are considered to be the same file if they share the same device and i-node numbers. Thus, linked files are considered to be the same file.

multconnio={tty | nulldev | combined | no }

Enables you to connect a device to more than one logical unit. You can then write to, or read from, more than one logical unit that is attached to the same device. The suboptions are as follows:

combined

Enables you to connect a combination of null and TTY devices to more than one logical unit.

nulldev

Enables you to connect the null device to more than one logical unit.

tty

Enables you to connect a TTY device to more than one logical unit.

Note: Using this option can produce unpredictable results.

In your program, you can now specify multiple OPEN statements that contain different values for the UNIT parameters but the same value for the FILE parameters. For example, if you have a symbolic link called mytty that is linked to TTY device /dev/tty, you can run the following program when you specify the multconnio=tty option:

PROGRAM iotest
OPEN(UNIT=3, FILE='mytty', ACTION="WRITE")
OPEN(UNIT=7, FILE='mytty', ACTION="WRITE")
END PROGRAM iotest

Fortran preconnects units 0, 5, and 6 to the same TTY device. Normally, you cannot use the OPEN statement to explicitly connect additional units to the TTY device that is connected to units 0, 5, and 6. However, this is possible if you specify the multconnio=tty option. For example, if units 0, 5, and 6 are preconnected to TTY device /dev/tty, you can run the following program if you specify the multconnio=tty option:

PROGRAM iotest
   ! /dev/pts/2 is your current tty, as reported by the 'tty' command.
   ! (This changes every time you login.)
   CALL SETRTEOPTS ('multconnio=tty')
   OPEN (UNIT=3, FILE='/dev/pts/2')
   WRITE (3, *) 'hello'  ! Display 'hello' on your screen
END PROGRAM

namelist={new | old}

Determines whether the program uses the XL Fortran new or old NAMELIST format for input and output. The Fortran 90 and Fortran 95 standards require the new format.

Note: You may need the old setting to read existing data files that contain NAMELIST output.However, use the standard-compilant new format in writing any new data files.

With namelist=old, the nonstandard NAMELIST format is not considered an error by the langlvl=90std, langlvl=95std, or langlvl=2003std setting.

Related information: For more information about NAMELIST I/O, see Namelist formatting in the XL Fortran Language Reference.

naninfoutput={2003std | old | default}

Controls whether the display of IEEE exceptional values conform to the Fortran 2003 standard or revert to the old XL Fortran behavior. This runtime option allows object files created with different compilation commands to output all IEEE exceptional values based on the old behavior, or the Fortran 2003 standard. The suboptions are:

default

Exceptional values output depends on how the program is compiled.

old

Exceptional values output conforms to the old XL Fortran behavior.

2003std

Exceptional values output conforms to the Fortran 2003 standard.

nlwidth=record_width

By default, a NAMELIST write statement produces a single output record long enough to contain all of the written NAMELIST items. To restrict NAMELIST output records to a given width, use the nlwidth runtime option.

Note: The RECL= specifier for sequential files has largely made this option obsolete, because programs attempt to fit NAMELIST output within the specified record length. You can still use nlwidth in conjunction with RECL= as long as the nlwidth width does not exceed the stated record length for the file.

random={generator1 | generator2}

Specifies the generator to be used by RANDOM_NUMBER if RANDOM_SEED has not yet been called with the GENERATOR argument. The value generator1 (the default) corresponds to GENERATOR=1, and generator2 corresponds to GENERATOR=2. If you call RANDOM_SEED with the GENERATOR argument, it overrides the random option from that point onward in the program. Changing the random option by calling SETRTEOPTS after calling RANDOM_SEED with the GENERATOR option has no effect.

scratch_vars={yes | no}

To give a specific name to a scratch file, set the scratch_vars runtime option to yes, and set the environment variable XLFSCRATCH_unit to the name of the file you want to be associated with the specified unit number. See Naming scratch files for examples.

ufmt_littleendian={units_list}

Specifies unit numbers of unformatted data files on which little-endian I/O is to be performed. The little-endian format data in the specified unformatted files is converted, on-the-fly, during the I/O operation to and from the big-endian format used on machines where XL Fortran applications are running.

This runtime option does not work with internal files; internal files are always FORMATTED. Units specified must be connected by an explicit or implicit OPEN for the UNFORMATTED form of I/O.

The syntax for this option is as follows:

ufmt_littleendian=units_list

where:

units_list = units | units_list, units

units = unit | unit- | -unit | unit1-unit2

The unit number must be an integer, whose value is in the range 1 through 2 147 483 647.

unit

Specifies the number of the logical unit.

unit-

Specifies the range of units, starting from unit number unit to the highest possible unit number

-unit

Specifies the range of units, starting from unit number 1 to unit number unit.

unit1-unit2

Specifies the range of units, starting from unit number unit1 to unit number unit2.

Note:

1. The byte order of data of type CHARACTER is not swapped.
2. The compiler assumes that the internal representation of values of type REAL*4 or REAL*8 is IEEE floating-point format compliant. I/O may not work properly with an internal representation that is different.
3. The internal representation of values of type REAL*16 is inconsistent among different vendors. The compiler treats the internal representation of values of type REAL*16 to be the same as XL Fortran's. I/O may not work properly with an internal representation that is different.
4. Conversion of derived type data is not supported. The alignment of derived types is inconsistent among different vendors.
5. Discrepancies in implementations from different vendors may cause problems in exchanging the little-endian unformatted data files between XL Fortran applications running on Blue Gene®/Q and Fortran applications running on little-endian systems. XL Fortran provides a number of options that help users port their programs to XL Fortran. If there are problems exchanging little-endian data files, check these options to see if they can help with the problem.

unit_vars={yes | no}

To give a specific name to an implicitly connected file or to a file opened with no FILE= specifier, you can set the runtime option unit_vars=yes and set one or more environment variables with names of the form XLFUNIT_unit to file names. See Naming files that are connected with no explicit name for examples.

uwidth={32 | 64}

To specify the width of record length fields in unformatted sequential files, specify the value in bits. When the record length of an unformatted sequential file is greater than (2**31 - 1) bytes minus 8 bytes (for the record terminators surrounding the data), you need to set the runtime option uwidth=64 to extend the record length fields to 64 bits. This allows the record length to be up to (2**63 - 1) minus 16 bytes (for the record terminators surrounding the data). The runtime option uwidth is only valid for 64-bit mode applications.

xrf_messages={yes | no}

To prevent programs from displaying runtime messages for error conditions during I/O operations, RANDOM_SEED calls, and ALLOCATE or DEALLOCATE statements, set the xrf_messages runtime option to no. Otherwise, runtime messages for conversion errors and other problems are sent to the standard error stream.

# Basic format
  XLFRTEOPTS=cnverr=yes:xrf_messages=no
  export XLFRTEOPTS

# With imbedded blanks
  XLFRTEOPTS="xrf_messages = NO : cnverr = YES"
  export XLFRTEOPTS

  CALL setrteopts('xrf_messages=NO:cnverr=yes')
! Name is in lowercase in case -U (mixed) option is used.