HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

The EXTERN property specifies that a variable is allocated in another source file. EXTERN can be used in global variable declarations, but it must not be applied to dummy arguments.

You must use EXTERN when accessing variables declared in other languages.

The VARYING directive allows a variable number of calling arguments. If VARYING is specified, the C property must also be specified.

When using the VARYING directive, either the first argument must be a number indicating how many arguments to process, or the last argument must be a special marker (such as -1 ) indicating it is the final argument. The sequence of the arguments, and types and kinds, must be compatible with the called procedure.

For More Information:

See the HP Fortran for OpenVMS Language Reference Manual.

10.4.2.5 ADDRESS64 Property

Specifies that the object has a 64-bit address. This property can be specified for any variable or dummy argument, including ALLOCATABLE and deferred-shape arrays. However, variables with this property cannot be data-initialized.

It can also be specified for COMMON blocks or for variables in a COMMON block. If specified for a COMMON block variable, the COMMON block implicitly has the ADDRESS64 property.

ADDRESS64 is not compatible with the AUTOMATIC attribute.

For More Information:

• On requirements and the use of 64-bit virtual addresses, see the online release notes.
• On the memory layout of process and system memory, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.
• On passing arguments, argument types, function return values, and the contents of registers on OpenVMS systems, see the HP OpenVMS Calling Standard.
• On HP Fortran intrinsic data types, see Chapter 8.
• On the HP Fortran language, see the HP Fortran for OpenVMS Language Reference Manual.
• On the HP C language, see the HP C Language Reference Manual.
• On the CC command, see the HP C User's Guide for OpenVMS Systems.

Programs compiled by the HP Fortran compiler conform to the standard defined for OpenVMS procedure calls (see the OpenVMS Programming Interfaces: Calling a System Routine and HP OpenVMS Calling Standard). This standard prescribes how registers and the system-maintained call stack can be used, how function values are returned, how arguments are passed, and how procedures receive and return control.

When writing routines that can be called from HP Fortran programs, you should give special consideration to the argument list descriptions in Section 10.5.3.

10.5.1 Register and Stack Usage

For information about register and stack usage on I64, see the HP OpenVMS Calling Standard.

10.5.1.1 Register and Stack Usage on Alpha

The Alpha architecture provides 32 general purpose integer registers (R0-R31) and 32 floating-point registers (F0-F31), each 64 bits in length. The OpenVMS Programming Interfaces: Calling a System Routine defines the use of these registers, as listed in Table 10-2.

A stack is defined as a LIFO (last-in/first-out) temporary storage area that the system allocates for every user process.

Each time you call a routine, the system places information on the stack in the form of procedure context structures, as described in the HP OpenVMS Calling Standard.

10.5.2 Return Values of Procedures

A procedure is an HP Fortran subprogram that performs one or more computations for other programs. Procedures can be either functions or subroutines. Both functions and subroutines can return values by storing them in variables specified in the argument list or in common blocks.

A function, unlike a subroutine, can also return a value to the calling program by assigning the value to the function's name. The method that function procedures use to return values depends on the data type of the value, as summarized in Table 10-3.

For More Information:

• On HP Fortran array descriptors, see Section 10.2.7.
• On defining and invoking subprograms, see the HP Fortran for OpenVMS Language Reference Manual.

Use an argument list to pass information to a routine and receive results.

The HP OpenVMS Calling Standard defines an argument list as an argument item sequence, consisting of the first six arguments occupying six integer and six floating-point registers (R16-R21 and F16-F21), with additional arguments placed on the stack. The argument information is contained in R25 (AI register). The stack pointer is contained in R30. For more details on argument lists, see the HP OpenVMS Calling Standard.

Memory for HP Fortran argument lists and for OpenVMS Alpha descriptors is allocated dynamically on the stack.

OpenVMS Alpha descriptors are generated from the use of the %DESCR function or by passing CHARACTER data, Fortran 90 pointers, and certain types of arrays (see Section 10.2.7).

Omitted arguments---for example, CALL X(A, ,B)---are represented by an argument passed by value that has a value of zero. This is an HP extension to the Fortran 90 standard.

Fortran optional arguments (OPTIONAL attribute) are also represented by an argument passed by value that has a value of zero.

For More Information:

On using Fortran language standards to specify arguments, see the HP Fortran for OpenVMS Language Reference Manual.

10.6 OpenVMS System Routines

System routines are OpenVMS routines that perform common tasks, such as finding the square root of a number or allocating virtual memory. You can call any system routine from your program, provided that HP Fortran supports the data structures required to call the routine (in a FORSYSDEF library module) or you define them yourself.

The system routines used most often are OpenVMS Run-Time Library routines and system services. System routines are documented in detail in the VMS Run-Time Library Routines Volume and the HP OpenVMS System Services Reference Manual.

10.6.1 OpenVMS Run-Time Library Routines

The OpenVMS Run-Time Library provides commonly-used routines that perform a wide variety of functions. These routines are grouped according to the types of tasks they perform, and each group has a prefix that identifies those routines as members of a particular OpenVMS Run-Time Library facility. Table 10-4 lists all of the language-independent Run-Time Library facility prefixes and the types of tasks each facility performs.

System services are system routines that perform a variety of tasks, such as controlling processes, communicating among processes, and coordinating I/O.

Unlike the OpenVMS Run-Time Library routines, which are divided into groups by facility, all system services share the same facility prefix (SYS$). However, these services are logically divided into groups that perform similar tasks. Table 10-5 describes these groups.

The basic steps for calling routines are the same whether you are calling a routine written in HP Fortran, a routine written in some other OpenVMS language, a system service, or an HP Fortran RTL routine.

To call a subroutine, use the CALL statement.

To call a function, reference the function name in an expression or as an argument in another routine call.

In any case, you must specify the name of the routine being called and all non-optional arguments required for that routine. Make sure the data types and passing mechanisms for the actual arguments you are passing coincide with those declared in the routine. (See Table 10-6 for information on OpenVMS data types or OpenVMS Programming Interfaces: Calling a System Routine for data types needed for mixed language programming.)

If you do not want to specify a value for a required parameter, you can pass a null argument by inserting a comma (,) as a placeholder in the argument list. If the routine requires any passing mechanism other than the default, you must specify the passing mechanism in the CALL statement or the function call.

Example 10-3 illustrates calling an OpenVMS RTL LIB$ routine. This example uses the LIB$GET_VM RTL routine and the Compaq Fortran 77 POINTER statement to allocate memory for an array, and uses HP extensions (POINTER statement and LIB$ routine) to allocate virtual memory.

! Program accepts an integer and displays square root values

  INTEGER (KIND=4) N
  READ (5,*) N            ! Request typed integer value
  CALL MAT(N)
  END

! Subroutine MAT uses the typed integer value to display the square
! root values of numbers from 1 to N (the typed number)

  SUBROUTINE MAT(N)
  REAL I(1000)           ! Fixed 1000 dimension allows bounds checking
  INTEGER SIZE,STATUS
  POINTER (P,I)          ! Compaq Fortran 77 POINTER statement establishes
                         ! P as the pointer and array variable I as the
                         ! pointee. P will receive memory base address
                         ! from LIB$GET_VM.

  SIZE=SIZEOF(I(1)) * N  ! Array I contains values calculated in loop below.
                         ! Intrinsic SIZEOF returns size of memory
                         ! to allocate.

  STATUS = LIB$GET_VM(SIZE,P)    ! Allocate memory
  IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

  DO J=1,N
     I(J) = SQRT(FLOAT(J))   ! Intrinsic FLOAT converts integer to REAL.
  ENDDO
  TYPE *, (I(J),J=1,N)       ! Display calculated values

  STATUS = LIB$FREE_VM(SIZE,P)   ! Deallocate memory
  IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

  END SUBROUTINE MAT

The following commands show how to compile, link, and run the program and how it displays the square root of numbers from 1 to 4 during execution:

$ FORTRAN SQUARE_ROOT
$ LINK SQUARE_ROOT
$ RUN SQUARE_ROOT
4
   1.000000       1.414214       1.732051       2.000000

The call to LIB$GET_VM as a function reference allocates memory and returns the starting address in variable P. The return status (variable STATUS) is tested to determine whether an error should be signaled using a subroutine call to LIB$SIGNAL, passing the value of the variable status (not its address) using the %VAL built-in function.

For More Information:

• On intrinsic procedures (such as FLOAT, SQRT, and SIZEOF) and the HP Fortran language, see the HP Fortran for OpenVMS Language Reference Manual.
• On the %VAL built-in function, see Section 10.3.3.
• On an example of memory allocation using Fortran 90 standard-conforming allocatable arrays, see the HP Fortran for OpenVMS Language Reference Manual.

You can invoke system services in an HP Fortran program with a function reference or a subroutine CALL statement that specifies the system service you want to use. To specify a system service, use the form:

You pass arguments to the system services according to the requirements of the particular service you are calling; the service may require an immediate value, an address, the address of a descriptor, or the address of a data structure. Section 10.8.4 describes the HP Fortran syntax rules for each of these cases. See the HP OpenVMS System Services Reference Manual for a full definition of individual services.

The basic steps for calling system services are the same as those for calling any external routine. However, when calling system services (or Run-Time Library routines), additional information is often required. The sections that follow describe these requirements.

10.8.1 Obtaining Values for System Symbols

OpenVMS uses symbolic names to identify the following values or codes for system services:

• Return status values are used for testing the success of system service calls.
• Condition values are used for error recovery procedures (see Chapter 14).
• Function codes are the symbolic values used as input arguments to system service calls.

The values chosen determine the specific action performed by the service.

The HP OpenVMS System Services Reference Manual describes the symbols that are used with each system service. The HP OpenVMS I/O User's Reference Manual describes the symbols that are used with I/O-related services.

The HP Fortran symbolic definition library FORSYSDEF contains HP Fortran source definitions for related groups of system symbols. Each related group of system symbols is stored in a separate text library module; for example, the library module $IODEF in FORSYSDEF contains PARAMETER statements that define the I/O function codes.

The library modules in FORSYSDEF correspond to the symbolic definition macros that OpenVMS MACRO programmers use to define system symbols. The library modules have the same names as the macros and contain HP Fortran source code, which is functionally equivalent to the MACRO source code. To determine whether you need to include other symbol definitions for the system service you want to use, refer to the documentation for that particular system service. If the documentation states that values are defined in a macro, you must include those symbol definitions in your program.

For example, the description for the flags argument in the SYS$MGBLSC (Map Global Section) system service states that "Symbolic names for the flag bits are defined by the $SECDEF macro." Therefore, when you call SYS$MGBLSC, you must include the definitions provided in the $SECDEF macro.

Library module $SYSSRVNAM in FORSYSDEF contains declarations for all system-service names. It contains the necessary INTEGER and EXTERNAL declarations for the system-service names. (The library module, once extracted from FORSYSDEF.TLB, also contains comments describing the arguments for each of the system services.) Also, library module $SSDEF contains system-service return status codes and is generally required whenever you access any of the services.

The library modules in FORSYSDEF contain definitions for constants, bit masks, and data structures. See Section 10.8.4.4 for a description of how to create data structure arguments in HP Fortran. Refer to Appendix E for a list of library modules that are in FORSYSDEF.

You can access the library modules in the FORSYSDEF library with the INCLUDE statement, using the following format:

The notation library-module-name represents the name of a library module contained in FORSYSDEF. The library FORSYSDEF is searched if the specified library module was not found in a previously searched library.