Format-directed formatting

Format-directed formatting allows you to control editing using edit descriptors in a format specification. Specify a format specification in a FORMAT statement or as the value of a character array or character expression in a data transfer statement. Edit descriptors allow you to control editing in the following ways:

Complex editing

To edit complex values, you must specify complex editing by using a pair of data edit descriptors. A complex value is a pair of separate real components. When specifying complex editing, the first edit descriptor applies to the real part of the number. The second edit descriptor applies to the imaginary part of the number.

You can specify different edit descriptors for a complex editing pair and use one or more control edit descriptors between the edit descriptors in that pair. You must not specify data edit descriptors between the edit descriptors in that pair.

Data edit descriptors

Data edit descriptors allow you to specify editing by data type. You can use them to edit both character and numeric data. The Data Edit Descriptors table contains a complete list of all character, character string and numeric edit descriptors. Numeric data refers to integer, real, and complex values.

Table 21. Data edit descriptors
Forms Use
A
Aw
Edits character values
Bw
Bw.m
Edits binary values
Ew.d
Ew.dEe
Ew.dDe *
Ew.dQe
*
Dw.d
ENw.d
ENw.dEe
ESw.d
ESw.dEe
Qw.d *
Edits real and complex numbers with exponents
Fw.d Edits real and complex numbers without exponents
Gw.d
Gw.dEe
Gw.dDe *
Gw.dQe
*
Edits data fields of any intrinsic type, with the output format adapting to the type of the data and, if the data is of type real, the magnitude of the data
Iw
Iw.m
Edits integer numbers
Lw Edits logical values
Ow
Ow.m
Edits octal values
Q * Returns the count of characters remaining in an input record *
Zw
Zw.m
Edits hexadecimal values

where:

*
specifies an IBM extension.
d
Specifies the number of digits to the right of the decimal point.
e
Specifies the number of digits in the exponent field.
m
Specifies the number of digits to print.
n
Specifies the number of characters in a literal field. Blanks are included in character count.
w
Specifies the width of a field including all blanks as a positive value.

FORTRAN 95 Begins If you specify the B, F, I, O, or Z, edit descriptors on output, the value of w can be zero. FORTRAN 95 Ends

Rules for Data Edit Descriptor and Modifiers

You must not specify kind type parameters.

Edit descriptor modifiers must be unsigned integer literal constants.

IBM Extension

For the w, m, d, and e modifiers, you must enclose a scalar integer expression in angle brackets (< and >). See Variable format expressions for details.

Note:

There are two types of Q data edit descriptor:

extended precision Q
is the Q edit descriptor with theQw.d syntax
character count Q
is the Q edit descriptor with the Q syntax
End of IBM Extension

Rules for numeric edit descriptors on input

Leading blanks are not significant. You can control the interpretation of other blanks using the BLANK= specifier in the OPEN or READ statements and the BN and BZ edit descriptors. A field of all blanks is treated as zero.

Plus signs are optional, though you must not specify plus signs for the B, O, and Z edit descriptors.

In F, E, EN, ES, D, G, and extended precision Q editing, a decimal point appearing in the input field overrides the portion of an edit descriptor that specifies the decimal point location. The field can contain more digits than can be represented internally.

Rules for numeric data edit descriptors on output

Characters are right-justified in the field.

When the number of characters in a field is less than the field width, leading blanks fill the remaining field space.

When the number of characters in a field is greater than the field width, or if an exponent exceeds its specified width, asterisks fill the entire field space.

A minus sign prefixes a negative value. A positive or zero value does not receive a plus sign prefix on output, unless you specify the S, SP, or SS edit descriptors.

Fortran 95

If you specify the -qxlf90 compiler option the E, D, Q(Extended Precision), F, EN, ES and G(General Editing) edit descriptors output a negative value differently depending on the signedzero suboption.

The EN and ES edit descriptors output a minus sign when the value is negative for the signedzero and nosignedzero suboptions.

End of Fortran 95
IBM Extension

XL Fortran indicates, a NaN (not a number) by "NAN", "+NAN", or "-NAN". XL Fortran indicates infinity by "INF", "+INF", or "-INF".

End of IBM Extension

Control edit descriptors

Table 22. Control edit descriptors
Forms Use
/
r /
Specifies the end of data transfer on the current record
: Specifies the end of format control if there are no more items in the input/output list
$ * Suppresses end-of-record in output *
BN Ignores nonleading blanks in numeric input fields
BZ Interprets nonleading blanks in numeric input fields as zeros
kP Specifies a scale factor for real and complex items
S
SS

Specifies that plus signs are not to be written
SP Specifies that plus signs are to be written
Tc Specifies the absolute position in a record from which, or to which, the next character is transferred
TLc Specifies the relative position (backward from the current position in a record) from which, or to which, the next character is transferred
TRc
oX
Specifies the relative position (forward from the current position in a record) from which, or to which, the next character is transferred

where:

*
specifies an IBM extension.
r
is a repeat specifier. It is an unsigned, positive, integer literal constant.
k
specifies the scale factor to be used. It is an optionally signed, integer literal constant.
c
specifies the character position in a record. It is an unsigned, nonzero, integer literal constant.
o
is the relative character position in a record. It is an unsigned, nonzero, integer literal constant.

Rules for Control Edit Descriptors and Modifiers

You must not specify kind type parameters.

IBM Extension

r, k, c, and o can also be expressed as an arithmetic expression enclosed by angle brackets that evaluates into an integer value.

End of IBM Extension

Character string edit descriptors

Character string edit descriptors allow you to edit character data.

Forms Use Page
nHstr Outputs a character string (str) H Editing
'str'
"str"
Outputs a character string (str) Apostrophe/Double quotation mark editing
n
is the number of characters in a literal field. It is an unsigned, positive, integer literal constant. Blanks are included in character count. A kind type parameter cannot be specified.

Apostrophe/Double quotation mark editing

Purpose

The apostrophe/double quotation mark edit descriptor specifies a character literal constant in an output format specification.

Syntax

Rules

The width of the output field is the length of the character literal constant. See Character for additional information on character literal constants.

IBM Extension
Notes:
  1. A backslash is recognized, by default, as an escape sequence, and as a backslash character when the -qnoescape compiler option is specified. See escape sequences for more information.
  2. XL Fortran provides support for multibyte characters within character constants, Hollerith constants, character-string edit descriptors, and comments. This support is provided through the -qmbcs option. Assignment of a constant containing multibyte characters to a variable that is not large enough to hold the entire string may result in truncation within a multibyte character.
  3. Support is also provided for Unicode characters and filenames. If the environment variable LANG is set to UNIVERSAL and the -qmbcs compiler option is specified, the compiler can read and write Unicode characters and filenames.
End of IBM Extension

Examples

      ITIME=8
      WRITE(*,5) ITIME
5     FORMAT('The value is -- ',I2) ! The value is -- 8
      WRITE(*,10) ITIME
10    FORMAT(I2,'o''clock') ! 8o'clock
      WRITE(*,'(I2,7Ho''clock)') ITIME ! 8o'clock
      WRITE(*,15) ITIME
15    FORMAT("The value is -- ",I2) ! The value is -- 8
      WRITE(*,20) ITIME
20    FORMAT(I2,"o'clock") ! 8o'clock
      WRITE(*,'(I2,"o''clock")') ITIME ! 8o'clock 

Interaction of Input/Output lists and format specifications

Beginning format-directed formatting initiates format control. Each action of format control depends on the next edit descriptor in the format specification, and on the next item in the input/output list, if one exists.

If an input/output list specifies at least one item, at least one data edit descriptor must exist in the format specification. Note that an empty format specification (parentheses only) can be used only if there are no items in the input/output list or if each item is a zero-sized array or an implied-DO list with an iteration count of zero. If this is the case and advancing input/output is in effect, one input record is skipped, or one output record containing no characters is written. For nonadvancing input/output, the file position is left unchanged.

A format specification is interpreted from left to right, except when a repeat specification (r) is present. A format item that is preceded by a repeat specification is processed as a list of r format specifications or edit descriptors identical to the format specification or edit descriptor without the repeat specification.

One item specified by the input/output list corresponds to each data edit descriptor. An list item of complex type requires the interpretation of two F, E, EN, ES, D, G, or extended precision Q edit descriptors. No item specified by the input/output list corresponds to a control edit descriptor or character string edit descriptor. Format control communicates information directly with the record.

Format control operates as follows:

  1. If a data edit descriptor is encountered, format control processes an input/output list item, if there is one, or terminates the input/output command if the list is empty. If the list item processed is of type complex, any two edit descriptors are processed.
  2. The colon edit descriptor terminates format control if no more items are in the input/output list. If more items are in the input/output list when the colon is encountered, it is ignored.
  3. If the end of the format specification is reached, format control terminates if the entire input/output list has been processed, or control reverts to the beginning of the format item terminated by the last preceding right parenthesis. The following items apply when the latter occurs:
IBM Extension

During a read operation, any unprocessed characters of the record are skipped whenever the next record is read. A comma can be used as a value separator for noncharacter data in an input record processed under format-directed formatting. The comma will override the format width specifications when the comma appears before the end of the field width. For example, the format (I10,F20.10,I4) will read the following record correctly:

-345, .05E-3, 12
End of IBM Extension

It is important to consider the maximum size record allowed on the input/output medium when defining a Fortran record by a FORMAT statement. For example, if a Fortran record is to be printed, the record should not be longer than the printer's line length.

IBM Extension

Comma-separated Input/Output

When reading floating-point data using format-directed input/output, a comma that appears in the input terminates the field. This can be useful for reading files containing comma-separated values.

For example, the following program reads two reals using the E edit descriptor. It requires that the field width be 16 characters. The program attempts to read the remaining characters in the record as a character string.

> cat read.f
real a,b
character*10 c
open(11, access='sequential', form='formatted')
read(11, '(2e16.10, A)') a,b,c
print *, a
print *, b
print *, c
end

If the floating-point fields are 16 characters wide, as the format specifies, the program executes correctly. (0.4000000000E+02 is 16 characters long.)

> cat fort.11
0.4000000000E+020.3000000000E+02hello
> a.out
 40.00000000
 30.00000000
 hello

But if the floating-point input contains less than 16 characters, errors occur because parts of the next field are read. (0.400000E+02 is 12 characters long.)

> cat fort.11
0.400000E+020.3000000E+02hello
> a.out
1525-097 A READ statement using decimal base input found the invalid digit
'.' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'h' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'e' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'l' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'l' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'o' in the input file.
The program will recover by assuming a zero in its place.
 INF
 0.0000000000E+00

If you use commas to terminate the fields, the floating-point values are read correctly. (0.400000E+02 is 12 characters long, but the fields are separated by commas.)

> cat fort.11
0.400000E+02,0.3000000E+02,hello
> a.out
 40.00000000
 30.00000000
 hello
End of IBM Extension