This section describes how to calculate the length of your transform by use of formulas or error-handling capabilities provided in ESSL.
For the ESSL subroutines listed in Table 24, you need to provide one or more transform lengths for the
computation of a Fourier transform. These transform lengths are
supplied through one or more arguments, such as n, n1,
n2, and n3, in the calling sequence for the ESSL
subroutine. Only certain lengths of transforms are permitted in the
computation.
Table 24. ESSL Subroutines Requiring Transform Lengths
| Subroutine Names |
|---|
|
Fourier Transforms: _CFT _RCFT _CRFT _COSF _SINF SCOSFT _CFT2 _RCFT2 _CRFT2 _CFT3 _RCFT3 _CRFT3 SCFTP SCFT2P SCFT3P |
You have a choice of two methods for determining an acceptable length for your transform to be processed by ESSL:
The lengths ESSL accepts for transforms in the Fourier transform subroutines are listed in Acceptable Lengths for the Transforms. You should use the table in that section to find the two values your length falls between. You then specify the larger length for your transform. If you find a perfect match, you can use that value without having to change it. The formula provided in that section expresses how to calculate the acceptable values listed in the table. If necessary, you can use the formula to dynamically check lengths in your program.
This section describes how to get ESSL to calculate transform lengths.
Ask yourself which of the following ways you prefer to obtain the information from ESSL:
Because the Fourier transform subroutines allow only certain lengths for transforms, ESSL provides this error-handling capability to return acceptable lengths to your program. It returns them in the transform length arguments. The value ESSL returns is the next larger acceptable length for a transform, based on the length you specify in the n argument.
In this case, you obtain an acceptable value of n from the error message, but your program terminates.
Leave error 2030 as unrecoverable, without calls to EINFO and ERRSET. Run your program with a close approximation of the transform length you want to use. If this happens not to be an acceptable length, the ESSL error monitor returns an acceptable length of the transform in input-argument error message. This does, however, terminates your program when the error is encountered. (If you do happen to specify an acceptable length for the transform, error handling does not issue an error message and processing continues normally.) Figure 4 illustrates what happens when error 2030 is unrecoverable.
Figure 4. How to Obtain an N Value from an Error Message, but Terminate
|
In this case, you obtain an acceptable value of n from the error message and from the updated n argument returned to your program.
Use EINFO and ERRSET with an ESSL error exit routine, ENOTRM, to make error 2030 recoverable. This allows you to dynamically determine in your program an acceptable length for your transform, specified in the n argument(s). Run your program with a close approximation of the transform length you want to use. If this happens not to be an acceptable length, the ESSL error monitor returns an acceptable length of the transform 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 n argument(s). 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 do happen to specify an acceptable length for the transform, error handling does not issue an error message and processing continues normally.) Figure 5 illustrates what happens when error 2030 is recoverable.
Figure 5. How to Obtain an N Value from an Error Message and in Your Program
 |
The following example illustrates all the actions taken by the ESSL error-handling facility for each possible value of a recoverable input argument, n. The values of n used in the example are as follows:
Table 25 describes the actions taken by ESSL in every possible
situation for the values given in this example.
Table 25. Example of Input-Argument Error Recovery for Transform Lengths
| N Value | Action When 2030 Is an Unrecoverable Input-Argument Error | Action When 2030 Is a Recoverable Input-Argument Error |
|---|---|---|
| n = 7208960
-or- n = 7340032 | Your application program runs successfully. | Your application program runs successfully. |
| 7208960 < n < 7340032 | An input-argument error message is issued. The value in the error message is 7340032. The application program stops. | ESSL returns the value of n as 7340032 to the application program, and an input-argument error message is issued. The value in the error message is 7340032. ESSL does no computation, and control is returned to the application program. |
If you leave error 2030 unrecoverable, you do not code anything in your program. You just look at the error messages to get the transform lengths. On the other hand, if you want to make error 2030 recoverable to obtain the transform lengths 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:
You may want to provide a separate subroutine to calculate the transform length whenever you need it. Figure 6 shows how you might code a separate Fortran subroutine. Before calling SCFT in your program, you call this subroutine, SCFT which calculates the correct length and stores it in n. Upon return, your program checks the return code. If it is nonzero, the n argument was updated, as planned. You then do any necessary data setup and call SCFT. On the other hand, if the return code is zero, error handling was not invoked, the n argument was not updated, and the initialization step was performed for SCFT.
Figure 6. Fortran Subroutine to Calculate Transform Length
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 S2030
CALL EINFO(0)
CALL ERRSAV(2030,S2030)
CALL ERRSET(2030,0,-1,1,ENOTRM,0)
CALL SCFT(INIT,X,INC1X,INC2X,Y,INC1Y,INC2Y,
* N,M,ISIGN,SCALE,AUX1,NAUX1,AUX2,NAUX2,*10)
CALL ERRSTR(2030,S2030)
RETURN
10 CONTINUE
CALL ERRSTR(2030,S2030)
RETURN 1
END
|
You might want to combine the request for auxiliary storage sizes along with your request for transform lengths. Figure 7 shows how you might code a separate Fortran subroutine combining both requests. It combines the functions performed by the subroutines in Figure 3 and Figure 6.
Figure 7. Fortran Subroutine to Calculate Auxiliary Storage Sizes and Transform Length
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,S2030
CALL EINFO(0)
CALL ERRSAV(2015,S2015)
CALL ERRSAV(2030,S2030)
CALL ERRSET(2015,0,-1,1,ENOTRM,0)
CALL ERRSET(2030,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)
CALL ERRSTR(2030,S2030)
RETURN
10 CONTINUE
CALL ERRSTR(2015,S2015)
CALL ERRSTR(2030,S2030)
RETURN 1
END
|