The `%REF()' Construct
----------------------
%REF(ARG)
The `%REF()' construct specifies that an argument, ARG, is to be
passed by reference, instead of by value or descriptor.
`%REF()' is restricted to actual arguments in invocations of
external procedures.
Use of `%REF()' is recommended only for code that is accessing
facilities outside of GNU Fortran, such as operating system or
windowing facilities. It is best to constrain such uses to isolated
portions of a program--portions the deal specifically and exclusively
with low-level, system-dependent facilities. Such portions might well
provide a portable interface for use by the program as a whole, but are
themselves not portable, and should be thoroughly tested each time they
are rebuilt using a new compiler or version of a compiler.
Do not depend on `%REF()' supplying a pointer to the procedure being
invoked. While that is a likely implementation choice, other
implementation choices are available that preserve Fortran
pass-by-reference semantics without passing a pointer to the argument,
ARG. (For example, a copy-in/copy-out implementation.)
*Implementation Note:* Currently, `g77' passes all arguments (other
than variables and arrays of type `CHARACTER') by reference. Future
versions of, or dialects supported by, `g77' might not pass `CHARACTER'
functions by reference.
Thus, use of `%REF()' tends to be restricted to cases where ARG is
type `CHARACTER' but the called procedure accesses it via a means other
than the method used for Fortran `CHARACTER' arguments.
Note:Procedures (SUBROUTINE and FUNCTION), for detailed
information on how this particular version of `g77' passes arguments to
procedures.