ISO/IEC JTC1/SC22/WG5 N1912

             Changes to N1904 to create N1911

                     Bill Long, 9-April 2012


WG5 document N1904 was a candidate DTS for TS 29113, Further
Interoperability of Fortran with C. An informal WG5 Ballot, N1908,
resulted in comments documented in N1910. Those Ballot comments and
additional comments resulting from email discussions on the interop-tr
email list and the WG5 email list resulted in comments included in
this document.

The accumulation of these changes applied to N1904 resulted in an
updated DTS candidate document WG5/N1911.  Edit citations refer to
N1904.

Comments include the name of the commenter and source of the
comment. The commenters are:

Bill:      Bill Long,      Cray Inc. (USA) (TS editor)
John:      John Reid,      RAL       (UK)  (WG5 Convener)
Malcolm:   Malcolm Cohen,  NAG       (UK)  (Fortran standard editor)
Daniel	   Daniel Chen     IBM	     (Canada)
Reinhold:  Reinhold Bader, LRZ       (Germany)
Robert:    Robert Corbett, Oracle    (USA)
Nick:      Nick Maclaren,  Cambridge (UK)
Van:       Van Snyder,     NASA/JPL  (USA)

Some comments include explanatory text enclosed in { }.

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

1) Reinhold, Daniel, others (Ballot comments)

5.1 Assumed-type objects, Constraint C407a, insert "INTENT(OUT), "
before "POINTER".
Same edit in 9.4 Edits to clause 4.
{The INTENT(OUT) attribute requires that the dummy argument become
undefined, which is not a viable requirement for an assumed-type
variable.}

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

2) Reinhold (Ballot comment)

5.2 Assumed-rank objects, para following C535b, convert this paragraph
into a Note.
{Text is repeated elsewhere is the TS.  Ed: Similar Note in 6.7 of
F2008.}
{Ed: In 9.5, edit to 5.3.8.7, delete the sentence "The intrinsic
function RANK can be used to inquire about the rank of a data
object."}

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

3) Bill, John, Daniel, others (Ballot comments and emails)

5.3 ALLOCATABLE, OPTIONAL, and POINTER attributes, replace the current
C1255 with these constraints below. Same edit for the last edit in 9.7
and add new edit in 9.5.

"C1255 (R1230) If <proc-language-binding-spec> is specified for a
procedure, each dummy argument shall be an interoperable procedure
(15.3.7) or a variable that is interoperable (15.3.5, 15.3.6), assumed
shape, assumed rank, assumed type, of assumed character length, or has
the ALLOCATABLE or POINTER attribute. If <proc-language-binding-spec>
is specified for a function, the function result shall be an
interoperable scalar variable.

C1255a (R1230) A dummy argument of a procedure that has a
<proc-language-binding-spec> shall not have both the OPTIONAL and
VALUE attributes.

C1255b (R1230) A variable that is a dummy argument of a procedure that
has a <proc-language-binding-spec> shall be of interoperable type or
assumed type.

C524a A coarray shall not be a dummy argument of a procedure that has
a <proc-language-binding-spec>."

{The current text, with the reference to 15.3.5, prohibits ALLOCATABLE
or POINTER arguments to a BIND(C) procedure. Clearly not acceptable
for the TS.  The original focus of the modification to C1255 was to
remove the restriction on OPTIONAL arguments. That aspect is separated
into C1255b above to separate it from the restrictions on the types of
the arguments.}
{Ed: In sentence before C1255, change "is replaced by" to "is replaced
by the following three constraints. Between the C1255 constraints and
C524a, insert this sentence: "The following constraint is added to
subclause 5.3.6.1 of \Fortranstandard{}.".  Before C516, change "much
less restrictive constraint:" to "following, less restrictive
constraint.}
{Ed: Add a new edit to 9.5 for the added C524a constraint.}
{Ed: At the end of 9.7 replace the current edit for 12.6.2.2 with the
revised edit above.}

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

4) John (Email comment)

6.3 Argument association, p1, in the second sentence change "is
scalar" to "has rank zero", and in the third sentence change "is an
array" to "has rank greater than zero".
{In the case of assumed-rank arguments, the meaning of "scalar" is
unclear."

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

5) John (Ballot comment)

7.2 RANK(A), in the Example change "effective" to "actual".
Same edit in 9.8 Edits to clause 13.
{Use simpler, clearer term.}

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

6) Malcolm (Email comment) Bill (editing)

8.1 Removed restrictions...procedures, p6, change "with a prototype of
void (*funptr_name)()" to "void(*)()".
{Remove incorrect "prototype" and "funptr_name".}
{Make same edit in 9.9 penultimate edit.}

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

7) Malcolm (Email comment)

8.2 C descriptors, replace the second sentence with "Together with
library functions that have standard prototypes, it provides a means
for describing and manipulating Fortran data objects from within a C
function.".
{The current sentence omits the assumed-rank case, and is
unnecessarily detailed.}

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

8) Malcolm (Ballot comment)

8.3.1 Summary of contents, p1 After "The \cf{ISO_Fortran_binding.h}
heading file" change "contains the" to "shall contain"

{This is a requirement (on the processor) not a statement of fact.}

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

9) Malcolm (Ballot comment)

8.3.1 Summary of contents, p1, sentence 2 change "The contents of" to
"The types, macros, and functions declared in".
{It is physically impossible to use the "contents" of a header file to
allocate or deallocate anything.}

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

10) Malcolm (Email comment)

8.3.3 CFI_cdesc_t, replace the description of the elem_lem member of
CFI_cdesc_t with "If the object is scalar, the value is the storage
size in bytes of the object; otherwise, the value is the storage size
in bytes of an element of the object."  
{Avoids questions about whether the type for character is Fortran
character or C char.}

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

11) Malcolm (Email comment)

8.3.3 CFI_cdesc_t, Note 8.2, replace the contents of Note 8.2 with
"The value of elem_len for a Fortran CHARACTER object is equal to the
character length times the number of bytes of a single character of
that kind. If the kind is C_CHAR, this value will be equal to the
character length."
{Clarify the elem_len definition for the Fortran character case. Ed:
Changed the third "character" to lower case.}

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

12) Malcolm (Email comment)

8.3.3 CFI_cdesc_t, p1, After the second sentence, add a new sentence
"The values of these members of a structure of type CFI_cdesc_t that
is produced by the functions and macros specified in
\thistechnicalreport{}, or received by a C function when invoked by a
Fortran procedure, shall have the following properties."
{Clarify who is responsible for meeting the specs for the members.}

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

13) Malcolm (Email comment)

8.3.3 description of version, change "shall be set equal" to "The
value is equal".

8.3.3 description of rank, change "equal to" to "The value is equal
to".

8.3.3 description of type, change "equal to" to "The value is equal
to".

8.3.3 description of attribute, change "equal to" to "The value is
equal to"
{Use complete sentences.}

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

14) Malcolm (Email comment) Bill (Email comment)

In 8.3.3 CFI_cdesc_t, separate out the descriptions of the typedefs
from the descriptions of the structure members. Edits to implement:

8.3.3p1 append "The types CFI_attribute_t, CFI_rank_t, and CFI_type_t
are described in 8.3.4.  The type CFI_dim_t is described in 8.3.2."

8.3.3 description of "rank" member, delete the last sentence.

8.3.3 description of "type" member, delete the last sentence.

8.3.3 description of "attribute" member, delete the last sentence.

8.3.4 title: change "Macros" to "Macros and typedefs".

8.3.4p1 change "The macros described" to "The macros and typedefs
described", and change "each expands" to "each macro expands".

8.3.4p3 change "CFI_MAX_RANK" to "The CFI_MAX_RANK macro".  At end of
para append "CFI_rank_t is a typedef name for a standard integer type
capable of representing the largest supported rank."  {Note change
from "shall be" to "is" here.}

8.3.4p4 change "CFI_VERSION" to "The CFI_VERSION macro".

8.3.4p5 append "CFI_attribute_t is a typedef name for a standard
integer type capable of representing the values of the attribute
codes."

8.3.4, just before Table 8.2, add a new paragraph: "CFI_type_t is a
typedef name for a standard integer type capable of representing the
values for the supported type codes."

{Ed: Corresponding edits: In 8.3.2 CFI_dim_t, move the second sentence
to a new paragraph following 8.3.4 Note 8.3, and in its place in 8.3.2
insert "The type CFI_index_t is described in 8.3.4." At the end of
8.3.2p1 change ":" to ".".  At the beginning of each member
description in 8.3.2 insert "The value is".}

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

15) John (Email comment)

8.3.3 CFI_cdesc_t Change the second sentence to "It shall contain at
least the members described in the list that follows this paragraph."
{The first para of 8.3.3 reads awkwardly now that there is so much
text after its second sentence.}

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

16) Bill (Email comment) John (Email comment)

8.3.3 CFI_cdesc_t description of "version", change "is established,
and otherwise not changed" to "was established".
{The new test in 8.3.3 clarifies that this field would not change
anyway.}

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

17) Malcolm (Email comment) Bill {Editorial}

8.3.3 CFI_cdesc_t, dim[] member, second sentence change "the array
shall be" to "the \cf{dim} array is" and move this to be the first
sentence. Remove "\cf{dim}" from the original first (now second)
sentence.
{Reword to avoid making a requirement.}

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

18) Bill (Editorial)

8.3.3 CFI_cdesc_t p10, change "member of the descriptor" to "member of
the C descriptor".
{Consistently use "C descriptor".}

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

19) Robert (Email comment) Bill (Email comment)

8.3.4 Macros, p2, after first sentence add "The argument shall be an
integer constant expression with a value that is greater than or equal
to zero and less than or equal to CFI_MAX_RANK."
{Add restrictions on the argument to CFI_CDESC_T.}

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

20) John (Email comment)

8.3.4 Macros, para following Table 8.1, last sentence, delete "that is
scalar ... or assumed-size array".
{Companion to change in 8.2.}

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

21) Bill (Editorial)

8.3.4 Table 8.2, remove the entry for CFI_type_cfunptr 
{We only allow C descriptors to describe data objects.}

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

21) Malcolm (Ballot comment)

8.3.5.1 Functions/General p1 After "The" change "macro" to "macros"
{There are several macros defined by ISO_Fortran_binding.h.}

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

22) Malcolm (Ballot comment)

8.3.5.1 Functions/General p1 After "and functions described in" change
"this subclause" to "subclause 8.3"
{"this subclause" is 8.3.5.1, and it contains no macro or function!}

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

23) Malcolm (Ballot comment) 

8.3.5.1 Functions/General p3: at end of sentence change "as follows:"
to "as described in the following subclauses of 8.3.5."
{ISO guidelines require a complete sentence here.}

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

24) Nick (Email comment)

8.3.5.1 Functions/General, in the final paragraph, after "for these
functions" insert ", or equivalent macros," and at the end of the
paragraph add a this new sentence " It is unspecified whether the
functions defined by this header are macros or identifiers declared
with external linkage.  If a macro definition is suppressed in order
to access an actual function, the behavior is undefined."  Also,
delete the corresponding paragraph in 8.3.5.5 that begins "It is
unspecified ...".
{Allow all functions to be macros, remove redundant para for
CFI_establish.}
{Ed: Corresponding edit: In the first sentence of 8.3.1 change "and C
prototypes for the C macro and functions" to "and C function
prototypes or macro definitions for".}

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

25) Bill (Email comment) John (Email comment)

8.3.5.1 Functions/General, Move Note 8.9 in 8.3.5.5 to the end of
8.3.5.1 and changing its first line to "These functions are allowed to
be macros to provide extra implementation flexibility. For example,
CFI_establish could".
{With the edit above, all of the functions could be macros.}

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

26) Bill (Email comment)

8.3.5.3 CFI_allocate function, elem_len formal parameter description,
changed "value of elem_len ... kind" to "value of elem_len shall be
the storage size in bytes of an element of the object".

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

27) Bill (Editorial)

8.3.5.3 CFI_allocate, in the Example, change the array name "a" to
"A".
{Reduce confusion in first sentence.}
{Similar changes in CFI_address, CFI_deallocate, CFI_select_part.}

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

28) Bill (Email comment)

8.3.5.5 CFI_establish function, elem_lem formal parameter description,
change " or CFI_type_other, ... character length times the sizeof()
for the type" to ", CFI_type_other, or a Fortran character type, the
value of elem_len shall be greater than zero and equal to the storage
size in bytes of an element of the object".

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

29) Malcolm (Email comment)

8.3.5.5 CFI_establish, para following the extents argument
description, before the last sentence add a new sentence: "If
\cf{base_addr} is the C address of a Fortran data object, the
\cf{type} and \cf{elem_len} arguments shall be consistent with the
type and type parameters of the Fortran data object.".
{Disallow invalid type associations with pointers.}
{Ed: Corresponding edit: At the end of the paragraph change "The
properties of the object" to "The remaining properties of the
object". Since some of the properties are now discussed in the
previous sentence.}

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

30) Reinhold (Ballot comment)

8.3.5.5 Example 1, in the first sentence change "array to pass to" to
"array that can be passed to".
{Wording improvement. Changed 'which' to 'that'.}

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

31) Bill (Email comment)

8.3.5.8 CFI_select_part function, elem_len formal parameter description,
changed "value of elem_len ... kind" to "value of elem_len shall be
the storage size in bytes of an element of the object".

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

32) Nick (email discussion)

8.4 subclause title, change "Use of" to "Restrictions on".
{Better reflects the contents of the subclause.}

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

33) Malcolm (Ballot comment), edited

8.4 Use of C descriptors, at the end of p1 change "here" to "8.3.5".
{There are no functions "specified here".}
{Ed: added fix in same sentence: insert comma after "updated".}

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

34) Reinhold (Ballot comment)

8.4 Use of C descriptors, in second bullet, change "decriptor" to
"descriptor".
{Correct spelling error.}

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

35) Malcolm (Ballot comment) Bill, Nick (Email comments)

8.4 Note 8.11 Delete the final sentence beginning "C programmers..."
{Sentence is unrelated to the topic of the subclause.}

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

36) Malcolm (Ballot comment)

8.5 Restrictions on formal parameters, p3, 1st bullet point,
after "INTENT(IN)" change "argument" to "attribute".
{Wrong term.}

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

37) Reinhold and Malcolm (Ballot comments}

8.5 Restrictions on formal parameters, p4: Move the last paragraph of
8.5 to become the second paragraph of 8.3.5.1.
{Paragraph not related to restrictions on formal parameters, and is a
general statement about the functions in 8.3.5, so the "General"
subclause is a better location.  Wording not changed; see Malcolm
ballot comment.}

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

38) Malcolm (Ballot comment)

8.6 Restrictions on lifetimes, NOTE 8.12, please change "ary" to "x".  
{The name "ary" is confusingly similar to "array".}

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

39) John, Malcolm (Email comments)

8.6 Restrictions on lifetimes, Note 8.12, Add ",target :: " as an
attribute to the declaration in the first line of the code example.
{Allow that the actual argument might be the target of a lingering
pointer.}

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

40) Reinhold (Ballot comment)

8.6 NOTE 8.12, Change the NOTE's first sentence to "The following
    example illustrates how a C descriptor becomes undefined upon
    returning from a call to a C function."
{Wording improvement.}

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

41) Nick (Email comment)

8.6 Note 8.12, final sentence, change "Because" to "In addition, because".
{Clarify that the last sentence is a different issue from the previous
sentence.}

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

42) Bill (editorial)

9.4 Edits to clause 4, Constraint C407a, at the end change
"attributes" to "attribute and is not an explicit-shape array".
{Change text to match the corresponding text in 5.1.}

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

43) Bill (Email comment)

9.9 Edits to clause 15, I the edit {Before subclause 15.5} change
"8.3" to "8.2", "15.8" to "15.9", "15.5.1" to "15.6.1", "15.5.5" to
"15.6.5", and "15.9" to "15.10".  In the final edit in 9.9, change
"15.9.4" to "15.10.4".
{8.2 was omitted from the edits, but contains the definition of "C
descriptor", which seems central to this part of clause 15.}

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

44) Nick (Ballot comment)

All of the TS: Change "final procedures" to "final subroutines"
throughout.

Locations:  
6.3p2,  
8.3.4 para before Table 8.2, 
8.7 p5 bullet 2 and corresponding edit in 9.9.
{The term used in the standard is "final subroutine", not "final
procedure".}

============================