Subject: hpff-doc: io-ext.tex

From: <[email-masked]> (Henry Zongaro)
Date: Fri, 18 Oct 1996 17:24:53 -0400 (EDT)

---------------------------------------------------------------------------
[email-masked] is a mailing list for HPF 2.0 language specification
authors and editors.  Instructions for adding or deleting yourself from this
list appear at the bottom of this message.
---------------------------------------------------------------------------
Hello,

     Here's the latest revision of io-ext.tex.  There are a couple of points
still being discussed.  One is the "READ ... I, A(I)" issue, a second is the
need for an ASYNCH= specifier on the INQUIRE statement - I guess we'll have to
wait for the public comments to suggest the syntax for that (since it hasn't
been formulated yet).

Thanks,

Henry

------------------------------------------------------------------------------

% File: io-ext.tex

% Contents:
% Approved Extension for EXTRINSIC(HPF_LOCAL) for HPF 2.0 document

% Revision history:
% May-28-96     Created by Larry Meadows, The Portland Group
% 1996/10/07    Updated by Henry Zongaro
% 1996/10/18    Updated by Henry Zongaro

\chapter{Approved Extension for Asynchronous I/O}
\label{ch-io-ext}

This section defines a mechanism for performing Asynchronous I/O
from an HPF or Fortran program. These are presented as changes
to the Fortran 90 standard.

To the second paragraph of section 9.2.1, before ``and'' add
``a processor-dependent set of allowed {\bf transfer methods},''.

To section 9.3.4, Rule R905, add

\begin{quote}
                                                                         \BNF
connect-spec             \IS  ASYNCH = scalar-default-char-expr
                                                                         \FNB
\end{quote}

Add a new section after 9.3.4.10, entitled ``{\bf ASYNCH= specifier in the
OPEN statement}'', containing the following paragraph:

\begin{quote}
The {\em scalar-default-char-expr} shall evaluate to 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 shall be in the set of transfer
methods permitted for the file.  If this specifier is omitted, the default
value is NO.
\end{quote}

To section 9.4.1, Rule R912, add

\begin{quote}
                                                                        \BNF
io-control-spec            \IS ID = scalar-default-int-variable
                                                                        \FNB
\end{quote}

To section 9.4.1, Rule R912 add the constraints

\begin{quote}
\begin{constraints}

\item If an {\tt ID=} specifier is present, the {\tt REC=} specifier shall
appear, a {\em format} shall not appear, and a {\em namelist-group-name}
shall not appear.

\item If an {\tt ID=} specifier is present, then no function reference may
appear in an expression anywhere in the data transfer statement.

\end{constraints}
\end{quote}

At the end of section 9.4.1, add the following three paragraphs:

\begin{quote}
The addition of the {\tt ID=} specifier results in the initiation of an
asynchronous data transfer.  The data transfer statement must be
eventually followed by a {\tt WAIT} statement specifying the same
{\tt ID} value that was returned to the {\tt ID} variable in a data transfer
statement, unless an {\tt IOSTAT=} specifier appeared on the data transfer
statement and the variable specified became defined with a non-zero value, or
an {\tt ERR=} specifier appeared and an error condition was detected on the
data transfer statement, in which case no such {\tt WAIT} statement
is permitted to appear.  This {\tt WAIT} statement is called the
{\em matching} {\tt WAIT} statement. Note that asynchronous data transfer must
be direct and unformatted.

The {\tt ID=} specifier must not be specified for a unit opened with an
{\tt ASYNCH=} specifier with a value of NO.
\end{quote}

In section 9.4.1, in the fourth and fifth paragraphs after the constraints,
change both instances of ``{\tt IOSTAT=} or a {\tt SIZE=}'' to
``{\tt IOSTAT=}, {\tt SIZE=} or an {\tt ID=}''.

Insert the following text at the end of section 9.4.3 before the
final paragraph:

\begin{quote}
For an asynchronous data transfer, errors
may occur either during execution of the data transfer statement or
during subsequent data transfer.  Should these conditions not
result in termination of the program then these conditions will
be detectable by the programmer via {\tt ERR=} and {\tt IOSTAT=}
specifiers in the matching {\tt WAIT} statement.
\end{quote}

Alter the paragraph at the end of 9.4.3 to read as follows:

\begin{quote}
Execution of the executable program is terminated if an error condition
occurs during execution or during subsequent data transfer
of an input/output statement that contains neither
an {\tt IOSTAT=} nor an {\tt ERR=} specifier.

Should an asynchronous data transfer statement cause the {\tt ERR} or
{\tt IOSTAT}
variables to be set then any matching
{\tt WAIT} statement will do the same.
\end{quote}

In section 9.4.4, alter operation 8 to read as follows:

\begin{quote}
\begin{itemize}

\item  (8) Cause any variables specified in the {\tt IOSTAT=},
{\tt SIZE=} and
{\tt ID=} specifiers to become defined.

\end{itemize}
\end{quote}

To section 9.4.4, add the following three paragraphs:

\begin{quote}
For asynchronous data transfers steps 1-8 correspond to both
the asynchronous data transfer statement and the matching {\tt WAIT}
statement.  Steps 4-7 may occur asynchronously with program
execution.  If an implementation does not support asynchronous
data transfers then steps 1-8 may be performed by the asynchronous
data transfer statement,  the matching {\tt WAIT} statement must still
be executed, the only effect being to return status information.

Any variable which appears as an {\em input-item} or {\em output-item}
in an asynchronous data transfer statement, or which is associated with
such a variable,
shall not be referenced, become defined, or become undefined
until the execution of the matching {\tt WAIT} statement.

Multiple outstanding asynchronous data transfer operations are allowed
but they must all be reads or
writes. No other I/O statements on the same unit are allowed until all
{\tt WAIT} requests are satisfied.
A {\tt WRITE} statement with an {\tt ID=} specifier must not specify both
the same unit and record number as any {\tt WRITE} statement with an {\tt ID=}
specifier for which the matching {\tt WAIT} statement has not been executed.
\end{quote}

\begin{users}
Note: we still permit left-to-right definition of the I/O list on a READ.
This means that a statement like
\CODE
READ(10,ID=IDNUM,REC=10) I,A(I)
\EDOC
is legal and has the same semantics as a synchronous READ.
\end{users}

In section 9, change ``and {\tt INQUIRE} statements'' to
``, {\tt INQUIRE}, and {\tt WAIT} statements''.

In section 9.6.1, Rule R924, add

\begin{quote}
                                                                         \BNF
inquire-spec             \IS  ASYNCH = scalar-default-char-variable
                                                                         \FNB
\end{quote}

\section{WAIT statement}
                                                                        \BNF

        WAIT statement \IS WAIT (wait-spec-list)
        wait-spec \IS ID = scalar-default-int-expr
                  \OR ERR = label
                  \OR IOSTAT= label
                  \OR DONE=scalar-default-logical-variable
                                                                        \FNB

\begin{constraints}
\item A {\em wait-spec-list} shall contain exactly one {\tt ID=} specifier
and at most one of each of the other specifiers.
\end{constraints}

The {\tt ERR=} and {\tt IOSTAT=} specifiers may only be present
if they were present in the matching asynchronous
data transfer statement.

The {\tt WAIT} statement terminates an asynchronous data transfer.
The {\tt IOSTAT=}, and {\tt ERR=} specifiers are described in
sections 9.4.1.4, 9.4.1.5 and 9.4.1.6, respectively.

The {\tt DONE=} specifier is optional. If present, the
{\em scalar-default-logical-variable} is set to {\tt .TRUE.} if the
asynchronous operation is complete, and to {\tt .FALSE.} if it is not complete.

The {\tt WAIT} statement causes the processor
to wait until the matching data transfer statement terminates,
either normally, or with an error condition. After execution
of the matching {\tt WAIT} statement, error conditions, control transfer,
data transfer, and the value of any {\tt IOSTAT=} variable are as if the
data transfer statement had been executed synchronously in place of the
matching {\tt WAIT} statement, and with the addition of any {\tt IOSTAT=}
and {\tt ERR=},
specifiers to the {\it io-control-spec-list} of the data transfer
statement.

If the {\tt DONE} specifier is present, and the returned value is
{\tt .FALSE.}, then one
or more matching {\tt WAIT} statement must be executed, until either the
{\tt DONE=} specifier is not present, or the returned value is {\tt .TRUE.}.

\begin{implementors}
Implementors may choose to implement any or all asynchronous I/O
synchronously. This essentially means using the {\tt ID=} clause on the
data transfer statement to store the results of the transfer, then
supplying the results to the matching WAIT statement.
\end{implementors}
---------------------------------------------------------------------------
To (un)subscribe to this list, send mail to [email-masked].
Leave the subject line blank, and in the body put the line
(un)subscribe <email-address>
---------------------------------------------------------------------------