This section explains how to interpret the information in the subroutine descriptions in Part 2 of this book.
Each subroutine description begins with a brief explanation of what the subroutine does. When we combine the description of multiple versions of a subroutine, we give enough information to enable you to easily tell the differences among the subroutines. Differences usually occur in either the function performed or the data types required for each subroutine.
This shows the syntax for the Fortran, C, C++, and PL/I 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); |
| PL/I | CALL NAME-1 | NAME-2 | ... | NAME-n (arg-1, arg-2, ... ,arg-m, ... ); |
The syntax indicates:
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.
The names of the arguments give an indication of the type of data that you should specify for the argument; for example:
This lists the input arguments, which are the arguments you pass to the ESSL 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 also listed, along with a reference to the On Return section.)
This lists the output arguments, which are the arguments passed back to your program from the ESSL 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.
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.
This is a functional, or mathematical, description of the function performed by this subroutine. It explains what computation is performed, not the implementation. It explains the variations in the computation depending on the input arguments. References are made, where appropriate, to mathematical background books listed in the bibliography. References appear as a number enclosed in square brackets, where the number refers to the item listed under that number in the bibliography. For example, reference [1] cites the first item listed.
These are unique ways you can use the subroutine in your application. In most cases, this book does not address applications of the ESSL subroutines; however, in special situations where the functional capability of the subroutine can be extended by following certain rules for its use, these rules are described in this section.
These are all the ESSL run-time errors that can occur in the subroutine. They are organized under three headings; Computational Errors, Input-Argument Errors, and Resource Errors. The return code values resulting from these errors are also explained.
The examples show how you would call the subroutine from a Fortran program. They show a variety of uses of the subroutine. Except where it is important to show differences in use between the various versions of the subroutine, the simplest version of the subroutine is used in the examples. In most cases, this is the short-precision real version of the subroutine. Each example provides a description of the important features of the example, followed by the Fortran calling sequence, the input data, and the resulting output data.