WRITE

Purpose

The WRITE statement is a data transfer output statement.

Syntax

Read syntax diagramSkip visual syntax diagramWRITE(io_control_list )output_item_list
output_item
is an output list item. An output list specifies the data to be transferred. An output list item can be:
  • A variable name. An array is treated as if all of its elements were specified in the order in which they are arranged in storage.

    A pointer must be associated with a target, and an allocatable object must be allocated. A derived-type object cannot have any ultimate component that is outside the scoping unit of this statement. The evaluation of output_item cannot result in a derived-type object that contains a pointer. The structure components of a structure in a formatted statement are treated as if they appear in the order of the derived-type definition; in an unformatted statement, the structure components are treated as a single value in their internal representation (including padding).

  • An expression
  • An implied-DO list, as described under Implied-DO List

An output_item must not be a procedure pointer.

io_control
is a list that must contain one unit specifier (UNIT=), and can also contain one of each of the other valid specifiers:
[UNIT=] u
is a unit specifier that specifies the unit to be used in the output operation. u is an external unit identifier or internal file identifier.
An external unit identifier refers to an external file. It is one of the following:
  • An integer expression whose value is in the range 1 through 2147483647
  • An asterisk, which identifies external unit 6 and is preconnected to standard output
  • Fortran 2008 beginsA NEWUNIT valueFortran 2008 ends

An internal file identifier refers to an internal file. It is the name of a character variable, which cannot be an array section with a vector subscript.

If the optional characters UNIT= are omitted, u must be the first item in io_control_list. If UNIT= is specified, FMT= must also be specified.

[FMT=] format
is a format specifier that specifies the format to be used in the output operation. format is a format identifier that can be:
  • The statement label of a FORMAT statement. The FORMAT statement must be in the same scoping unit.
  • The name of a scalar INTEGER(4) or INTEGER(8) variable that was assigned the statement label of a FORMAT statement. The FORMAT statement must be in the same scoping unit.

    Fortran 95 does not permit assigning of a statement label.

  • A character constant enclosed in parentheses. Only the format codes listed under FORMAT can be used between the parentheses. Blank characters can precede the left parenthesis or follow the right parenthesis.
  • A character variable that contains character data whose leftmost character positions constitute a valid format. A valid format begins with a left parenthesis and ends with a right parenthesis. Only the format codes described in the FORMAT statement can be used between the parentheses. Blank characters can precede the left parenthesis or follow the right parenthesis. If format is an array element, the format identifier must not exceed the length of the array element.
  • An array of noncharacter intrinsic type. The data must be a valid format identifier as described under character array.
  • Any character expression, except one involving concatenation of an operand that specifies inherited length, unless the operand is the name of a constant.
  • An asterisk, specifying list-directed formatting.
  • A namelist specifier that specifies the name of a namelist list that you have previously defined.

If the optional characters FMT= are omitted, format must be the second item in io_control_list, and the first item must be the unit specifier with UNIT= omitted. NML= and FMT= cannot both be specified in the same output statement.

ASYNCH= char_expr (IBM extension)
is an asynchronous I/O specifier that indicates whether an explicitly connected unit is to be used for asynchronous I/O.

char_expr is a scalar character expression whose value is either YES or NO. YES specifies that asynchronous data transfer statements are permitted for this connection. NO specifies that asynchronous data transfer statements are not permitted for this connection. The value specified will be in the set of transfer methods permitted for the file. If this specifier is omitted, the default value is NO.

Preconnected units are connected with an ASYNCH= value of NO.

The ASYNCH= value of an implicitly connected unit is determined by the first data transfer statement performed on the unit. If the first statement performs an asynchronous data transfer and the file being implicitly connected permits asynchronous data transfers, the ASYNCH= value is YES. Otherwise, the ASYNCH= value is NO.

ASYNCHRONOUS=char_expr (Fortran 2003)
allows execution to continue without waiting for the data transfer to complete. char_expr is a scalar character expression that must evaluate to YES or NO. ASYNCHRONOUS=YES must not appear unless UNIT= specifies a file unit number. If ID= appears, an ASYNCHRONOUS=YES must also appear.

A statement and the I/O operation are synchronous if ASYNCHRONOUS=NO or if both ASYNCHRONOUS= and ID= are absent. For ASYNCHRONOUS=YES or if ID= appears, asynchronous I/O is permitted only for external files opened with ASYNCHRONOUS=YES in the OPEN statement.

If a variable is used in an asynchronous data transfer statement as an item in an I/O list, a group object in a namelist or as a SIZE= specifier, the base object of the data_ref is implicitly given the ASYNCHRONOUS attribute in the scoping unit of the data transfer statement. For asynchronous nonadvancing input, the storage units specified in the SIZE= specifier become defined with the count of the characters transferred when the corresponding wait operation is executed. For asynchronous output, a pending I/O storage sequence affector shall not be redefined, become undefined, or have its pointer association status changed. For asynchronous input, a pending I/O storage sequence affector shall not be referenced, become defined, become undefined, become associated with a dummy argument that has the VALUE attribute, or have its pointer association status changed.

When an error, end-of-file or end-of-record condition occurs for a previously executed asynchronous data transfer statement , a wait operation is performed for all pending data transfer operations on that unit. When a condition occurs during a subsequent statement, any actions specified by IOSTAT=, IOMSG=, ERR=, END=, and EOR= specifiers for that statement are taken.

A wait operation is performed by a WAIT, CLOSE, or file positioning statement.

DECIMAL= char_expr(Fortran 2003)
temporarily changes the default decimal edit mode for the duration of an I/O statement. char_expr is a scalar character expression whose value must evaluate to either POINT, or COMMA. After each WRITE statement, the mode defaults to whatever decimal mode was specified (or assumed) on the OPEN statement for that unit.
POS=integer_expr(Fortran 2003)
integer_expr is an integer expression greater than 0. POS= specifies the file position of the file storage unit to be written in a file connected for stream access. You must not use POS= for a file that cannot be positioned.
REC= integer_expr
is a record specifier that specifies the number of the record to be written in a file connected for direct access. The REC= specifier is only permitted for direct output. integer_expr is an integer expression whose value is positive. A record specifier is not valid if formatting is list-directed or if the unit specifier specifies an internal file. The record specifier represents the relative position of a record within a file. The relative position number of the first record is 1. You must not specify REC= in data transfer statements that specify a unit connected for stream access, or use the POS= specifier.
ROUND= char-expr(Fortran 2003)

temporarily changes the current value of the I/O rounding mode for the duration of this I/O statement. If omitted, then the rounding mode is unchanged. char-expr evaluates to either UP, DOWN, ZERO, NEAREST, COMPATIBLE or PROCESSOR_DEFINED

The rounding mode helps specify how decimal numbers are converted to an internal representation, (that is, in binary) from a character representation and vice versa during formatted input and output. The rounding modes have the following functions:

  • In the UP rounding mode the value from the conversion is the smallest value that is greater than or equal to the original value.
  • In the DOWN rounding mode the value from the conversion is the greatest value that is smaller than or equal to the original value.
  • In the ZERO rounding mode the value from the conversion is the closest value to the original value, and not greater in magnitude.
  • In the NEAREST rounding mode the value from the conversion is the closer of the two nearest representable values. If both values are equally close then the even value will be chosen. In IEEE rounding conversions, NEAREST corresponds to the ieee_nearest rounding mode as specified by the IEEE standard.
  • In the COMPATIBLE rounding mode the value from the conversion is the closest of the two nearest representable values, or the value further away from zero if halfway between.
  • In the PROCESSOR_DEFINED rounding mode the value from the conversion is processor dependent and may correspond to the other modes. In the PROCESSOR_DEFINED rounding mode the value from the conversion is processor dependent and may correspond to the other modes. In XL Fortran, the PROCESSOR_DEFINED rounding mode will be the rounding mode you choose in the floating-point control register. If you do not set the floating-point control register explicitly, the default rounding mode is NEAREST.
SIGN= char_expr(Fortran 2003)
indicates the sign mode in effect for a connection for formatted input/output. If char_expr is assigned the value PLUS, the processor shall produce a plus sign in any position that normally contains an optional plus sign and suppresses plus signs in these positions if char_expr is assigned the value SUPPRESS. char_expr can also be assigned the value PROCESSOR_DEFINED which is the default sign mode and acts the same as SUPPRESS. If there is no connection, or if the connection is not for formatted input/output, char_expr is assigned the value UNDEFINED.
IOMSG= iomsg_variable(Fortran 2003)
is an input/output status specifier that specifies the message returned by the input/output operation. iomsg_variable is a scalar default character variable. It must not be a use-associated nonpointer protected variable. When the input/output statement containing this specifier finishes execution, iomsg_variable is defined as follows:
  • If an error, end-of-file, or end-of-record condition occurs, the variable is assigned an explanatory message as if by assignment.
  • If no such condition occurs, the value of the variable is unchanged.
IOSTAT= ios
is an input/output status specifier that specifies the status of the input/output operation. ios is an integer variable. Coding the IOSTAT= specifier suppresses error messages. When the statement finishes execution, ios is defined with:
  • A zero value if no error condition occurs
  • A positive value if an error occurs.
ID= integer_variable(IBM extension)
indicates that the data transfer is to be done asynchronously. The integer_variable is an integer variable. If no error is encountered, the integer_variable is defined with a value after executing the asynchronous data transfer statement. This value must be used in the matching WAIT statement.

Asynchronous data transfer must either be direct unformatted, sequential unformatted, or stream unformatted. Asynchronous I/O to internal files is prohibited. Asynchronous I/O to raw character devices (for example, tapes or raw logical volumes) is prohibited. The integer_variable must not be associated with any entity in the data transfer I/O list, or with a do_variable of an io_implied_do in the data transfer I/O list. If the integer_variable is an array element reference, its subscript values must not be affected by the data transfer, the io_implied_do processing, or the definition or evaluation of any other specifier in the io_control_spec.

DELIM= char_expr(Fortran 2003)
specifies what delimiter, if any, is used to delimit character constants written with list-directed or namelist formatting. char_expr is a scalar character expression whose value must evaluate to APOSTROPHE, QUOTE, or NONE. If the value is APOSTROPHE, apostrophes delimit character constants and all apostrophes within character constants are doubled. If the value is QUOTE, double quotation marks delimit character constants and all double quotation marks within character constants are doubled. If the value is NONE, character constants are not delimited and no characters are doubled. The default value is NONE. The DELIM= specifier is permitted only for files being connected for formatted input/output, although it is ignored during input of a formatted record.
ERR= stmt_label
is an error specifier that specifies the statement label of an executable statement in the same scoping unit to which control is to transfer in the case of an error. Coding the ERR= specifier suppresses error messages.
NUM= integer_variable(IBM extension)
is a number specifier that specifies the number of bytes of data transmitted between the I/O list and the file. integer_variable is an integer variable. The NUM= specifier is only permitted for unformatted output. Coding the NUM parameter suppresses the indication of an error that would occur if the number of bytes represented by the output list is greater than the number of bytes that can be written into the record. In this case, integer_variable is set to a value that is the maximum length record that can be written. Data from remaining output list items is not written into subsequent records. In the portion of the program that executes between the asynchronous data transfer statement and the matching WAIT statement, the integer_variable in the NUM= specifier or any variable associated with it must not be referenced, become defined, or become undefined.
[NML=] name
is a namelist specifier that specifies the name of a namelist list that you have previously defined. If the optional characters NML= are not specified, the namelist name must appear as the second parameter in the list, and the first item must be the unit specifier with UNIT= omitted. If both NML= and UNIT= are specified, all the parameters can appear in any order. The NML= specifier is an alternative to FMT=. Both NML= and FMT= cannot be specified in the same output statement.
ADVANCE= char_expr
is an advance specifier that determines whether nonadvancing output occurs for this statement. char_expr is a character expression that must evaluate to YES or NO. If NO is specified, nonadvancing output occurs. If YES is specified, advancing, formatted sequential or formatted stream output occurs. The default value is YES. ADVANCE= can be specified only in a formatted sequential WRITE statement with an explicit format specification that does not specify an internal file unit specifier.

Rules

If a NUM= specifier is present, neither a format specifier nor a namelist specifier can be present.

Variables specified for the IOSTAT= and NUM= specifiers must not be associated with any output list item, namelist list item, or DO variable of an implied-DO list. If such a specifier variable is an array element, its subscript values must not be affected by the data transfer, any implied-DO processing, or the definition or evaluation of any other specifier.

If the ERR= and IOSTAT= specifiers are set and an error is encountered during a synchronous data transfer, transfer is made to the statement specified by the ERR= specifier and a positive integer value is assigned to ios.

If the ERR= or IOSTAT= specifiers are set and an error is encountered during an asynchronous data transfer, execution of the matching WAIT statement is not required.

If a conversion error is encountered and the CNVERR run-time option is set to NO, ERR= is not branched to, although IOSTAT= may be set.

If IOSTAT= and ERR= are not specified,
  • The program stops if a severe error is encountered.
  • The program continues to the next statement if a recoverable error is encountered and the ERR_RECOVERY run-time option is set to YES. If the option is set to NO, the program stops.
  • The program continues to the next statement when a conversion error is encountered if the ERR_RECOVERY run-time option is set to YES. If the CNVERR run-time option is set to YES, conversion errors are treated as recoverable errors; when CNVERR=NO, they are treated as conversion errors.

PRINT format has the same effect as WRITE(*,format).

Examples

WRITE (6,FMT='(10F8.2)') (LOG(A(I)),I=1,N+9,K),G

Related information