Using HP Fortran 90 directives

HP Fortran 90 provides a number of compiler directives that are useful for controlling certain functions (for example, optimization) within the source file. Table 9-1 “HP Fortran 90 directives” lists and briefly describes these directives; they are listed in the order in which they appear in the sections below.

Table 9-1 HP Fortran 90 directives

Directive	Function
`$HP$ ALIAS`	Associates the name of a subroutine, function, entry, or common block with an external name.
`$HP$ CHECK_OVERFLOW`	Generates code to trap integer overflows.
`$HP$ LIST`	Controls output of source lines in listing file.
`$HP$ OPTIMIZE`	Controls optimization within the source file.

In files that use free format, directives must start with the comment character !. In fixed format, they must start with the comment character C, *, or ! in column 1. Keywords and any arguments must be delimited by at least one space character, as in the following:

!$HP$ OPTIMIZE ON

Using the comment character as the directive prefix ensures that, unless the compiler is specifically looking for the directive, it is otherwise treated as a comment and ignored.

The following sections describe each of the HP Fortran 90 directives.

$HP$ ALIAS

The ALIAS directive associates the name of a subroutine, function, entry, or common block with an external name and specifies the parameter-passing conventions of routines written in other languages.

Syntax

!$HP$ ALIAS name [= external-name] [(arg-pass-mode-list)]

name

is the name used by the program to refer to a subroutine, function, or procedure entry point—but not to an internal subroutine. If name is enclosed by slashes, it is a common block name.

external-name

is a character constant that specifies a standard symbolic name.

arg-pass-mode-list

is used only when name is that of a procedure that takes arguments. The items in the list specify how the corresponding actual argument are to be passed. The items can be either of the following built-in functions:

%VAL: pass the value of the actual argument
%REF: pass the address of the actual argument

There must be as many items in the list as there are arguments in the procedure, they must be separated by commas, and they must correspond positionally to the arguments.

Description and restrictions

The $HP$ ALIAS directive serves two purposes:

It provides a way to associate the name used by your program when referring to a subroutine, function, entry, or common block with a distinct external name. This feature is especially useful when you want to access a variety of different graphics device drivers from the same source code so that different hardware configurations can be supported.
When used in conjunction with the %VAL and %REF built-in functions, it provides a way to direct the compiler to use the appropriate parameter passing conventions to communicate with routines written in other high-level languages.

external-name should never conflict with the name of an HP-UX system routine (described in sections 2 and 3 of the HP-UX Reference) or with a Fortran 90 library routine (for example, OPEN, READ, or CLOSE). The $HP$ ALIAS directive applies to subroutines, entries, and functions that are used externally. It does not apply to the main program unit.

%VAL is a built-in function that specifies that the value of the actual argument is to be passed to the called procedure. You can use this parameter with all types of arguments. However, when used with a procedure name, it has no effect; a pointer to the procedure is still passed.

%REF specifies that the address of the actual argument is to be passed to the called procedure. For non-character arguments, this is the default. For character arguments, %REF disables the passing of the hidden length parameter.

When %VAL and %REF are used with the CALL statement, they override the specification in the $HP$ ALIAS directive. For detailed information about these built-in functions and their use in the CALL statement, see the HP Fortran 90 Programmer's Reference..

Note the following restrictions:

Attempts to redefine $HP$ ALIAS names generate warning messages.
The compiler always uses external-name exactly as it is entered. No case transformations occur, and no underscore is appended. The +ppu and +uppercase compile-line options do not apply to external names specified by the $HP$ ALIAS directive; see Chapter 13 for information about these options.

Local and global usage

The $HP$ ALIAS directive can be used either locally or globally, as follows:

The $HP$ ALIAS directive has local application only—that is, its effect is limited to a particular program unit—if it appears within the boundaries of that program unit. To have local application only, the directive must appear after any PROGRAM, SUBROUTINE, or FUNCTION statement and before the first occurrence of name in the target program unit.
The $HP$ ALIAS directive has global application—that is, it applies to all subsequent program units—if it appears outside and before the boundaries of those program units to which it is to apply.

Examples

The $HP$ ALIAS directive is especially useful when calling a routine in a language that uses different conventions than Fortran. The following examples illustrate how to use the $HP$ ALIAS directive to resolve differences with:

Case sensitivity
Argument-passing conventions
Strings

Case sensitivity

Names in HP Fortran 90 are not case sensitive; that is, the compiler converts all names to lowercase. This means that if you reference a routine in a language that is case sensitive and the routine name contains uppercase letters, a call to that routine in HP Fortran 90 will result in an unresolved reference—unless you use the $HP$ ALIAS directive to redefine the name in all lowercase letters, as in the following example:

!$HP$ ALIAS printnames = "PrintNames"

Argument-passing conventions

By default, HP Fortran 90 assumes that all parameters in a subroutine or function call are passed by reference; that is, the call passes the addresses of the parameters, not their values. On the other hand, C code assumes that parameters are passed by value; that is, the current value of the actual parameter is passed to the called routine. Without the $HP$ ALIAS directive, it would be difficult to call a C routine from a Fortran program.

For example, suppose you want to call the system routine calloc (see the malloc(3C) man page) to obtain dynamic memory. The man page describes the calling sequence as:

char *calloc(unsigned nelem, unsigned elsize);

It would be difficult, using standard Fortran 90 constructs, to provide actual parameters corresponding to nelem and elsize because HP Fortran 90 always passes addresses. The $HP$ ALIAS directive can solve this problem by directing the compiler to generate call-by-value actual parameters:

!$HP$ ALIAS calloc(%VAL, %VAL)

Strings

Programs written in C expect strings to be terminated with the null character ('\0'). But HP Fortran 90 programs pass a hidden length parameter to indicate the end of a string argument. Thus, if you want to pass a string from HP Fortran 90 to a C language function, you must explicitly append the null to the string and suppress the hidden length parameter. The $HP$ ALIAS directive enables you to pass the string from Fortran to C. For example, consider the following routine:

Example 9-1 pr_str.c

void c_rout(char *s)
{
  printf("%s\n", s);
}

The ALIAS directive in the following program enables the string to be passed to c_rout:

Example 9-2 pass_str.f90

PROGRAM main
!$HP$ ALIAS c_rout(%REF)
  CHARACTER(LEN=10) name
  name = "Charlie"
! Append a null to the string so that C can handle it properly
  CALL c_rout(name//char(0))
END PROGRAM main

Here are the command lines to compile and link both files, and to execute the program, along with the output from a sample run:

$ cc -Aa -c pr_str.c
$ f90
pass_str.f90 pr_str.o
$ a.out
Charlie

For more information

For detailed information about the %REF and %VAL built-in functions, see the HP Fortran 90 Programmer's Reference.

$HP$ CHECK_OVERFLOW

The $HP$ CHECK_OVERFLOW directive generates code to trap when an overflow occurs in integer arithmetic. By default, integer overflow is ignored.

Syntax

!$HP$ CHECK_OVERFLOW INTEGER [ON | OFF]

ON: causes the compiler to generate code to trap integer overflow exceptions.
OFF: causes the compiler not to generate code to trap integer overflow exceptions.

Description and restrictions

If you use $HP$ CHECK_OVERFLOW with the ON statement, you can cause your program to ignore the overflow, abort on the overflow, or branch to a trap subroutine. If this directive is not used, the ON statement has no effect on integer overflow errors.

This directive can appear anywhere in your program. It stays in effect until a subsequent $HP$ CHECK_OVERFLOW directive changes the status.

For more information

For more information about the ON statement $HP$ CHECK_OVERFLOW directive, see Chapter 10 and the HP Fortran 90 Programmer's Guide.

$HP$ LIST

The $HP$ LIST directive turns on or off the inclusion of subsequent source lines in the listing output.

Syntax

!$HP$ LIST [ON | OFF]

ON: enables the inclusion of source lines in the listing file.
OFF: disables the inclusion of source lines in the listing file.

Description and restrictions

The $HP$ LIST directive controls which source lines are output to the listing file. This directive is effective only when the source files are compiled with the +list option. It may appear anywhere in the source file.

If the $HP$ LIST OFF directive occurs in a file that is compiled with the +list option, the listing will contain everything in the source file up through the directive. The $HP$ LIST OFF directive applies to the rest of the file, or until a $HP$ LIST ON directive is encountered.

Example

The $HP$ LIST directive is especially useful for disabling the listing of include files, as in the following example:

!$HP$ LIST OFF
INCLUDE "/my_stuff/some_generic_declarations.h"
!$HP$ LIST ON

For more information

For information about the +list option, see Chapter 13.

$HP$ OPTIMIZE

The $HP$ OPTIMIZE directive enables or disables the level of optimization that was specified on the compile line.

Syntax

!$HP$ OPTIMIZE [ON | OFF]

ON: enables the level of optimization specified on the compile line.
OFF: disables the level of optimization specified on the compile line.

This directive is effective for all program units that follow it in your program. It should therefore be placed outside and before the program units it is to affect. If you insert this directive inside a program unit, it will have no effect on that program unit, only on those that follow.

Description and restrictions

The $HP$ OPTIMIZE directive allows you to determine which areas of your program that the optimizer will process. Specifying $HP$ OPTIMIZE OFF causes the following source lines not to be optimized. $HP$ OPTIMIZE ON re-enables optimization for the following source lines.

This directive is effective only if you have used either the -On or +On option when you compiled the program. If you have not specified either option, both $HP$ OPTIMIZE ON and $HP$ OPTIMIZE OFF will give you level 0 optimization.

For more information

For information about the -On and +On options $HP$ OPTIMIZE directive is also discussed in the HP Fortran 90 Programmer's Guide.

Using HP Fortran 90 directives

Technical documentation

» Table of Contents

» Glossary

$HP$ ALIAS

Syntax

Description and restrictions

Local and global usage

Examples

For more information

$HP$ CHECK_OVERFLOW

Syntax

Description and restrictions

For more information

$HP$ LIST

Syntax

Description and restrictions

Example

For more information

$HP$ OPTIMIZE

Syntax

Description and restrictions

For more information