When you specify fixed-length records, all records in the file contain the same number of bytes. When you open a file that is to contain fixed-length records, you must specify the record size by using the RECL specifier. A sequentially organized file opened for direct access must contain fixed-length records, to allow the record position in the file to be computed correctly.

For relative files, the layout and overhead of fixed-length records depends on whether the program accessing the file was compiled with the -vms option or whether the -vms option was omitted:

• For relative files where the -vms option was omitted (the default), each record has no control information.
• For relative files where the -vms option was specified, each record has one byte of control information at the beginning of the record.

Figure 7-1 shows the record layout of fixed-length records.

Figure 7-1 Fixed-Length Records

For More Information:

On the default value and size limit for fixed-length records, see the RECL specifier for the OPEN statement in the DIGITAL Fortran Language Reference Manual.

7.8.2 Variable-Length Records

Variable-length records can contain any number of bytes, up to a specified maximum record length, and only apply to sequential files. These records are generally prefixed and suffixed by four bytes of control information containing count fields. The 4-byte integer value stored in each count field indicates the number of data bytes (excluding overhead bytes) in that particular variable-length record.

The record layout of variable-length records appears in Figure 7-2.

Figure 7-2 Variable-Length Records

The count field of a variable-length record is available when you read the record by issuing a READ statement with a Q format descriptor. You can then use the count field information to determine how many bytes should be in an I/O list.

Files written with variable-length records by DIGITAL Fortran 90 programs usually cannot be accessed as text files. Instead, use the Stream_LF record format for text files with records of varying length.

7.8.3 Segmented Records

A segmented record is a single logical record consisting of one or more variable-length, unformatted records in a sequentially organized disk file. Unformatted data written to sequentially organized files using sequential access is stored as segmented records by default.

Segmented records are useful when you want to write exceptionally long records but cannot or do not wish to define one long variable-length record, perhaps because virtual memory limitations can prevent program execution. By using smaller, segmented records, you reduce the chance of problems caused by virtual memory limitations on systems on which the program may execute.

For disk files, the segmented record is a single logical record that consists of one or more segments. Each segment is a physical record. A segmented (logical) record can exceed the absolute maximum record length (2.14 billion bytes), but each segment (physical record) individually cannot exceed the maximum record length.

To access an unformatted sequential file that contains segmented records, specify FORM='UNFORMATTED' and RECORDTYPE='SEGMENTED' when you open the file. Otherwise, the file may be processed erroneously.

As shown in Figure 7-3, the layout of segmented records consists of four bytes of control information followed by the user data.

Figure 7-3 Segmented Records

The control information consists of a 2-byte integer record size count (includes the two bytes used by the segment identifier), followed by a 2-byte integer segment identifier that identifies this segment as one of the following:

Identifier Value	Segment Identified
0	One of the segments between the first and last segments.
1	First segment.
2	Last segment.
3	Only segment.

If the specified record length is an odd number, the user data will be padded with a single blank (one byte), but this extra byte is not added to the 2-byte integer record size count.

7.8.4 Stream File Data

A Stream file is not grouped into records and contains no control information. Stream files are used with CARRIAGECONTROL='NONE' and contain character or binary data that is read or written only to the extent of the variables specified on the input or output statement.

The layout of a Stream file appears in Figure 7-4.

Figure 7-4 Stream File

A Stream_CR or Stream_LF record is a variable-length record whose length is indicated by explicit record terminators embedded in the data, not by a count. These terminators are automatically added when you write records to a stream-type file and are removed when you read records.

Each variety uses a different 1-byte record terminator:

• Stream_CR files use only a carriage-return as the terminator, so Stream_CR files must not contain embedded carriage-return characters.
• Stream_LF files use only a line-feed (new line) as the terminator, so Stream_LF files must not contain embedded line-feed (new line) characters. This is the usual operating system text file record type.

The layout of Stream_CR and Stream_LF records appears in Figure 7-5.

Figure 7-5 Stream_CR and Stream_LF Records

This chapter contains information on the following topics:

• Default error processing, the format of run-time errors, values returned to the shell, and how to force a core dump ( Section 8.1)
• Handling run-time errors within your program, including using the END, EOR, and ERR I/O statement branch specifiers, the IOSTAT specifier, and 3f interface library routines ( Section 8.2)
• The signal handling facility on DIGITAL UNIX systems ( Section 8.3)
• DIGITAL Fortran 90 run-time errors, including a list of error numbers, severity level, condition symbols, and descriptions ( Section 8.4)

During execution, your program may encounter errors or exception conditions. These conditions can result from any of the following:

• Errors that occur during I/O operations
• Invalid input data
• Argument errors in calls to the mathematical library
• Arithmetic errors
• Other system-detected errors

The DIGITAL Fortran 90 Run-Time Library (RTL) generates appropriate messages and takes action to recover from errors whenever possible.

8.1 DIGITAL Fortran 90 Run-Time Library Default Error Processing

The DIGITAL Fortran 90 RTL processes a number of errors that may occur during program execution. A default action is defined for each error recognized by the DIGITAL Fortran 90 RTL. The default actions described throughout this chapter occur unless overridden by explicit error-processing methods.

The way in which the DIGITAL Fortran 90 RTL actually processes errors depends upon the following factors:

• The severity of the error. For instance, the program usually continues executing when an error message with a severity level of warning or info (informational) is detected.
• For certain errors associated with I/O statements, whether or not an I/O error-handling specifier was specified.
• For certain errors, whether or not the default action of an associated signal was changed.
• For certain errors related to arithmetic operations (including floating-point exceptions), compilation options can determine whether the error is reported and the severity of the reported error.

How arithmetic exception conditions are reported and handled depends on the cause of the exception and how the program was compiled. Unless the program was compiled to handle exceptions, the exception might not be reported until after the instruction that caused the exception condition. The following f90 command options are related to handling errors and exceptions:

• The -check bounds , -check overflow , and -check underflow options generate extra code to catch certain conditions. For example, the -check overflow option generates extra code to catch integer overflow conditions.
• The -check noformat , -check nooutput_conversion , and -check nopower options reduce the severity level of the associated run-time error to allow program continuation.
• The -fpen options and the -check underflow option control the handling and reporting of floating-point arithmetic exceptions at run-time.
• The -synchronous_exceptions option (and certain -fpen option) influence the reporting of floating-point arithmetic exceptions at run-time.
• The -warn xxxx -u , -nowarn -w , and -w1 options control compile-time warning messages, which in some circumstances can help determine the cause of a run-time error.

For More Information:

• On the f90 command -fpen options and for_get_fpe routine that control how floating-point exceptional conditions are handled at run-time, see Section 3.35.
• On the -check bounds option, see Section 3.16.
• On the -check noformat option, see Section 3.17.
• On the -check nooutput_conversion option, see Section 3.18.
• On the -check overflow option, see Section 3.21.
• On the -check nopower option, see Section 3.19.
• On the -check underflow option, see Section 3.22.
• On the f90 options that control warning messages, see Section 3.83.
• On IEEE floating-point data types and exceptional values, see Section 9.4.
• On f90 command options and their categories, see Table 3-1.
• On DIGITAL Fortran 90 intrinsic data types and their ranges, see Chapter 9.

When errors occur during program execution (run time) of a scalar (nonparallel) program, the DIGITAL Fortran 90 RTL issues diagnostic messages. These run-time messages have the following format:

forrtl: severity (nnn): message-text

Run-time messages provide the following information:

Contents	Information Given
forrtl	Identifies the source as the DIGITAL Fortran 90 RTL.
severity	The severity levels are: severe , error , warning , or info (abbreviation of information) (see Table 8-1).
nnn	This is the message number, also the IOSTAT value for I/O statements.
message_text	Explains the event that caused the message.

Table 8-1 explains the severity levels of run-time messages, in the order of greatest to least severity.

Table 8-1 Severity Levels of Run-Time Messages

Severity	Description
severe	Must be corrected. The program's execution is terminated when the error is encountered, unless the program's I/O statements use the END, EOR, or ERR branch specifiers to transfer control, perhaps to a routine that uses the IOSTAT specifier (see Section 8.2.1 and Section 8.2.2).
error	Should be corrected. The program might continue execution, but the output from this execution may be incorrect.
warning	Should be investigated. The program continues execution, but output from this execution may be incorrect.
info	For informational purposes only; the program continues.

If you have installed the Parallel Software Environment and compiled a program for parallel execution, additional messages specific to parallel HPF execution may appear. These messages are described in the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

8.1.2 Message Catalog Location

The DIGITAL Fortran 90 RTL uses a message catalog file to store the text associated with each run-time message. When a run-time error occurs, the DIGITAL Fortran 90 RTL uses the environment variable NLSPATH to locate the message catalog file, from which it obtains the text of the appropriate message. If the file is not found at the position indicated by NLSPATH, the RTL searches for the message catalog at the following location:

/usr/lib/nls/msg/en_us.iso8859-1/for_msg.cat

Before executing a DIGITAL Fortran 90 program on a system where DIGITAL Fortran 90 is not installed, you need to install the appropriate DIGITAL Fortran 90 run-time subset. For instructions on installing DIGITAL Fortran 90 run-time support, see the DIGITAL Fortran Installation Guide for DIGITAL UNIX Systems.

When a run-time error occurs on a system where the message file is not found, the following messages may appear:

forrtl: info: Fortran error message number is nnn. forrtl: warning: Could not open message catalog: for_msg.cat. forrtl: info: Check environment variable NLSPATH and protection of usr/lib/nls/msg/en_US.ISO8859-1/for_msg.cat

The DIGITAL Fortran 90 RTL returns an error number (displayed after the severity level) that the calling program can use with an IOSTAT variable to handle various I/O conditions, as described in Section 8.2.2.

For more information on NLSPATH, refer to environ(5).

8.1.3 Values Returned to the Shell at Program Termination

A DIGITAL Fortran 90 program can terminate in one of several ways:

• The program runs to normal completion. A value of zero is returned to the shell.
• The program stops with a STOP or a PAUSE statement. A value of zero is returned to the shell.
• The program stops because of a signal that is caught but does not allow the program to continue. A value of 1 is returned to the shell.
• The program stops because of a severe run-time error. The error number for that run-time error is returned to the shell. Error numbers are listed in Table 8-2.
• The program stops with a CALL EXIT statement. The value passed to EXIT is returned to the shell.

You can force a core dump for severe errors that do not usually cause a core file to be created. Before running the program, set the decfort_dump_flag environment variable to Y or y to cause severe errors to create a core file. For instance, the following C shell command sets the decfort_dump_flag environment variable:

% setenv decfort_dump_flag y

The core file is written to the current directory and can be examined using a debugger.

For More Information:

• On the shell commands you can use to set or unset environment variables, see Appendix B.
• On core files, see core(5).
• On language syntax, see the DIGITAL Fortran Language Reference Manual.
• On file operations, see Section 7.5.
• On record operations, see Section 7.6.

Whenever possible, the DIGITAL Fortran 90 RTL does certain error handling, such as generating appropriate messages and taking necessary action to recover from errors. You can explicitly supplement or override default actions by using the following methods:

• To transfer control to error-handling code within the program, use the ERR, EOR, and END branch specifiers in I/O statements ( Section 8.2.1)
• To identify Fortran-specific I/O errors based on the value of DIGITAL Fortran 90 RTL error codes, use the I/O status specifier (IOSTAT) in I/O statements (or call the ERRSNS subroutine) ( Section 8.2.2)
• Obtain system-level error codes by using the appropriate 3f library routines ( Section 8.2.3)
• For certain error conditions, use the signal handling facility to change the default action to be taken ( Section 8.3)

These error-processing methods are complementary; you can use any or all of them within the same program to obtain DIGITAL Fortran 90 run-time and DIGITAL UNIX system error codes.

If your program generates an exception, use the -synchronous_exceptions option and recompile and relink your application (see Section 4.9).

8.2.1 Using the END, EOR, and ERR Branch Specifiers

When a severe error occurs during DIGITAL Fortran 90 program execution, the default action is to display an error message and terminate the program. To override this default action, there are three branch specifiers you can use in I/O statements to transfer control to a specified point in the program:

• The END branch specifier handles an end-of-file condition.
• The EOR branch specifier handles an end-of-record condition for nonadvancing reads.
• The ERR branch specifier handles all error conditions.

If you use the END, EOR, or ERR branch specifiers, no error message is displayed and execution continues at the designated statement, usually an error-handling routine.

You might encounter an unexpected error that the error-handling routine cannot handle. In this case, do one of the following:

• Modify the error-handling routine to display the error message number
• Remove the END, EOR, or ERR branch specifiers from the I/O statement that causes the error

After you modify the source code, compile, link, and run the program to display the error message. For example:

READ (8,50,ERR=400)

If any severe error occurs during execution of this statement, the DIGITAL Fortran 90 RTL transfers control to the statement at label 400. Similarly, you can use the END specifier to handle an end-of-file condition that might otherwise be treated as an error. For example:

READ (12,70,END=550)

When using nonadvancing I/O, use the EOR specifier to handle the end-of-record condition. For example:

150 FORMAT (F10.2, F10.2, I6) READ (UNIT=20, FMT=150, SIZE=X, ADVANCE='NO', EOR=700) A, F, I

You can also use ERR as a specifier in an OPEN, CLOSE, or INQUIRE statement. For example:

OPEN (UNIT=10, FILE='FILNAM', STATUS='OLD', ERR=999)

If an error is detected during execution of this OPEN statement, control transfers to the statement at label 999.

For More Information:

• On advancing and nonadvancing record I/O, see Section 7.6.4.
• On language syntax, see the DIGITAL Fortran Language Reference Manual.
• On file operations, see Section 7.5.
• On record operations, see Section 7.6.

You can use the IOSTAT specifier to continue program execution after an I/O error and to return information about I/O operations, whether the program is executing as a scalar or parallel program (I/O is done in a scalar fashion). As described in Table 8-2, certain errors are not returned in IOSTAT.

Although the IOSTAT specifier transfers control, it can only return information returned by the DIGITAL Fortran 90 RTL.

The IOSTAT specifier can supplement or replace the END, EOR, and ERR branch transfers. Execution of an I/O statement containing the IOSTAT specifier suppresses the display of an error message and defines the specified integer variable, array element, or scalar field reference as one of the following:

• A value of --2 if an end-of-record condition occurs with nonadvancing reads.
• A value of --1 if an end-of-file condition occurs.
• A value of 0 for normal completion (not an error condition, end-of-file, or end-of-record condition).
• A positive integer value if an error condition occurs. (This value is one of the Fortran-specific IOSTAT numbers listed in Table 8-2.)

Following the execution of the I/O statement and assignment of an IOSTAT value, control transfers to the END, EOR, or ERR statement label, if any. If there is no control transfer, normal execution continues.

You can include /usr/include/foriosdef.f in your program to obtain symbolic definitions for the values of IOSTAT.

Example 8-1 uses the IOSTAT specifier and the foriosdef.f file to handle an OPEN statement error (in the FILE specifier).

Example 8-1 Error Handling OPEN Statement File Name

CHARACTER(LEN=40) :: FILNM INCLUDE '/usr/include/foriosdef.f' DO I=1,4 FILNM = '' WRITE (6,*) 'Type file name ' READ (5,*) FILNM OPEN (UNIT=1, FILE=FILNM, STATUS='OLD', IOSTAT=IERR, ERR=100) WRITE (6,*) 'Opening file: ', FILNM ! (process the input file) CLOSE (UNIT=1) STOP 100 IF (IERR .EQ. FOR$IOS_FILNOTFOU) THEN WRITE (6,*) 'File: ', FILNM, ' does not exist ' ELSE IF (IERR .EQ. FOR$IOS_FILNAMSPE) THEN WRITE (6,*) 'File: ', FILNM, ' was bad, enter new file name' ELSE PRINT *, 'Unrecoverable error, code =', IERR STOP END IF END DO WRITE (6,*) 'File not found. Type ls to find file and run again' END PROGRAM

Another way to obtain information about an error is the ERRSNS subroutine (a DIGITAL extension), which allows you to obtain the last I/O system error code associated with a DIGITAL Fortran 90 RTL error (see the DIGITAL Fortran Language Reference Manual).