Guide and Reference

Interpreting the Subroutine Descriptions

This section explains how to interpret the information in the subroutine descriptions in Part 2 and 3 of this book. Each subroutine description explains the function(s) performed by the subroutine(s). It provides a data types table, showing how the data differs for each subroutine. It also contains sections that are described below.

Syntax

This section shows the syntax for the Fortran, C, C++, and HPF calling statements.

Fortran, C, and C++ Syntax

This section shows the syntax for the Fortran, C, and C++ calling statements.

Fortran	CALL NAME-1 | NAME-2 | ... | NAME-n (arg-1, arg-2, ... , arg-m)
C and C++	name-1 | name-2 | ... | name-n (arg-1, ... , arg-m);

The syntax indicates:

• The programming language (Fortran, C, or C++)

• Each possible subroutine name that you can code in the calling sequence. Each name is separated by the | (or) symbol. You specify only one of these names in your calling sequence. (You do not code the | in the calling sequence.)

• The arguments, listed in the order in which you code them in the calling sequence. You must code them all in your calling sequence.

  You can distinguish between input arguments and output arguments by looking at the "On Entry" and "On Return" sections, respectively. An argument used for both input and output is described in both the "On Entry" and "On Return" sections. In this case, the input value for the argument is overlaid with the output value.

Fortran 90 or HPF Syntax

This shows the syntax for the Fortran 90 and HPF calling statements.

Fortran 90 or HPF

Equations or Cases

CALL NAME (req-1, ... , req-m) CALL NAME (req-1, ... , req-m, opt-1, ... , opt-l)

The syntax indicates:

• The programming language (Fortran 90 or HPF)

• The mathematical equations or subroutines associated with a calling sequence (HPF only)

• The Parallel ESSL subroutine name, which is a generic name for one or more functions.

• The arguments in the calling sequence.

  The first calling sequence shows the arguments required when coding your program. The second calling sequence shows all the arguments, required and optional. The subroutine assigns a default value for any optional argument that is not present.

  You can distinguish between input arguments and output arguments by looking at the "On Entry" and "On Return" sections, respectively. An argument used for both input and output is described in both the "On Entry" and "On Return" sections. In this case, the input value for the argument is overlaid with the output value.

On Entry

This lists the input arguments, which are the arguments you pass to the subroutine. Each argument description first gives the meaning of the argument, and then gives the form of data required for the argument. (To help you avoid errors, output arguments are included, with a reference to the 'On Return' section.)

On Return

This lists the output arguments, which are the arguments passed back to your program from the subroutine. Each argument description first gives the meaning of the argument, and then gives the form of data passed back to your program for the argument.

Notes and Coding Rules

The notes describe any programming considerations and restrictions that apply to the arguments or the data for the arguments. There may be references to other parts of the book for further information.

Error Conditions

These are all the Parallel ESSL run-time errors that can occur in the subroutine. They are organized under the headings, "Computational Errors", "Input Argument Errors", "Resource Errors", "Communications Errors", and "Miscellaneous Errors".

Example

The two reference sections in this book contain different types of examples.

Fortran Examples

The examples in Part 2 of this book show how you would call the subroutine in a Fortran program. Each example includes:

• A description of the salient features of the example
• The calling sequence, coded in Fortran
• The input and output data distributed across a process grid

HPF Examples

The examples in Part 3 of this book show how you would call the subroutine in an HPF program. Each example includes:

• A description of the salient features of the example
• The data directives
• One or more ways to code the calling sequence
• The input and output data