fformats.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap *refid=fformat Format
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
A
.us format
specification used in conjunction with formatted I/O provides a
means of specifying the way internal data is converted to a
character string and vice versa.
A format specification can be given in two ways.
.autopoint
.point
In a
.kw FORMAT
statement.
.point
As values of character expressions or character arrays.
.endpoint
.*
.section The FORMAT Statement
.*
.np
The form of a
.kw FORMAT
statement is
.mbox begin
      label    FORMAT fs
.mbox end
.synote 7
.mnote label
is the statement label used by an I/O statement to identify the
.kw FORMAT
statement.
.mnote fs
is a format specification which will be described later.
.endnote
.exam begin
      REAL X
      X = 234.43
      PRINT 100, X
100   FORMAT(F10.2)
      END
.exam end
.pc
In the previous example, the
.kw PRINT
statement uses the format specification in the
.kw FORMAT
statement whose statement label is 100 to display the value of
.id X.
.*
.section FORMAT as a Character Expression
.*
.np
Instead of specifying the statement label of a
.kw FORMAT
statement, a character expression can be used.
The previous example could be modified as follows and achieve the
identical result.
.exam begin
      REAL X
      X = 234.43
      PRINT '(F10.2)', X
      END
.exam end
.np
When using a character expression to represent a format specification,
the format specification can be preceded by blank characters and followed
by any character data without affecting the format specification.
The following example produces the identical result to the previous
example.
.exam begin
      REAL X
      X = 234.43
      PRINT '    (F10.2) THIS IS FOR X', X
      END
.exam end
.np
If a character array is used to describe the format specification,
the format specification is considered to be the concatenation of
all the character array elements in the order given by array element
ordering described in the chapter entitled :HDREF refid='farrays'..
Note that if a character array element is used, the format specification
is considered to be only that array element.
.exam begin
      REAL X
      CHARACTER*5 FMTSPEC(3)
      X = 234.43
      FMTSPEC(1)='('
      FMTSPEC(2)='F10.2'
      FMTSPEC(3)=')'
      PRINT FMTSPEC, X
      END
.exam end
.*
.section Format Specification
.*
.np
.ix format 'see also' 'edit descriptor'
A
.us format specification
.ix 'format specification'
has the following form.
.mbox begin
      ( [flist] )
.mbox end
.synote 8
.mnote flist
is a list whose items are separated by commas.
The forms of the items in
.id flist
are:
.np
.id [r] ed
.np
.id ned
.np
.id [r] fs
.mnote ed
is a repeatable edit descriptor.
.mnote ned
is a nonrepeatable edit descriptor.
.mnote fs
is a format specification with a nonempty list
.id flist.
.mnote r
is a positive unsigned integer constant called a
.us repeat specification.
.ix format 'repeat specification'
.endnote
.np
The comma separating the items of
.id flist
can be omitted in the following cases.
.autopoint
.point
Between a
.id P
edit descriptor and an
.id F, E, D
or
.id G
edit descriptor which immediately follows.
.point
Before or after a slash edit descriptor.
.point
Before or after a colon edit descriptor.
.endpoint
.np
.xt begin
&product allows the omission of a comma between the items of
.id flist.
Care should be taken when omitting commas between edit descriptors.
For example, the format specification
.mono (I5 2I3)
may appear to be an
.mono I5
edit descriptor followed by two
.mono I3
edit descriptors when in actuality it is interpreted as an
.mono I52
edit descriptor followed by an
.mono I3
edit descriptor.
.xt end
.*
.section Repeatable Edit Descriptors
.*
.np
The forms of
.us repeatable edit descriptors
.ix 'repeatable edit descriptor'
.ix 'edit descriptor' repeatable
.ix extension 'E edit descriptor'
.ix extension 'Z edit descriptor'
are:
.millust begin
    Iw
    Iw.m
    Fw.d
    Ew.d
    Ew.dEe
    Dw.d
    Gw.d
    Gw.dEe
    Lw
    A
    Aw
.millust end
.np
.xt begin
As an extension to the FORTRAN 77 language, the following repeatable
edit descriptors are also supported.
.millust begin
    Ew.dDe
    Zw
.millust end
.xt end
.synote
.mnote ~b
.id I, F, E, D, G, L, A
and
.id Z
indicate the method of editing.
.np
.id w
and
.id e
are positive unsigned integer constants.
.np
.id d
and
.id m
are unsigned integer constants.
.endnote
.*
.section Nonrepeatable Edit Descriptors
.*
.np
The forms of
.us nonrepeatable edit descriptors
.ix 'nonrepeatable edit descriptors'
.ix 'edit descriptor' repeatable
.ix '$ edit descriptor'
.ix '\ edit descriptor'
.ix extension 'X edit descriptor'
.ix extension '$ edit descriptor'
.ix extension '\ edit descriptor'
are:
.millust begin
    'hh...h' (apostrophe)
    nHhh...h
    Tc
    TLc
    TRc
    nX
    /
    :
    S
    SP
    SS
    kP
    BN
    BZ
    X
.millust end
.np
.xt begin
As an extension to the FORTRAN 77 language, the following
nonrepeatable edit descriptors are also supported.
.millust begin
    $
    \
.millust end
.xt end
.synote
.mnote ~b
Apostrophe,
.id H, T, TL, TR, X, /, :, S, SP, SS, P, BN, BZ,
.xt on
.id \
and
.id $
.xt off
indicate the method of editing.
.np
.id h
is a character.
.np
.id n
and
.id c
are positive unsigned integer constants.
.np
.id k
is an optionally signed integer constant.
.endnote
.np
.xt begin
&product allows edit descriptors to be specified using lower case
letters.
.xt end
.*
.section Editing
.*
.np
Edit descriptors are used to describe the way the editing between
internal representation of data and the characters of a record in a file
is to take place.
When the edit descriptors
.id I, F, E, D, G, L, A, H, Z
or apostrophe are
processed, they process a sequence of characters called a
.us field.
.ix format field
On input, the field is the character data read from a record; on output
it is the character data written to a record.
The number of characters in a field is called the
.us field width.
.ix format 'field width'
.*
.beglevel
.*
.section Apostrophe Editing
.*
.np
The
.us apostrophe edit descriptor
.ix 'apostrophe edit descriptor'
.ix 'edit descriptor' apostrophe
has the same form as a character constant
and can only be used on output.
It causes the characters in the format specification enclosed in quotes
to be written.
The field width is the number of characters enclosed in quotes.
.exam begin
      PRINT '(''HI THERE'')'
      END
.exam end
.pc
In the previous example, the string
.millust begin
HI THERE
.millust end
.pc
would be the output produced by the
.kw PRINT
statement.
.*
.section H Editing
.*
.np
The
.id nH
.ix 'H edit descriptor'
.ix 'edit descriptor' H
edit descriptor causes the
.id n
characters following the
.id H,
including blanks, to be written.
Like the apostrophe edit descriptor, it can only appear in a format
specification used for output.
.exam begin
      PRINT '(8HHI THERE)'
      END
.exam end
.pc
In the previous example, the string
.millust begin
HI THERE
.millust end
.pc
would be the output produced by the
.kw PRINT
statement.
.*
.section Positional Editing: T, TL, TR and X Editing
.*
.np
.ix 'positional edit descriptor'
.ix 'edit descriptor' positional
.ix 'edit descriptor' positional T
.ix 'edit descriptor' positional TL
.ix 'edit descriptor' positional TR
.ix 'edit descriptor' positional X
.ix 'T edit descriptor'
.ix 'TL edit descriptor'
.ix 'TR edit descriptor'
.ix 'X  edit descriptor'
The
.id T,
.id TL,
.id TR
and
.id X
edit descriptors specify at which position the next character will be
read from or written to the record.
In the case of input, this allows data to be read more than once with
different edit descriptors.
On output, it is possible to overwrite data previously written.
.np
On output it is possible to use positional editing to create a record
in which gaps appear.
That is, there may be parts of the record where no data has been
written.
The parts of a record in which no data has been written are filled with
blanks.
The effect is as if the record was previously initialized to blanks.
Note that positioning does not cause any data to be transmitted.
.np
The
.id Tc
edit descriptor specifies that the next character to be
transmitted is to be from the
.id c
.ct th
character position in the record.
The
.id TLc
edit descriptor specifies that the next character to be
transmitted is to be from the
.id c
.ct th
position backward from the current position.
The
.id TRc
edit descriptor is identical to the
.id TLc
edit descriptor except
that positioning is forward from the current position.
The
.id nX
edit descriptor behaves identically to the
.id TRc
edit descriptor;
the transmission of the next character is
.id n
character positions forward from the current position.
.xt on
If
.id n
is omitted then the transmission of the next character is 1 character
position forward from the current position.
.xt off
.exam begin
      PRINT '(''THE NUMBER       IS AN INTEGER'',TL19,
     $      ''12345'')'
      END
.exam end
.pc
The output produced is
.millust begin
THE NUMBER 12345 IS AN INTEGER
.millust end
.*
.section Slash Editing
.*
.np
The
.us slash edit descriptor
.ix 'slash edit descriptor'
.ix 'edit descriptor' slash
indicates the end of data transfer on the current record.
On input from a record connected for sequential access, the remaining
characters in the record are skipped and the file is positioned to the
start of the next record.
Note that entire records may be skipped.
On output, a new record is created and becomes the last and current
record of the file.
Note that a record with no characters can be written.
If the file is an internal file or a direct access file, the record
is filled with blanks.
.np
For a file connected for direct access, the current record number is
increased by one and the file is positioned at the beginning of that
record.
.*
.section Colon Editing
.*
.np
The
.us colon edit descriptor
.ix 'colon edit descriptor'
.ix 'edit descriptor' colon
terminates processing of the format
specification if there are no more items in the I/O list.
If there are items remaining in the I/O list, the colon edit
descriptor has no effect.
.*
.section S, SP and SS Editing
.*
.np
The
.id S,
.id SP
and
.id SS
.ix 'S edit descriptor'
.ix 'SS edit descriptor'
.ix 'SP edit descriptor'
.ix 'edit descriptor' S
.ix 'edit descriptor' SS
.ix 'edit descriptor' SP
edit descriptors control optional plus characters in
numeric output fields.
They only effect the
.id I,
.id F,
.id E,
.id D
and
.id G
edit descriptors during output
and have no effect on input.
The FORTRAN 77 standard specifies that before processing a format
specification, the appearance of a plus sign in numeric output fields
is optional and is determined by the processor.
&product does not produce plus signs in numeric output fields.
When an
.id SP
edit descriptor is encountered, a plus sign is produced
in any subsequent position that optionally contains a plus sign.
When as
.id SS
edit descriptor is encountered, a plus sign is not produced
in any subsequent position that optionally contains a plus sign.
If an
.id S
edit descriptor is encountered, the option is returned to the
processor.
.exam begin
      PRINT '(1H<,I5,SP,I5,SS,I5,1H>)',1,2,3
      END
.exam end
.pc
The output produced by the
.kw PRINT
statement in the previous example is:
.millust begin
<    1   +2    3>
.millust end
.*
.section P Editing
.*
.np
The form of a
.id P
edit descriptor is
.ix 'P edit descriptor'
.ix 'edit descriptor' P
.id kP
where
.id k
is an optionally signed integer constant called the
.us scale factor.
.ix 'scale factor'
The value of the scale factor is zero at the beginning of each I/O
statement.
The scale factor applies to all subsequent
.id F,
.id E,
.id D
and
.id G
edit descriptors until another scale factor is encountered.
The scale factor affects editing in the following way.
.autopoint
.point
On input with
.id F,
.id E,
.id D
and
.id G
editing, provided that no exponent exists
in the field, the effect is that the
represented number equals the internally represented number multiplied
by
.mono 10**k.
.point
On input with
.id F,
.id E,
.id D
and
.id G
editing, the scale factor has no effect
if there is an exponent in the field.
.point
On
.id F
output editing, the effect is that the represented number equals
the internally represented number multiplied
by
.mono 10**k.
.point
On output with
.id E
and
.id D
editing, the simple real constant
(see the chapter entitled :HDREF refid='ftypes'.)
part of the data is multiplied by
.id 10**k
and the exponent is reduced by
.id k.
.point
On output with
.id G
editing, the scale factor has no effect unless the
magnitude of the datum is outside the range that allows
.id F
editing (see the section entitled :HDREF refid='gedit'.).
If
.id E
editing is required, the scale factor has the same effect as
with
.id E
output editing.
.endpoint
.*
.section BN and BZ Editing
.*
.np
The
.id BN