When you open a disk file, you can use the OPEN statement's POSITION specifier to request one of the following initial record positions within the file:

• The initial position before the first record (POSITION='REWIND'). A sequential access READ or WRITE statement will read or write the first record in the file.
• A point beyond the last record in the file (POSITION='APPEND'), just before the end-of-file record, if one exists. For a new file, this is the initial position before the first record (same as 'REWIND'). You might specify 'APPEND' before you write records to an existing sequential file using sequential access.
• The current position (ASIS). This is usually used only to maintain the current record position when reconnecting a file. The second OPEN specifies the same unit number and specifies the same file name (or omits it), which leaves the file open, retaining the current record position.
  However, if a second OPEN statement specifies a different file name for the same unit number, the file will be closed and then opened, causing a loss of current record position.

The following I/O statements allow you to change the current record position:

• REWIND sets the record position to the initial position before the first record. A sequential access READ or WRITE statement would read or write the first record in the file.
• BACKSPACE sets the record position to the previous record in a file. Using sequential access, if you wrote record 5, issued a BACKSPACE to that unit, and then read from that unit, you would read record 5.
• ENDFILE writes an end-of-file marker. This is typically done after writing records using sequential access just before you close the file.

Unless you use nonadvancing I/O (see Section 6.8.5), reading and writing records usually advances the current record position by one record. As discussed in Section 6.8.6, more than one record might be transferred using a single record I/O statement.

6.8.5 Advancing and Nonadvancing Record I/O

After you open a file, if you omit the ADVANCE specifier (or specify ADVANCE='YES') in READ and WRITE statements, advancing I/O (normal FORTRAN-77 I/O) will be used for record access. When using advancing I/O:

• Record I/O statements transfer one entire record (or multiple records).
• Record I/O statements advance the current record position to a position before the next record.

You can request nonadvancing I/O for the file by specifying the ADVANCE= 'NO' specifier in a READ and WRITE statement. You can use nonadvancing I/O only for sequential access to external files using formatted I/O (not list-directed or namelist).

When you use nonadvancing I/O, the current record position does not change, and part of the record might be transferred, unlike advancing I/O where one entire record or records are always transferred.

You can alternate between advancing and nonadvancing I/O by specifying different values for the ADVANCE specifier ('YES' and 'NO') in the READ and WRITE record I/O statements.

When reading records with either advancing or nonadvancing I/O, you can use the END branch specifier to branch to a specified label when the end of the file is read.

Because nonadvancing I/O might not read an entire record, it also supports an EOR branch specifier to branch to a specified label when the end of the record is read. If you omit the EOR and the IOSTAT specifiers when using nonadvancing I/O, an error results when the end-of-record is read.

When using nonadvancing input, you can use the SIZE specifier to return the number of characters read. For example, in the following READ statement, SIZE=X (where variable X is an integer) returns the number of characters read in X and an end-of-record condition causes a branch to label 700:

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

6.8.6 Record Transfer

I/O statements transfer all data as records. The amount of data that a record can contain depends on the following circumstances:

• With formatted I/O (except for fixed-length records), the number of items in the I/O statement and its associated format specifier jointly determine the amount of data to be transferred.
• With namelist and list-directed output, the items listed in the NAMELIST statement or I/O statement list (in conjunction with the NAMELIST or list-directed formatting rules) determine the amount of data to be transferred.
• With unformatted I/O (except for fixed-length records), the I/O statement alone specifies the amount of data to be transferred.
• When you specify fixed-length records (RECORDTYPE='FIXED'), all records are the same size. If the size of an I/O record being written is less than the record length (RECL), extra bytes are added (padding).

Typically, the data transferred by an I/O statement is read from or written to a single record. It is possible, however, for a single I/O statement to transfer data from or to more than one record, depending on the form of I/O used.

Input Record Transfer

When using advancing I/O, if an input statement specifies fewer data fields (less data) than the record contains, the remaining fields are ignored.

If an input statement specifies more data fields than the record contains, one of the following occurs:

• For formatted input using advancing I/O, if the file was opened with PAD='YES', additional fields are read as spaces. If the file is opened with PAD='NO', an error occurs (the input statement should not specify more data fields than the record contains).
  For formatted input using nonadvancing I/O (ADVANCE='NO' specifier), an end-of-record (EOR) condition is returned. If the file was opened with PAD='YES', additional fields are read as spaces.
• For list-directed input, another record is read.
• For namelist input, another record is read.
• For unformatted input, an error occurs.

Output Record Transfer

If an output statement specifies fewer data fields than the record contains (less data than required to fill a record), the following occurs:

• With fixed-length records (RECORDTYPE='FIXED'), all records are the same size. If the size of an I/O record being written is less than the record length (RECL), extra bytes are added (padding) in the form of spaces (for a formatted record) or zeros (for an unformatted record).
• With other record types, the fields present are written and those omitted are not written (might result in a short record).

If the output statement specifies more data than the record can contain, an error occurs, as follows:

• With formatted or unformatted output using fixed-length records
  If the items in the output statement and its associated format specifier result in a number of bytes that exceed the maximum record length (RECL), an error occurs.
• With formatted or unformatted output not using fixed-length records
  If the items in the output statement and its associated format specifier result in a number of bytes that exceed the maximum record length (RECL), an error (OUTSTAOVE) occurs.
• For list-directed output and namelist output, if the data specified exceeds the maximum record length (RECL), another record is written.

For More Information:

• On Compaq Fortran I/O statements, see Table 6-1.
• On record I/O specifiers, see Section 6.8.1.
• On statement syntax and specifier values, see the Compaq Fortran Language Reference Manual.
• On improving Compaq Fortran I/O performance, see Section 5.5.
• On user-supplied OPEN Procedures (the USEROPEN specifier), see Chapter 11.

When a Compaq Fortran output statement is executed, the record data may not be written immediately to the file or device.

To enhance performance, Compaq Fortran uses the OpenVMS RMS "write-behind" and "multibuffering" features, which group records together in a memory buffer and delays the actual device write operation until the buffers are full or the file is closed. In most cases, this is desirable (for instance, to minimize disk I/O).

For those applications that depend on data being written to the physical device immediately, "write-behind" and "multibuffering" can result in incomplete data in the case of a power loss or other severe problem that prevents the data being written.

For applications that require guaranteed file consistency for disaster recovery or transactional integrity, the RMS Journaling product is recommended. RMS Journaling provides three types of journaling:

• After-Image journaling, in which journaled transactions allow you to redo record operations.
• Before-Image journaling, in which journaled transactions allow you to undo record operations.
• Recovery Unit (RU) for transactional integrity (multiple operations treated as one transaction)

Both After-Image and Before-Image journaling can be used without modifying the application.

Other applications that do not need the degree of safety provided by RMS journaling can use RMS features to cause data to be written to the file or device more frequently. The simplest method is to use the SYS$FLUSH system service to cause RMS to perform all pending writes immediately to disk. This also has the effect of updating the file's end-of-file pointer so that all of the data written up to that point becomes accessible. An application might choose to call SYS$FLUSH at an interval of every hundred records, for example. The more often SYS$FLUSH is called, the more often the file is updated, but the more performance is affected.

When calling SYS$FLUSH, the RMS Record Access Block (RAB) for the file must be passed as an argument. For files opened by Compaq Fortran (or Compaq Fortran 77), the FOR$RAB intrinsic function may be used to obtain the RAB. For example:

INTEGER (KIND=4) :: FOR$RAB, IUNIT . . . IREC_COUNT = 0 DO WHILE (....) . . . WRITE (IUNIT) DATA IREC_COUNT = IREC_COUNT + 1 IF (IREC_COUNT .EQ. 100) THEN CALL SYS$FLUSH(%VAL(FOR$RAB(IUNIT))) IREC_COUNT = 0 END IF END DO

For More Information:

• On RMS Journaling, see the RMS Journaling for OpenVMS Manual.
• On SYS$FLUSH and other RMS features, see Chapter 11, the Guide to OpenVMS File Applications, and the OpenVMS Record Management Services Reference Manual.
• On using the FOR$RAB intrinsic function, see Section 11.1.3.
• On improving Compaq Fortran I/O performance, see Section 5.5.

During execution, your program may encounter errors or exception conditions. These conditions can result from errors that occur during I/O operations, from invalid input data, from argument errors in calls to the mathematical library, from arithmetic errors, or from system-detected errors.

The Compaq Fortran Run-Time Library (RTL) provides default processing for error conditions, generates appropriate messages, and takes action to recover from errors whenever possible. However, 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 error (ERR), end-of-record (EOR), and end-of-file (END) branch specifiers in I/O statements.
• To identify Fortran-specific errors based on the value of IOSTAT, use the I/O status specifier (IOSTAT) in I/O statements.
• To tailor error processing to the special requirements of your applications, use the OpenVMS condition-handling facility (including user-written condition handlers). (For information on user-written condition handlers, see Chapter 14.)

This chapter describes how the Compaq Fortran RTL processes errors. It also provides information about using I/O specifiers for explicit error processing and control, and shows how these methods affect the default error processing of the Compaq Fortran RTL.

7.1 Compaq Fortran RTL Default Error Processing

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

Unless you specify the /SYNCHRONOUS_EXCEPTIONS qualifier when you compile the program, error reporting of exceptions may be inexact; the exception may not be reported until a few instructions after the one that caused the exception. This makes continuation from an exception trap not feasible.

The way in which the Compaq Fortran RTL actually processes errors depends upon several factors:

• The severity of the error.
• Whether an I/O error-handling specifier or a condition handler was used.

The following FORTRAN command qualifiers are related to handling errors and exceptions:

• The /CHECK=BOUNDS, /CHECK=OVERFLOW, and /CHECK=UNDERFLOW qualifiers generate extra code to catch certain conditions. For example, the /CHECK=OVERFLOW qualifier generates extra code to catch integer overflow conditions.
• The /CHECK=NOFORMAT, /CHECK=NOOUTPUT_CONVERSION, and /CHECK=NOPOWER qualifiers reduce the severity level of the associated run-time error to allow program continuation.
• The /CHECK=NOFP_EXCEPTIONS qualifier and the /CHECK=UNDERFLOW qualifier control the handling and reporting of floating-point arithmetic exceptions at run-time.
• The /SYNCHRONOUS_EXCEPTIONS qualifier (and certain /IEEE_MODE keywords) influence the reporting of floating-point arithmetic exceptions at run-time.
• The /WARNINGS qualifier controls compile-time warning messages, which in some circumstances can help determine the cause of a run-time error.

For More Information:

• On the FORTRAN command qualifier /CHECK, see Section 2.3.9.
• On other /CHECK qualifier keywords, see Section 2.3.9.
• On the FORTRAN qualifiers that control compile-time warning messages, see Section 2.3.48.
• On IEEE floating-point data types and exceptional values, see Section 2.3.21.
• On FORTRAN command qualifiers and their categories, see Table 2-1.
• On Compaq Fortran intrinsic data types and their ranges, see Chapter 8.

The general form of Compaq Fortran run-time messages follows:

%FOR-severity-mnemonic, message-text

The contents of the fields in run-time messages follow:

%	The percent sign identifies the line as a message.
FOR	The facility code for Compaq Fortran 77 and Compaq Fortran.
severity	A single character that determines message severity. The types of run-time messages are: Fatal (F), Error (E), and Informational (I).
mnemonic	A 6- to 9-character name that uniquely identifies that message.
message_text	Explains the event or reason why the message appears.

For example, the following message has a severity of Fatal, a mnemonic of ADJARRDIM, and message text of "adjustable array dimension error":

%FOR-F-ADJARRDIM, adjustable array dimension error

7.1.2 Run-Time Message Severity Levels

In order of greatest to least severity, the classes of run-time diagnostic messages are as follows:

Severity Code	Description
F	Fatal (severe) This must be corrected. The program cannot complete execution and is terminated when the error is encountered, unless for I/O statements the program uses the END, EOR, or ERR branch specifiers to transfer control, perhaps to a routine that uses the IOSTAT specifier (see Section 7.2.1 and Section 7.2.2). You can also continue from certain fatal-level messages by using a condition handler.
E	Error This should be corrected. The program may continue execution, but the output from this execution may be incorrect.
I	Informational This should be investigated. The program continues executing, but output from this execution may be incorrect.

The severity depends on the source of the message. In some cases, certain FORTRAN command qualifiers can change the severity level or control whether messages are displayed (such as the /CHECK and /IEEE_MODE keywords).

7.2 Handling Errors

Whenever possible, the Compaq Fortran RTL does certain error handling, such as generating appropriate messages and taking necessary action to recover from errors.

When no recovery method is specified for a statement and a fatal-level error occurs, a message appears and the program terminates. To prevent program termination, you must include either an appropriate I/O error-handling specifier (see Section 7.2) or a condition handler that performs an unwind (see Chapter 14). The I/O error-handling specifier or condition handler might also handle error-level messages.

You can explicitly supplement or override default actions by using the following Compaq Fortran methods:

• To transfer control to error-handling code within the program, use the ERR, EOR, and END branch specifiers in I/O statements (see Section 7.2.1).
• The ERR, EOR, and END branch specifiers transfer control to a part of your program designed to handle specific errors. The error-handling code associated with the ERR branch usually handles multiple types of errors.
  To identify Fortran-specific I/O errors based on the value of Compaq Fortran RTL error codes, use the I/O status specifier (IOSTAT) in I/O statements (or call the ERRSNS subroutine) (see Section 7.2.2).

When a fatal error occurs during program execution, the Compaq Fortran RTL default action is to print an error message and terminate the program. You can establish an OpenVMS condition handler that performs an unwind for certain fatal errors.

These error-processing methods are complementary; you can use all of them within the same program. However, before attempting to write a condition handler, you should be familiar with the OpenVMS condition-handling facility (CHF) and with the condition-handling description in Chapter 14.

Using the END, EOR, or ERR branch specifiers in I/O statements prevent signaling (display) of errors, including secondary return values for file system errors, such as RMS errors. Using these specifiers prevent the transfer of control to a condition handler.

There are certain file system errors where no handler (condition handler or vector exception handler) exists. To obtain the secondary file system errors in these cases, remove the END, EOR, and ERR specifiers, recompile, relink, and rerun the program.

You do not need to remove the ERR or IOSTAT specifiers if you use a vectored exception handler (established using SYS$SETEXV), which will receive control instead of the ERR and IOSTAT specifiers. The ERRSNS subroutine allows you to obtain secondary return values for file system errors (see the Compaq Fortran Language Reference Manual).

7.2.1 Using the ERR, EOR, and END Branch Specifiers

When a fatal error occurs during program execution, the Compaq Fortran RTL default action is to print an error message and terminate the program.

You can use the ERR, EOR, and END specifiers in I/O statements to override this default by transferring control to a specified point in 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
• Handle the error by using a vectored exception handler (established using SYS$SETEXV)
• Establish a condition handler that performs an unwind (for certain severe errors).

For example, consider the following WRITE statement:

WRITE (8,50,ERR=400)

If an error occurs during execution of this statement, the Compaq Fortran RTL transfers control to the statement at label 400. You can also 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 specify ERR as a keyword to such I/O statements as 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 statement 999.

For More Information:

• On the IOSTAT specifier, see Section 7.2.2).
• On detailed descriptions of errors processed by the Compaq Fortran RTL, see Table B-1 or online FORTRAN HELP.
• On user-written condition handlers, see Chapter 14.

You can use the IOSTAT specifier to continue program execution after an I/O error and to return information about I/O operations. It can supplement or replace the END and ERR transfers. Execution of an I/O statement containing the IOSTAT specifier suppresses printing of an error message and causes the specified integer variable, array element, or scalar field reference to be defined as one of the following:

• A value of --2 if an end-of-record condition occurs (nonadvancing reads).
• A value of --1 if an end-of-file condition occurs.
• A value of 0 if neither an error condition nor an end-of-file condition occurs.
• A positive integer value if an error condition occurs (this value is one of the Fortran-specific IOSTAT numbers listed in Table 7-1.)

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

Your program can include the $FORIOSDEF library module from the FORSYSDEF library (automatically searched during compilation) to obtain symbolic definitions for the values of IOSTAT.

The values of the IOSTAT symbols from the $FORIOSDEF library module are not the same as the values of the Fortran condition symbols from the $FORDEF library module.

The symbolic names in the $FORIOSDEF library module have a form similar to the Fortran condition symbols:

Fortran Condition Symbol ($FORDEF)	IOSTAT Symbolic Name ($FORIOSDEF)
FOR$_mnemonic	FOR$IOS_mnemonic

Example 7-1 uses the ERR and IOSTAT specifiers to handle an OPEN statement error (in the FILE specifier). Condition symbols are included from the $FORIOSDEF library module (in FORSYSDEF).

Example 7-1 Handling OPEN Statement File Name Errors

CHARACTER(LEN=40) :: FILNM ! Typed file specification INCLUDE '($FORIOSDEF)' ! Include condition symbol definitions DO I=1,4 ! Allow four tries 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 records . 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 ! After four attempts or a Ctrl/Z on the READ statement, allow program restart WRITE (6,*) 'File not found. Type DIRECTORY to find file and run again' END PROGRAM

For More Information:

• On user-written condition handlers, see Chapter 14.
• On the END, EOR, or ERR branch specifiers, see Section 7.2.1.
• On detailed descriptions of errors processed by the Compaq Fortran RTL, see Table B-1 or online FORTRAN HELP.
• On the ERRSNS subroutine, see the Compaq Fortran Language Reference Manual.
• On the including library modules from text libraries, see Section 10.7.1.