| Previous | Contents | Index |
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.
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.
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.
| Register | Use |
|---|---|
| R0 | Function value return registers; also see F0, F1 |
| R1 | Conventional scratch register |
| R2-R15 | Conventional saved registers |
| R16-R21 | Argument registers (one register per argument, additional arguments are placed on the stack) |
| R22-R24 | Conventional scratch registers |
| R25 | Argument information (AI); contains argument count and argument type |
| R26 | Return address (RA) register |
| R27 | Procedure value (PV) register |
| R28 | Volatile scratch register |
| R29 | Frame pointer (FP) |
| R30 | Stack pointer (SP) |
| R31 | Read As Zero/Sink (RZ) register |
| PC | Program counter (PC), a special register that addresses the instruction stream, which is not accessible as an integer register |
| F0, F1 | Function value return registers (F1 is used for the imaginary part of COMPLEX) |
| F2-F9 | Conventional saved registers |
| F10-F15 | Conventional scratch registers |
| F16-F21 | Argument registers (one per argument, additional arguments are placed on the stack) |
| F22-F30 | Conventional scratch registers |
| F31 | Read As Zero/Sink (RZ) register |
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.
| Data Type | Return Method |
|---|---|
|
R0 |
| REAL (KIND=4) | F0 |
| REAL (KIND=8) | F0 |
| REAL (KIND=16) | F0 and F1 |
|
COMPLEX (KIND=4)
(COMPLEX*8) |
F0 (real part), F1 (imaginary part) |
|
COMPLEX (KIND=8)
(COMPLEX*16) |
F0 (real part), F1 (imaginary part) |
|
COMPLEX (KIND=16)
(COMPLEX*32) |
In addition to the arguments, an entry is added to the beginning of the argument list. This additional entry contains the address of the character string descriptor. At run time, before the call, the calling program allocates enough storage to contain the result and places the storage address in the descriptor. |
| Character | In addition to the arguments, an entry is added to the beginning of the argument list. This additional entry contains the address of the character string descriptor. At run time, before the call, the calling program allocates enough storage to contain the result and places the storage address in the descriptor. |
| Pointers | R0 contains the address of the array descriptor (see Section 10.2.6). |
|
Assumed-shape arrays,
Deferred-shape arrays |
R0 contains the address of the array descriptor (see Section 10.2.5). |
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.
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.
| Facility Prefix | Types of Tasks Performed |
|---|---|
| CVT$ | Library routines that handle floating-point data conversion |
| DTK$ | DECtalk routines that are used to control HP's DECtalk device |
| LIB$ |
Library routines that:
Obtain records from devices |
| MATH$ | Mathematics routines that perform arithmetic, algebraic, and trigonometric calculations |
| OTS$ | General-purpose routines that perform such tasks as data type conversions as part of a compiler's generated code |
| PPL$ | Parallel processing routines that help you implement concurrent programs on single-CPU and multiprocessor systems |
| SMG$ | Screen-management routines that are used in designing, composing, and keeping track of complex images on a video screen |
| STR$ | String manipulation routines that perform such tasks as searching for substrings, concatenating strings, and prefixing and appending strings |
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.
| Group | Types of Tasks Performed |
|---|---|
| AST | Allows processes to control the handling of ASTs |
| Change Mode | Changes the access mode of particular routines |
| Condition Handling | Designates condition handlers for special purposes |
| Event Flag | Clears, sets, reads, and waits for event flags, and associates with event flag clusters |
| Input/Output | Performs I/O directly, without going through OpenVMS RMS |
| Lock Management | Enables processes to coordinate access to shareable system resources |
| Logical Names | Provides methods of accessing and maintaining pairs of character string logical names and equivalence names |
| Memory Management | Increases or decreases available virtual memory, controls paging and swapping, and creates and accesses shareable files of code or data |
| Process Control | Creates, deletes, and controls execution of processes |
| Process Information | Returns information about processes |
| Security | Enhances the security of OpenVMS systems |
| Timer and Time Conversion | Schedules events, and obtains and formats binary time values |
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.
| Example 10-3 Use of LIB$GET_VM and POINTER |
|---|
! 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.
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:
|
SYS$service-name(arg,...,arg) |
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:
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:
|
INCLUDE '(library-module-name)' |
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.
| Previous | Next | Contents | Index |