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

Using Auxiliary Storage in ESSL

For the ESSL subroutines listed in Table 22, you need to provide extra working storage to perform the computation. This section describes the use of dynamic allocation for providing auxiliary storage in ESSL and how to calculate the amount of auxiliary storage you need by use of formulas or error-handling capabilities provided in ESSL, if dynamic allocation is not an option.

Auxiliary storage, or working storage, is supplied through one or more arguments, such as aux, in the calling sequence for the ESSL subroutine. If the working storage does not need to persist after the subroutine call, it is suggested you use dynamic allocation. For example, in the Fourier Transforms subroutines, you may allocate aux2 dynamically, but not aux1. See the subroutine descriptions in Part 2 of this book for details and variations.

Table 22. ESSL Subroutines Requiring Auxiliary Working Storage

Dynamic Allocation of Auxiliary Storage

Dynamic allocation for the auxiliary storage is performed when error 2015 is unrecoverable and naux=0. For details on which aux arguments allow dynamic allocation, see the subroutine descriptions in Part 2 of this book.

Setting Up Auxiliary Storage When Dynamic Allocation Is Not Used

You set up the storage area in your program and pass it to ESSL through arguments, specifying the size of the aux work area in the naux argument.

Who Do You Want to Calculate the Size? You or ESSL?

You have a choice of two methods for determining how much auxiliary storage you should specify:

• Use the formulas provided in the subroutine description to derive sufficient values for your current and future needs. Use them if ease of migration to future machines and future releases of ESSL is your primary concern. For details, see How Do You Calculate the Size Using the Formulas?.
• Use the ESSL error-handling facilities to return to you a minimum value for the particular processor you are currently running on. (Values vary by platform.) Use this approach if conserving storage is your primary concern. For details, see How Do You Get ESSL to Calculate the Size Using ESSL Error Handling?.

How Do You Calculate the Size Using the Formulas?

The formulas provided for calculating naux indicate a sufficient amount of auxiliary storage required, which, in most cases, is larger than the minimum amount, returned by ESSL error handling. There are two types of formulas:

• Simple formulas

  These are given in the naux argument syntax descriptions. In general, these formulas result in the minimum required value, but, in a few cases, they provide overestimates.

• Processor-independent formulas

  These are given in separate sections in the subroutine description. In general, these provide overestimates.

Both types of formulas provide values that are sufficient for all processors. As a result, you can migrate to any other processor and to future releases of ESSL without being concerned about having to increase the amount of storage for aux. You do, of course, need to weigh your storage requirements against the convenience of using this larger value.

To calculate the amount of storage using the formulas, you must substitute values for specific variables, such as n, m, n1, or n2. These variables are arguments specified in the ESSL calling sequence or derived from the arguments in the calling sequence.

How Do You Get ESSL to Calculate the Size Using ESSL Error Handling?

This section describes how you can get ESSL to calculate auxiliary storage.

Here Are the Two Ways You Can Do It

Ask yourself which of the following ways you prefer to obtain the information from ESSL:

• By leaving error 2015 unrecoverable, you can obtain the minimum required value of naux from the input-argument error message, but your program terminates.
• By making error 2015 recoverable, you can obtain the minimum required value of naux from the input-argument error message and have the updated naux argument returned to your program.

For both techniques, the amount returned by the ESSL error-handling facility is the minimum amount of auxiliary storage required to run your program successfully on the particular processor you are currently running on. The ESSL error-handling capability usually returns a smaller value than you derive by using the formulas listed for the subroutine. This is because the formulas provide a good estimate, but ESSL can calculate exactly what is needed on the basis of your data.

The values returned by ESSL error handling may not apply to future processors. You should not use them if you plan to run your program on a future processor. You should use them only if you are concerned with minimizing the amount of auxiliary storage used by your program.

The First Way

In this case, you obtain the minimum required value of naux from the error message, but your program terminates. The following description assumes that dynamic allocation is not selected as an option.

Leave error 2015 as unrecoverable, without calls to EINFO and ERRSET. Run your program with the naux values smaller than required by the subroutine for the particular processor you are running on. As a general guideline, specify values smaller than those listed in the formulas. However, if a lower limit is specified in the syntax (only for several naux1 arguments in the Fourier transform, convolution, and correlation subroutines), you should not go below that limit. The ESSL error monitor returns the necessary sizes of the aux storage areas in the input-argument error message. This does, however, terminate your program when the error is encountered. (If you accidentally specify a sufficient amount of storage for the ESSL subroutine to perform the computation, error handling does not issue an error message and processing continues normally.) Figure 1 illustrates what happens when error 2015 is unrecoverable.

Figure 1. How to Obtain an NAUX Value from an Error Message, but Terminate

* This check applies only to several NAUX1 arguments in the Fourier transform, convolution, and correlation subroutines.

The Second Way

In this case, you obtain the minimum required value of naux from the error message and from the updated naux argument returned to your program.

Use EINFO and ERRSET with an ESSL error exit routine, ENOTRM, to make error 2015 recoverable. This allows you to dynamically determine in your program the minimum sizes required for the auxiliary working storage areas, specified in the naux arguments. Run your program with the naux values smaller than required by the subroutine for the particular processor you are running on. As a general guideline, specify values smaller than those listed in the formulas. However, if a lower limit is specified in the syntax (only for several naux1 arguments in the Fourier transform, convolution, and correlation subroutines), you should not go below that limit. The ESSL error monitor returns the necessary sizes of the aux storage areas in the input-argument error message and a return code is passed back to your program, indicating that updated values are also returned in the naux arguments. You can then react to these updated values during run time in your program. ESSL does not perform any computation when this error occurs. For details on how to do this, see Chapter 4, Coding Your Program. (If you accidentally specify a sufficient amount of storage for the ESSL subroutine to perform the computation, error handling does not issue an error message and processing continues normally.) Figure 2 illustrates what happens when error 2015 is recoverable.

Figure 2. How to Obtain an NAUX Value from an Error Message and in Your Program

* This check applies only to several NAUX1 arguments in the Fourier transform, convolution, and correlation subroutines.

Here Is an Example of What Happens When You Use These Two Techniques

The following example illustrates all the actions taken by the ESSL error-handling facility for each possible value of a recoverable input argument, naux. A key point here is that if you want to have the updated argument value returned to your program, you must make error 2015 recoverable and then specify an naux value greater than or equal to 20 and less than 300. For values out of that range, the error recovery facility is not in effect. (These values of naux, 20 and 300, are used only for the purposes of this example and do not relate to any of the ESSL subroutines.)

NAUX

Meaning of the NAUX Value

20

Lower limit of naux required for using recoverable input-argument error-handling facilities in ESSL. (This applies only to several naux1 arguments in the Fourier transform, convolution, and correlation subroutines. You can find the lower limit in the syntax description for the naux1 argument. For a list of subroutines, see Table 22.)

300

Minimum value of naux, required for successful running (on the processor the program is being run on).

Table 23 describes the actions taken by ESSL in every possible situation for the values given in this example.

Table 23. Example of Input-Argument Error Recovery for Auxiliary Storage Sizes

Here Is How You Code It in Your Program

If you leave error 2015 unrecoverable, you do not code anything in your program. You just look at the error messages to get the sizes of auxiliary storage. On the other hand, if you want to make error 2015 recoverable to obtain the auxiliary storage sizes dynamically in your program, you need to add some coding statements to your program. For details on coding these statements in each programming language, see the following examples:

• For Fortran, see page "Example"
• For C, see page "Example 1"
• For C++, see page "Example"

You may want to provide a separate subroutine to calculate the auxiliary storage size whenever you need it. Figure 3 shows how you might code a separate Fortran subroutine. Before calling SCFT in your program, call this subroutine, SCFT which calculates the minimum size and stores it in the naux arguments. Upon return, your program checks the return code. If it is nonzero, the naux arguments were updated, as planned. You should then make sure adequate storage is available and call SCFT. On the other hand, if the return code is zero, error handling was not invoked, the naux arguments were not updated, and the initialization step was performed for SCFT.

Figure 3. Fortran Subroutine to Calculate Auxiliary Storage Sizes

      SUBROUTINE SCFT
     * N, M, ISIGN, SCALE, AUX1, NAUX1,AUX2,NAUX2)
      REAL*4 X(0:*),Y(0:*),SCALE
      REAL*8 AUX1(7),AUX2(0:*)
      INTEGER*4 INIT,INC1X,INC2X,INC1Y,INC2Y,N,M,ISIGN,NAUX1,NAUX2
      EXTERNAL ENOTRM
      CHARACTER*8   S2015
          CALL EINFO(0)
          CALL ERRSAV(2015,S2015)
          CALL ERRSET(2015,0,-1,1,ENOTRM,0)
C     SETS NAUX1 AND NAUX2 TO THE MINIMUM VALUES REQUIRED TO USE
C     THE RECOVERABLE INPUT-ARGUMENT ERROR-HANDLING FACILITY
          NAUX1 = 7
          NAUX2 = 0
          CALL SCFT(INIT,X,INC1X,INC2X,Y,INC1Y,INC2Y,
     *              N,M,ISIGN,SCALE,AUX1,NAUX1,AUX2,NAUX2,*10)
          CALL ERRSTR(2015,S2015)
          RETURN
10        CONTINUE
          CALL ERRSTR(2015,S2015)
          RETURN 1
          END