Edit descriptors

Character string (’...’ or ”...”) edit descriptor

The character string edit descriptor is used to write a character constant to a formatted output record. It cannot be used to format input. You can use either apostrophes or quotation marks to delimit the constant. Whichever you use, they must be balanced. That is, if you begin with an apostrophe, you must also end with it. If the enclosed character constant includes a delimiting character, it must be of the other type; or you can escape the delimiter by giving another of the same type. The width of the field is the number of characters enclosed by the character string edit descriptors, including any blanks.

Table 9-2 “Character string edit descriptor output examples” provides examples of the character string edit descriptor on output. Note that b represents a blank.

Newline ($) edit descriptor

The newline edit descriptor is an HP extension that suppresses the generation of the newline character (that is, the carriage-return/linefeed sequence) during formatted, sequential output. By default, the cursor moves to a newline after each output statement. The newline edit descriptor causes the cursor to remain on the same line, immediately to the right of the last character output.

	NOTE: Nonadvancing I/O also suppresses the newline at the end of a record. Unlike the newline ($) edit descriptor, it is a standard feature of Fortran 90, and can be used on input and output. For more information, see “Nonadvancing I/O” and the ADVANCE= I/O specifier in “OPEN”.

Slash (/) edit descriptor

The slash edit descriptor terminates the current record and begins processing a new record (such as a new line on a terminal). This edit descriptor has the same result for both input and output: it terminates the current record and begins a new one. For example, on output a newline character is printed, and on input a new line is read.

Keep in mind the following considerations when using the slash edit descriptor:

The / edit descriptor does not need to be separated from other descriptors by commas.

Colon (:) edit descriptor

The colon edit descriptor (:) is used when performing formatted I/O to terminate format control when the I/O list has been exhausted. If all items in an I/O list have been read or written, the colon edit descriptor stops any further format processing. If more items remain in the list, the colon edit descriptor has no effect.

Consider the following example:

WRITE (*, 40) 1, 2
WRITE (*, 50) 1, 2
40 FORMAT(3(' value =', I2))
50 FORMAT(3(:, ' value =', I2))

The first WRITE statement outputs the line:

 value = 1 value = 2 value =

The descriptor 'value =' is repeated a third time because format control is not terminated until the descriptor I2 is reached and not satisfied.

The second WRITE statement outputs the line:

 value = 1 value = 2

This time, the colon descriptor terminates format control before the string ' value=' is output a third time.

A and R (character) edit descriptors

The A and R edit descriptors define fields for character data. The A edit descriptor specifies left-justification, and the R edit descriptor specifies right-justification.

The R edit descriptor is an HP extension.

The syntax for the character edit descriptors is:

[r]A[w]

[r]R[w]

where:

As a portability extension, the list item can be of any data type.

When the A and R edit descriptors are used for input and output, the results can differ according to whether the width (w) specified for the edit descriptor is less than, greater than, or equal to the length of the I/O list item. The results on input are summarized in Table 9-3 “Contents of character data fields on input”; the results on output are summarized in Table 9-4 “Contents of character data fields on output”.

Examples of the use of character edit descriptors on input are provided in Table 9-5 “A and R edit descriptors: input examples”. In the table, b represents a blank and z represents a Null.

Table 9-6 “A and R Edit descriptors: output examples” provides examples of character edit descriptors on output. In the table, b represents a blank and z represents a Null.

B (binary) edit descriptor

The B edit descriptor defines a field for binary data. It provides for conversion between an external binary number and its internal representation.

The syntax for the binary edit descriptor is:

[r]B[w[.m]]

where:

Input

Variables to receive binary input must be of type integer. The only legal characters are 0s and 1s. Nonleading blanks are ignored, unless the file is opened with BLANK='ZERO'.

If the file is opened with BLANK='ZERO', nonleading blanks are treated as zeroes. For more information about the BLANK= specifier, see “OPEN”. Plus and minus signs, commas, or any other symbols are not permitted. If a nonbinary digit appears, an error occurs. The presence of too many digits for the integer variable (or I/O list item) is illegal.

Table 9-7 “B Edit descriptor: input examples” provides examples of the binary edit descriptor on input.

Output

Unlike input, list items on output may be of any type, though character values are output only as the binary equivalent of their ASCII representation (without a length descriptor). If w is greater than the number of converted binary digits (excluding leading zeroes), the binary digits are right-justified in the output field.

If w is less than the number of converted binary digits, the field is filled with w asterisks. This primarily affects the output of negative values. Because negative values are output in twos complement form, their high-order bits are nonzero and cause the field to be filled with asterisks when w is less than the number of binary digits in the entire output value.

The field width required to fully represent the binary value of an item is eight times its size in bytes. For example, an INTEGER*4 item could require a field w of up to 32 characters.

Only 1s and 0s are printed on output.

Table 9-8 “B Edit descriptor: output examples” provides examples of the binary edit descriptor on output.

BN and BZ (blank) edit descriptors

The BN and BZ edit descriptors control the interpretation of embedded and trailing blanks in numeric input fields. The syntax of the blank edit descriptors is:

BN

BZ

At the beginning of the execution of an input statement, blank characters within numbers are ignored except when the unit is connected with BLANK='ZERO' specified in the OPEN statement. BN and BZ override the BLANK= I/O specifier for the current READ statement. For more details about the BLANK= I/O specifier, see “OPEN”.

If a BZ edit descriptor is encountered in the format specification, trailing and embedded blanks in succeeding numeric fields are treated as zeroes. The BZ edit descriptor remains in effect until a BN edit descriptor or the end of the format specification is encountered. If BN is specified, all embedded blanks are removed and the input number is right justified within the field width.

The BN and BZ edit descriptors affect only I, B, O, F, D, E, EN, ES, G, and Z format descriptors during the execution of an input statement. The BN and BZ edit descriptors do not affect character and logical edit descriptors.

Table 9-9 “BN and BZ edit descriptors: input examples” provides examples of the BN and BZ edit descriptors on input.

The BN and BZ edit descriptors are ignored during the execution of an output statement.

D, E, EN, ES, F, G, and Q (real) edit descriptors

The D, E, EN, ES, F, G, and Q edit descriptors define fields for real numbers. The I/O list item corresponding to a real descriptor must be a numeric type. (The Standard permits real and complex types only; as an extension, HP Fortran allows integers.)

The syntax for these edit descriptors is:

[r]D[w.d]

[r]E[w.d[{E|D|Q}e]]

[r]EN[w.d[Ee]]

[r]ES[w.d[Ee]]

[r]F[w.d]

[r]G[w.d[{E|D|Q}e]]

[r]Q[w.d]

where:

For formatting complex data, you can use two real edit descriptors—the first for the real part of the number and the second for the imaginary part. The two edit descriptors may be different or the same, and you can insert control and character string edit descriptors between them.

H (Hollerith) edit descriptor

The H edit descriptor outputs a specified number of characters. The syntax is:

nHcharacter-sequence

where:

Table 9-15 “H edit descriptor: output examples” provides examples of the Hollerith edit descriptor on output.

I (Integer) edit descriptor

The I edit descriptor defines a field for an integer number. As an HP extension, it can also be used on real and logical data. The corresponding I/O list item must be a numeric or logical type.

The syntax of the integer edit descriptor is:

[rI][w[.m]]

where:

Input

The integer edit descriptor causes the interpretation of the next w positions of the input record. The number is converted to match the type of the list item currently using the descriptor. A plus sign is optional for positive values. A decimal point must not appear in the field.

Table 9-16 “I edit descriptor: input examples” provides examples of the integer edit descriptor on input.

Output

The integer edit descriptor outputs a numeric variable as a right-justified integer value (truncated, if necessary). The field width, w, should be one greater than the expected number of digits to allow a position for a minus sign for negative values. If m is set to 0, a zero value is output as all blanks.

Table 9-17 “I edit descriptor: output examples” provides examples of the integer edit descriptor on output.

L (Logical) edit descriptor

The L edit descriptor defines a field for logical data. Its syntax is:

[r]L[w]

where:

The I/O list item corresponding to an L edit descriptor must be of type logical, short logical, or byte.

Input

The field width is scanned for optional blanks followed by an optional decimal point, followed by T (or t) for true or F (or f) for false. The first nonblank character in the input field (excluding the optional decimal point) determines the value to be stored in the declared logical variable. It is an error if the first nonblank character is not T, t, F, f, or a period(.).

Table 9-18 “L edit descriptor: input examples” provides examples of the logical edit descriptor on input.

Output

The character T or F is right-justified in the output field, depending on whether the value of the list item is true or false. Table 9-19 “L edit descriptor: output examples” provides examples of the logical edit descriptor on output.

M and N edit descriptors

Edit descriptors M and N are used to output numeric values in formats normally used for currency.

For example, the N edit descriptor will output a value 1234.5 in the format 1,234.50; the M edit descriptor will cause this same value to be output at $1,234.50.

O (Octal) edit descriptor

The O edit descriptor defines a field for octal data. It provides conversion between an external octal number and its internal representation.

The syntax for the octal edit descriptor is:

[r]O[w[.m]]

where:

Input

The presence of too many digits for the integer variable (or list item) to receive produces undefined results. Legal octal digits are 0 through 7. Plus and minus signs are illegal.

Table 9-20 “O edit descriptor: input examples” provides examples of the octal edit descriptors on input.

Output

List items may be of any type, though character variables are output only as the octal equivalent of their ASCII representation (no length descriptor).

If w is greater than the number of converted octal digits (including blanks between words but excluding leading zeroes), the octal digits are right-justified in the output field. If w is less than the number of converted octal digits, the field is filled with asterisks. This primarily affects the output of negative values. Because negative values are output in twos complement form, their high-order bits are nonzero and cause the field to be filled with asterisks when w is less than the number of octal digits in the entire output value. If m is set to 0, a zero value is output as all blanks.

Table 9-21 “O edit descriptor: output examples” provides examples of the octal edit descriptors on output.

P (scale factor) edit descriptor

The kP edit descriptor causes a scale factor of k to be applied to all subsequent F, D, E, EN, ES, and G edit descriptors in the format specification.

If the P edit descriptor does not precede an F, D, E, EN, ES, or G edit descriptor, it should be separated from other edit descriptors by a comma. If the P edit descriptor immediately precedes an F, D, E, EN, ES, or G edit descriptor, the comma is optional.

For example, the format specification

(3P, I2, F4.1, E5.2)

is equivalent to

(I2, 3PF4.1, E5.2)

When a format specification is interpreted, the scale factor is initially set to 0. When a P edit descriptor is encountered, the specified scale factor takes effect for the format specification and remains in effect until another P edit descriptor is encountered.

The effect of the scale factor differs for input and output as follows:

Input

If the value in the input field does not have an exponent, the internal number is equal to the field value multiplied by 10-k. If the value in the input field has an exponent, the scale factor has no effect. See Table 9-22 “P edit descriptor: input and output examples” for examples of the scale factor on input.

Output

The scale factor has no effect on the EN, ES, F and G (interpreted as F) edit descriptors. For the D, E, and G (interpreted as E) edit descriptors, the value of the list item is multiplied by 10k as it is output but the exponent part is decreased by k.

The value specified for the scale factor (k) must be in the range:

-d < k < (d + 2)

where:

Table 9-22 “P edit descriptor: input and output examples” provides examples of the scale factor on output.

When part or all of a format specification is repeated, the current scale factor is not changed until another scale factor is encountered.

Q (bytes remaining) edit descriptor

The Q edit descriptor is an HP extension that returns the number of bytes remaining to be read in the input record, placing the result into the corresponding integer variable in the I/O list. The return value can be used to control the remaining input items.

The Q edit descriptor is valid on input only; it is ignored on output. It can be used for reading formatted, sequential, and direct-access files. The following program segment reads variable-length strings from a sequential file:

CHARACTER(LEN=80) :: string
INTEGER :: n, i
...
READ (11,'(Q,80A1)') n, (string (i:i), i=1, n)

For information about the Qw.d edit descriptor for editing real data, see “D, E, EN, ES, F, G, and Q (real) edit descriptors”.

S, SP, and SS (plus sign) edit descriptors

The S, SP, and SS edit descriptors control printing of the plus sign character in numeric output. The default behavior of HP Fortran is not to print the plus sign. However, an SP edit descriptor in the format specification causes the plus sign to appear in any subsequent numeric output where the value is positive. The SS descriptor suppresses the plus sign in subsequent numeric output. The S edit descriptor restores the default behavior.

The sign edit descriptors have no effect on input.

T, TL, TR, and X (tab) edit descriptors

The tab edit descriptors position the cursor on the input or output record. Their syntax is:

Tn

TLn

TRn

nX

where:

The T edit descriptor references an absolute column number, while the descriptors TL and TR reference a relative number of column positions to the left (TL) or right (TR) of the current cursor position. Note that the TR descriptor is identical to the X edit descriptor.

Z (hexadecimal) edit descriptor

The Z edit descriptor defines a field for hexadecimal data. This descriptor provides for conversion between an external hexadecimal number and its internal representation.

The syntax for the hexadecimal edit descriptor is:

[r ]Z[w [.m ]]

where:

Input

Variables to receive hexadecimal input must be of type integer. Legal hexadecimal digits are 0 through 9, and A through F (or a through f). Nonleading blanks are ignored, unless the file is opened with BLANK='ZERO'. If the file is opened with BLANK='ZERO', nonleading blanks are treated as zeroes. For more information about the BLANK= specifier see “OPEN”. Plus and minus signs, commas, or any other symbols are neither permitted on input nor printed on output. The presence of too many digits for the integer variable (or list item) produces undefined results.

Table 9-23 “Z edit descriptor: input examples” provides examples of the hexadecimal edit descriptor on input.

Output

List items may be of any type, though character variables are output only as the hexadecimal equivalent of their ASCII representation (without a length descriptor). If w is greater than the number of converted hexadecimal digits (excluding leading zeroes), the hexadecimal digits are right-justified in the output field. If w is less than the number of converted hexadecimal digits, the field is filled with asterisks. This primarily affects the output of negative values. Because negative values are output in twos complement form, their high-order bits are nonzero and cause the field to be filled with asterisks when w is less than the number of hexadecimal digits in the entire output value. If m is set to 0, a zero value is output as all blanks.

The field width required to fully represent the hexadecimal value of an item is twice its size in bytes. For example, a CHARACTER*12 item would require a field width of 24 characters.

Table 9-24 “Z edit descriptor: output examples” provides examples of the hexadecimal edit descriptor on output.