DIGITAL Fortran 90 uses the same argument-passing conventions as DIGITAL Fortran 77 on DIGITAL UNIX systems for non-pointer scalar variables and explicit-shape and assumed-size arrays.

When calling DIGITAL Fortran 90 subprograms, be aware that DIGITAL Fortran 90 expects to receive arguments the same way it passes them.

The main points about argument passing and function return values are as follows:

• Arguments are generally passed by reference. The address of the argument is passed.
  Unless explicitly specified otherwise (such as with the cDEC$ ATTRIBUTES directive or the %VAL built-in function), an argument contains the address of the data being passed, not the data itself.
  Assumed-shape arrays and deferred-shape arrays are passed by array descriptor.
  Arguments omitted by adding an extra comma (,) are passed as a zero by immediate value. OPTIONAL arguments that are not passed are also handled this way.
• Function return data is usually passed by immediate value (function return contains a value). Certain types of data (such as array-valued functions) are passed by other means.
  The value being returned from a function call usually contains the actual data, not the address of the data.
• Character variables, explicit-shape character arrays, and assumed-size character arrays are passed as arguments by reference along with an extra argument, called a "hidden length" argument, that gets passed by value after all actual arguments.
  The hidden length is an integer value. If two character scalar variables are passed, the argument list contains two extra hidden length arguments that respectively contain the length of the passed character arguments. Dummy arguments for character data can use an assumed length.
  When passing character arguments to a C routine as strings, the character argument is not automatically null-terminated by the compiler. To null-terminate a string from DIGITAL Fortran 90, use the CHAR intrinsic function or the null character escape sequence (described in the DIGITAL Fortran Language Reference Manual).
• External names have a trailing underscore (_) appended to their name and are in lowercase.
  The DIGITAL Fortran 90 compiler appends the underscore to any reference to an external procedure name, as well as DIGITAL Fortran 90 procedure declarations in the object file. This is mostly a concern when the program uses routines in DIGITAL Fortran 90 and C, as described in Section 11.4.2.

The arguments passed from a calling routine must match the dummy arguments declared in the called function or subroutine (or other procedure), as follows:

• Arguments are kept in the same position as they are specified by the user.
  The exception to same position placement is the use of argument keywords to associate dummy and actual arguments.
• Each corresponding argument or function return value must at least match in data type, kind, and rank, as follows:
  • The primary DIGITAL Fortran 90 intrinsic data types are character, integer, logical, real, and complex.
    To convert data from one data type to another, use the appropriate intrinsic procedures described in the DIGITAL Fortran Language Reference Manual.
    Also, certain attributes of a data item may have to match. For example, if a dummy argument has the POINTER attribute, its corresponding actual argument must also have the POINTER attribute Section 11.1.6).
  • You can use the kind parameter to specify the length of each numeric intrinsic type, such as INTEGER (KIND=8). For character lengths, use the LEN specifier, perhaps with an assumed length for dummy character arguments (LEN=*).
  • The rank (as number of dimensions) of the actual argument is usually the same (or less than) the rank of the dummy argument, unless an assumed-size dummy array is used.
    When using an explicit interface, the rank of the actual argument must be the same as the rank of the dummy argument.
    For example, when passing a scalar actual argument to a scalar dummy argument (no more than one array element or a nonarray variable), the rank of both is 0.
    You can pass an actual array to a dummy array of the same rank or you can pass an array section. If you use an assumed-shape array, the extents of the dummy array argument are taken from the actual array argument.
    Other rules which apply to passing arrays and pointers are described in Section 11.1.5, Section 11.1.6, and the DIGITAL Fortran Language Reference Manual.
• The means by which the argument is passed and received (passing mechanism) must match.
  By default, DIGITAL Fortran 90 arguments are passed by reference. (See Table 11-3 for information about passing arguments with the C property.)
  When calling functions or other routines that are intended to be called from another language (such as C), be aware that these languages may require data to be passed by other means, such as by value.
  Most DIGITAL Fortran 90 function return values are passed by value. Certain types of data (such as array-valued functions) are passed by other means.
  In most cases, you can change the passing mechanism of actual arguments by using the following DIGITAL extensions:
  • cDEC$ ATTRIBUTES directive (see Section 11.2.2)
  • Built-in functions (see Section 11.1.8)
• To explicitly specify the procedure (argument or function return) interface, provide an explicit interface.
  You can use interface blocks and modules to specify INTENT and other attributes of arguments.

For More Information:

• On passing arguments, function return values, and the contents of registers on DIGITAL UNIX systems, see the DIGITAL UNIX Calling Standard for Alpha Systems.
• On intrinsic data types, see Chapter 9 and the DIGITAL Fortran Language Reference Manual.
• On intrinsic procedures and attributes available for array use, see the DIGITAL Fortran Language Reference Manual.
• On explicit interfaces and when they are required, see the DIGITAL Fortran Language Reference Manual.
• On a DIGITAL Fortran 90 example program that uses an external subprogram and a module that contains a procedure interface block, see Example 1-3.

Certain arguments or function return values require the use of an explicit interface, including assumed-shape dummy arguments, pointer dummy arguments, and function return values that are arrays. This is discussed in the DIGITAL Fortran Language Reference Manual.

When passing arrays as arguments, the rank and the extents (number of elements in a dimension) should agree, so the arrays have the same shape and are conformable. If you use an assumed-shape array, the rank is specified and extents of the dummy array argument are taken from the actual array argument.

If the rank and extent (shape) do not agree, the arrays are not conformable. The assignment of elements from the actual array to the noncomformable (assumed-size or explicit-shape) dummy array is done by using array element sequence association. Using array element sequence associations is discussed in the DIGITAL Fortran Language Reference Manual.

Certain combinations of actual and dummy array arguments are disallowed.

For More Information:

• On the types of arrays and passing array arguments, see the DIGITAL Fortran Language Reference Manual.
• On explicit interfaces and when they are required, see the DIGITAL Fortran Language Reference Manual.
• On array descriptors, see Section 11.1.7.

Previous sections have discussed the case where the actual and dummy arguments have neither the POINTER attribute nor the TARGET attribute.

The argument passing rules of like type, kind, and rank (for conformable arrays) or array element sequence association (for noncomformable arrays) apply when:

• Both actual and dummy arguments have the POINTER attribute.
• Dummy arguments have the TARGET attribute.
• Both actual and dummy arguments have neither attribute.

You can specify an actual argument of type POINTER and a dummy argument of type POINTER. You must use an explicit interface that defines the dummy argument with the POINTER attribute in the code containing the actual argument. This ensures that the pointer is passed, rather than the array data itself.

However, if you specify an actual argument of type POINTER and do not specify an appropriate explicit interface (such as an interface block), it is passed as actual (target) data.

For More Information:

On using pointers and pointer arguments, see the DIGITAL Fortran Language Reference Manual.

11.1.7 DIGITAL Fortran 90 Array Descriptor Format

When using an explicit interface (by association or procedure interface block), DIGITAL Fortran 90 will generate a descriptor for the following types of dummy argument data structures:

• Pointers to arrays (array pointers)
• Allocatable arrays
• Assumed-shape arrays

To allow calling between DIGITAL Fortran 77 and DIGITAL Fortran 90, certain data structure arguments also supported by DIGITAL Fortran 77 do not use a descriptor, even when an appropriate explicit interface is provided. For example, since explicit-shape and assumed-size arrays are supported by both DIGITAL Fortran 77 and DIGITAL Fortran 90, a descriptor is not used.

However, for cases where the called routine needs the information in the DIGITAL Fortran 90 descriptor, declare the routine with an assumed-shape or pointer argument and an explicit interface.

The byte components of the DIGITAL Fortran 90 descriptor follow:

• Byte 0 contains a count of the number of dimensions (rank).
• Byte 1 should always contain a 1.
• Byte 2 contains the data type of the result, as follows:
  • 1 for INTEGER (KIND=1)
  • 2 for INTEGER (KIND=2)
  • 3 for INTEGER (KIND=4)
  • 4 for INTEGER (KIND=8)
  • 5 for LOGICAL (KIND=1)
  • 6 for LOGICAL (KIND=2)
  • 7 for LOGICAL (KIND=4)
  • 8 for LOGICAL (KIND=8)
  • 9 for REAL (KIND=4)
  • 10 for REAL (KIND=8)
  • 11 for REAL (KIND=16)
  • 12 for COMPLEX (KIND=4) or COMPLEX*8
  • 13 for COMPLEX (KIND=8) or COMPLEX*16
  • 14 for CHARACTER
  • 15 for RECORD
• Bytes 3 to 7 (inclusive) are reserved.
• Bytes 8 to 15 contain the element length for character data, in bytes.
• Bytes 16 to 23 contain the address of the first element of an array.
• Bytes 24 to 39 are reserved.
• The remaining bytes (40 to 207) contain information about each array dimension, as follows:
  • Bytes 40 to 63 contain dimension information for rank 1
  • Bytes 64 to 87 contain dimension information for rank 2
  • Bytes 88 to 111 contain dimension information for rank 3
  • Bytes 112 to 135 contain dimension information for rank 4
  • Bytes 136 to 159 contain dimension information for rank 5
  • Bytes 160 to 183 contain dimension information for rank 6
  • Bytes 184 to 207 contain dimension information for rank 7

Within the dimension information (24 bytes) for each rank:

• Bytes 0 to 7 contain the number of bytes between two successive elements in this dimension.
• Bytes 8 to 15 contain the upper bound.
• Bytes 16 to 23 contain the lower bound.

For example, consider the following declaration:

integer,target :: a(10,10) integer,pointer :: p(:,:) p => a(9:1:-2,1:9:3) call f(p) . . .

The descriptor for actual argument p would contain the following values:

• Byte 0 contains 2 (number of dimensions).
• Byte 1 contains 1 (always).
• Byte 2 contains 3 (data type of the result is the default INTEGER size, usually INTEGER (KIND=4)).
• Bytes 3 to 15 are reserved.
• Bytes 16 to 23 contain the address of the first element.
• Bytes 24 to 39 are reserved.
• Bytes 40 to 63 contain dimension information for rank 1, as follows:
  • Bytes 40 to 47 contain --8 (distance between elements)
  • Bytes 48 to 55 contain 5 (upper bound)
  • Bytes 56 to 63 contain 1 (lower bound)
• Bytes 64 to 87 contain dimension information for rank 2, as follows:
  • Bytes 64 to 71 contain 120 (distance between elements)
  • Bytes 72 to 80 contain 3 (upper bound)
  • Bytes 81 to 87 contain 1 (lower bound)
• Byte 87 is the last byte.

When a DIGITAL Fortran 90 program needs to call a routine written in a different language (or in some cases a Fortran 90 subprogram), there may be a need to use a form other the DIGITAL Fortran 90 default passing mechanisms. For example, numeric arguments may need to be passed by immediate value instead of by reference.

To change the DIGITAL Fortran 90 default mechanisms with the DIGITAL Fortran 90 built-in functions, use the following functions:

• To change how an argument is passed (default passing mechanism), use the %VAL or %REF built-in functions for specific arguments.
• To compute the address of a storage element as an integer value, use the %LOC built-in function in any arithmetic expression.

The %VAL or %REF functions can only be used as unparenthesized arguments in actual argument lists.

Instead of the DIGITAL Fortran 90 built-in functions, you can use the cDEC$ ATTRIBUTES directive to change the DIGITAL Fortran 90 default passing mechanisms for either an entire call or for individual arguments. (see Section 11.2.2).

11.1.8.1 Passing Addresses --- %LOC Function

The %LOC built-in function computes the address of a storage element as an INTEGER*8 (Alpha UNIX systems) value. You can then use this value in an arithmetic expression. It has the following form:

%LOC(arg)

The %LOC function is particularly useful for non-Fortran procedures that may require argument data structures containing the addresses of storage elements. In such cases, the data structures should be declared volatile to protect them from possible optimizations.

For More Information:

• On optimization and declaring volatile data, see Section 5.7.3.
• On the VOLATILE attribute, see the DIGITAL Fortran Language Reference Manual.

The %VAL function passes the argument list entry as a 64-bit immediate value on DIGITAL UNIX systems. It has the following form:

%VAL(arg)

The argument-list entry generated by the compiler is the value of the argument (arg). Because argument-list entries are eight bytes long, the argument value must be an INTEGER (including INTEGER*8), LOGICAL (including LOGICAL*8), or REAL (REAL*4 and REAL*8) constant, variable, array element, or expression.

If a COMPLEX (KIND=4) or COMPLEX (KIND=8) argument is passed by value, two REAL arguments (one contains the real part; the other the imaginary part) are passed by immediate value. If a COMPLEX parameter to a routine is specified as received by value (or given the C attribute), two REAL parameters are received and stored in the real and imaginary parts of the COMPLEX parameter specified.

If the value is a byte, word, or longword, it is sign-extended to eight bytes.

To produce a zero-extended value rather than a sign-extended value, use the ZEXT intrinsic function (see the DIGITAL Fortran Language Reference Manual).

11.1.8.3 Passing Arguments by Reference --- %REF Function

The %REF function passes the argument by reference. It has the following form:

%REF(arg)

The argument-list entry the compiler generates will contain the address of the argument, (arg). The argument value can be a record name, a procedure name, or a numeric or character expression, array, character array section, or array element. In DIGITAL Fortran 90, passing by reference is the default mechanism for numeric values, so the %REF call is usually not needed. Passing character arrays with %REF caused the hidden length to be omitted.

11.1.8.4 Examples of Argument Passing Built-in Functions

The following examples show the use of the argument list built-in functions:

• The first constant is passed by reference. The second constant is passed by immediate value:

  CALL SUB(2,%VAL(2))

• The first character variable is passed by address and hidden length. The second character variable is passed by reference (no hidden length):

  CHARACTER(LEN=10) A,B CALL SUB(A,%REF(B))

• Both arrays are passed by reference:

  INTEGER IARY(20), JARY(20) CALL SUB(IARY,JARY)

For an example of passing integer data by value (using %VAL) and by reference (default) to a C function, see Section 11.4.7.

11.2 Using the cDEC$ ALIAS and cDEC$ ATTRIBUTES Directives

This section provides reference information about the following directives:

• The cDEC$ ALIAS (or !DEC$ ALIAS or *DEC$ ALIAS) directive lets you specify a name for an external subprogram that differs from the name used by the calling subprogram.
• The cDEC$ ATTRIBUTES (or !DEC$ ATTRIBUTES or *DEC$ ATTRIBUTES) directive lets you specify the properties for external data objects and procedures. This includes using C language rules, specifying how an argument is passed (passing mechanism), and specifying an alias for an external routine.

DIGITAL Fortran 90 supports the cDEC$ ALIAS directive in the same manner as DIGITAL Fortran 77. Use this directive to specify that the external name of an external subprogram is different from the name by which the calling procedure references it.

The syntax is:

cDEC$ ALIAS internal-name, external-name

The internal-name is the name of the subprogram as used in the current program unit.

The external-name is either a quoted character constant (delimited by single quotation marks) or a symbolic name.

If external-name is a quoted character constant, the value of that constant is used as the external name for the specified internal name. The character constant is used as it appears, with no modifications for case or addition or removal of punctuation characters. The default for the DIGITAL Fortran 90 compiler is to force the name into lowercase and append an underscore unless directed otherwise.

If external-name is a symbolic name, the symbolic name (in lowercase) is used as the external name for the specified internal name and an underscore is appended. Any other declaration of the specified symbolic name is ignored for the purposes of the ALIAS directive.

The DIGITAL UNIX linker may have restrictions on what appears in an external name and whether external names are case sensitive.

For example, in the following program (free source form):

PROGRAM ALIAS_EXAMPLE !DEC$ ALIAS ROUT1, 'ROUT1A' !DEC$ ALIAS ROUT2, 'routine2_' !DEC$ ALIAS ROUT3, rout3A CALL ROUT1 CALL ROUT2 CALL ROUT3 END PROGRAM ALIAS_EXAMPLE

The three calls are to external routines named ROUT1A, routine2_, and rout3a_. Because rout3A is not in single quotation marks (character constant), a trailing underscore is added (DIGITAL Fortran adds a trailing underscore to external names on UNIX systems unless directed otherwise) and the letter A becomes a lowercase a.

This feature can be useful when porting code systems where different routine naming conventions are in use. By adding or removing the cDEC$ ALIAS directive, you can specify an alternate routine name without recoding the application.

The cDEC$ ALIAS and cDEC$ ATTRIBUTES ALIAS directives are synonymous.

11.2.2 The cDEC$ ATTRIBUTES Directive

Use the cDEC$ ATTRIBUTES directive to specify properties for data objects and procedures. These properties let you specify how data is passed and the rules for invoking procedures. The cDEC$ ATTRIBUTES directive is intended to simplify mixed-language calls with DIGITAL Fortran 90 routines written in C or Assembler. The STDCALL keyword is synonymous with the C keyword on DIGITAL UNIX systems.

The cDEC$ ATTRIBUTES directive takes the following form:

cDEC$ ATTRIBUTES att [,att]... :: object [,object]...

In this form:

c

Is the letter or character (c, C, *, !) that introduces the directive (see the DIGITAL Fortran Language Reference Manual).

att

Is one of the keywords listed in the DIGITAL Fortran Language Reference Manual. For example, C, ALIAS, REFERENCE, or VALUE.

object

Is the name of a data object used as an argument or procedure. Only one object is allowed when using the C and ALIAS properties.

The DIGITAL Fortran Language Reference Manual) shows valid combinations of properties with the various types of objects.

The ATTRIBUTES options C, STDCALL, REFERENCE, VALUE, and VARYING all affect the calling convention of routines.

By default, Fortran passes all data by reference (except the hidden length argument of strings, which is a special case). If the C or STDCALL option is used, the default changes to passing almost all data by value except arrays.

In addition to the calling-convention options C and STDCALL, you can also specify argument options, VALUE and REFERENCE, to pass arguments by value or by reference, regardless of the calling convention option. Arrays can only be passed by reference.

Table 11-1 summarizes the effect of the most common Fortran calling-convention directives.

Table 11-1 Calling Conventions for ATTRIBUTES Options

Arguments	Default	C or STDCALL	C or STDCALL with REFERENCE
Scalar	Reference	Value	Reference
Scalar [value]	Value	Value	Value
Scalar [reference]	Reference	Reference	Reference
String	Reference, Len: End	String (1:1)	Reference, Len: End
String [value]	Error	String(1:1)	String(1:1)
String [reference]	Reference, No Len	Reference: No Len	Reference: No Len
Array	Reference	Reference	Reference
Array [value]	Error	Error	Error
Array [reference]	Reference	Reference	Reference
Derived type	Reference	Value, size dependent	Reference
Derived type [value]	Value, size dependent	Value, size dependent	Value, size dependent
Derived type [reference]	Reference	Reference	Reference
F90 Pointer	Descriptor	Descriptor	Descriptor
F90 Pointer [value]	Error	Error	Error
F90 Pointer [reference]	Descriptor	Descriptor	Descriptor

The terms used in Table 11-1 mean the following:

Term	Description
[value]	Assigned to the VALUE property
[reference]	Assigned to the REFERENCE property
Value	The argument value is pushed on the stack. All values are padded to the next 8-byte boundary.
Reference	The 8-byte argument address is pushed on the stack.
Len: End	The length of the string is pushed (by value) on the stack after all of the other arguments.
No Len	The length of the string is not available to the called procedure.
String(1:1)	For string arguments, the first character is converted to INTEGER(KIND=8) as in ICHAR(string(1:1)) and pushed onto the stack by value.
Error	Produces a compiler error.
Descriptor	8-byte address of the array descriptor.
Size dependent	Derive-type arguments specified by value are passed as follows: Arguments of 1 to 4 bytes are passed by value Arguments of 5 to 8 bytes are passed in two registers Arguments of more than 8 bytes provide value semantics by passing a temporary storage address by reference.