Engineering and Scientific Subroutine Library for AIX Version 3 Release 3: Guide and Reference

Setting Up Your ESSL Calling Sequences

This section gives the general rules for setting up the ESSL calling sequences. The information given here applies to all types of programs, running in all environments. For a description and examples of how to code the ESSL calling sequences in your particular programming language, see the following sections:

• Fortran Programs
• C Programs
• C++ Programs

For details on the conventions used in this book to describe the calling sequence syntax, see How to Interpret the Subroutine Descriptions. It describes how required and optional arguments are indicated in the calling sequence and the naming conventions used for different data types.

What Is an Input-Output Argument?

Some arguments are used for both input and output. The contents of the input argument are overlaid with the output value(s) on return to your program. Be careful that you save any data you need to preserve before calling the ESSL subroutine.

What Are the General Rules to Follow when Specifying Data for the Arguments?

You should follow the syntax rules given for each argument in "On Entry" in the subroutine description. Input-argument error messages may be issued, and your program may terminate when you make an error specifying the input arguments. For example:

• Data passed to ESSL must be of the correct type: integer, character, real, complex, short-precision, or long-precision. There is no conversion of data. Assuming you are using the ESSL header file with your C and C++ programs, you first need to define the following:
  • Complex and logical data in C programs, using the guidelines given on page "Setting Up Complex Data Types in C".
  • Short-precision complex and logical data in C++ programs, using the guidelines given on page "Setting Up Short-Precision Complex Data Types If You Are Using the IBM Open Class Complex Mathematics Library in C++".
• Character values must be one of the specified values. For example, it may have to be 'N', 'T', or 'C'.
• Numeric values must fall within the correct range for that argument. For example, a numeric value may need to be greater than or equal to 0, or it may have to be a nonzero value.
• Arrays must be defined correctly; that is, they must have the correct dimensions, or the dimensions must fall within the correct range. For example, input and output matrices may need to be conformable, or the number of rows in the matrix must be less than or equal to the leading dimension specified. (ESSL assumes all arrays are stored in column-major order.)

What Happens When a Value of 0 Is Specified for N?

For most ESSL subroutines, if you specify 0 for the number of elements to be processed in a vector or the order of a matrix (usually argument n), no computation is performed. After checking for input-argument errors, the subroutine returns immediately and no result is returned. In the other subroutines, an error message may be issued.

How Do You Specify the Beginning of the Data Structure in the ESSL Calling Sequence?

When you specify a vector, matrix, or sequence in your calling sequence, it does not necessarily have to start at the beginning of the array. It can begin at any point in the array. For example, if you want vector x to start at element 3 in array A, which is declared A(1:12), specify A(3) in your calling sequence for argument x, such as in the following SASUM calling sequence in your Fortran program:

              N    X   INCX
              |    |     |
   X = SASUM( 4 , A(3) , 2 )

Also, for example, if you want matrix A to start at the second row and third column of array A, which is declared A(0:10,2:8), specify A(1,4) in your calling sequence for argument a, such as in the following SGEADD calling sequence in your Fortran program:

                   A     LDA  TRANSA  B  LDB TRANSB  C  LDC  M   N
                   |      |     |     |   |    |     |   |   |   |
   CALL  SGEADD( A(1,4) , 11 , 'N'  , B , 4 , 'N'  , C , 4 , 4 , 3 )

For more examples of specifying vectors and matrices, see Chapter 3, Setting Up Your Data Structures.