The default file name for the executable program is a.out. You can select a different name with the -o compiler option. You should avoid giving your programs the same names as system or shell commands (such as test or cp), as you could accidentally execute the wrong command. If a name conflict does occur, you can execute the program by specifying a path name, such as ./test.
You can run a program by entering the path name and file name of an executable object file along with any run-time arguments on the command line.
To suspend a running program, press the Ctrl+Z key while the program is in the foreground. Use the fg command to resume running.
To cancel a running program, press the Ctrl+C key while the program is in the foreground.
Statically linked programs that you compiled with levels of XL Fortran prior to Version 8.1 should continue to run with no change in performance or behavior. They may not run on a system with a level of the operating system different from the system on which they were compiled.
If you have dynamically linked programs compiled by XL Fortran Version 2, 3, 4, 5, 6, or 7, you can run them on systems with the XL Fortran Version 8 libraries. The programs will use the current compiler data formats and I/O behavior, which are somewhat different from those of XL Fortran Version 2.
If you want to move an XL Fortran executable file to a different system for execution, you can link statically and copy the program, and optionally the run-time message catalogs. Alternatively, you can link dynamically and copy the program as well as the XL Fortran libraries if needed and optionally the run-time message catalogs. For non-SMP programs, libxlf90.a is usually the only XL Fortran library needed. For SMP programs, you will usually need at least the libxlf90_r.a and libxlsmp.a libraries. libxlf.a is only needed if the program has any XL Fortran Version 1 or 2 object files linked in. libxlfpmt*.a and libxlfpad.a are only needed if the program is compiled with the -qautodbl option. If your application has dependencies on libhmd.a, refer to Using Debug Memory Routines for XL Fortran for more details on library dependencies.
For a dynamically linked program to work correctly, the XL Fortran libraries and operating system on the execution system must be at either the same level or a more recent level than on the compilation system.
For a statically linked program to work properly, the operating-system level may need to be the same on the execution system as it is on the compilation system.
The XL Fortran compiler and run-time library provide binary compatibility in the following areas:
xlf95_r7 test.f -lmy_utility -o a.out
You do not need to regenerate libmy_utility.a before using it on AIX Version 4.3.3.
There are, however, restrictions on binary compatibility. XL Fortran supports combinations of Draft 7 and 1003.1-1996 standard object files in some instances. For example, if you used XL Fortran Version 5.1.0 to create a library, that library uses the Draft 7 pthreads API. An application that you build with that library can use either the Draft 7 pthreads API or the 1003.1-1996 standard pthreads API as long as the portions of the complete application built with the Draft 7 pthreads API do not share any pthreads data objects (such as mutexes or condition variables) with the portions built with the 1003.1-1996 standard pthreads API. If any such objects need to be used across portions of an application that are compiled with different levels of the pthreads API, the final application needs to use either the Draft 7 pthreads API or the 1003.1-1996 standard pthreads API across the entire application. You can do this in one of two ways:
There are three run-time libraries that are connected with POSIX thread support. The libxlf90_r.a library is a multiprocessor-enabled version of the Fortran run-time library. The libxlsmp.a library is the SMP run-time library.
The following libraries are used:
XL Fortran supplies the following directories for .mod files:
Depending on the invocation command, and in some cases, the compiler option, the appropriate
set of libraries and include files for thread support is bound in. For
example:
| Cmd. | Libraries Used | Include Files Used | POSIX Pthreads API Level Supported |
|---|---|---|---|
|
xlf90_r xlf95_r |
/lib/libxlf90.a /lib/libxlsmp.a /lib/libpthreads.a |
/usr/lpp/xlf/include_32 (if you specify -q32) /usr/lpp/xlf/include_64 (if you specify -q64) | 1003.1-1996 standard |
|
xlf90_r7 xlf95_r7 |
/lib/libxlf90.a /lib/libxlsmp.a /lib/libxlfpthrds_compat.a /lib/libpthreads.a | /usr/lpp/xlf/include_32_d7 | Draft 7 |
To select a language for run-time messages that are issued by an XL Fortran program, set the LANG and NLSPATH environment variables before executing the program.
In addition to setting environment variables, your program should call the C library routine setlocale to set the program's locale at run time. For example, the following program specifies the run-time message category to be set according to the LC_ALL, LC_MESSAGES, and LANG environment variables:
PROGRAM MYPROG PARAMETER(LC_MESSAGES = 5) EXTERNAL SETLOCALE CHARACTER NULL_STRING /Z'00'/ CALL SETLOCALE (%VAL(LC_MESSAGES), NULL_STRING) END
The C library routine setlocale is defined in the AIX Technical Reference: Base Operating System and Extensions Volume 1.
Internal switches in an XL Fortran program control run-time behavior, similar to the way compiler options control compile-time behavior. You can set the run-time options through either environment variables or a procedure call within the program.
You can specify all XL Fortran run-time option settings by using one of two environment variables: XLFRTEOPTS and XLSMPOPTS.
The XLFRTEOPTS environment variable allows you to specify options that affect I/O, EOF error-handling, and the specification of random-number generators. You can declare XLFRTEOPTS by using the following ksh command format:
.-:------------------------------------------.
V |
>>-XLFRTEOPTS=--+---+----runtime_option_name--=----option_setting---+--+---+-><
'-"-' '-"-'
You can specify option names and settings in uppercase or lowercase. You can add blanks before and after the colons and equal signs to improve readability. However, if the XLFRTEOPTS option string contains imbedded blanks, you must enclose the entire option string in double quotation marks (").
The environment variable is checked when the program first encounters one of the following conditions:
Changing the XLFRTEOPTS environment variable during the execution of a program has no effect on the program.
The SETRTEOPTS procedure (which is defined in "Service and Utility Procedures" in the XL Fortran for AIX Language Reference) accepts a single-string argument that contains the same name-value pairs as the XLFRTEOPTS environment variable. It overrides the environment variable and can be used to change settings during the execution of a program. The new settings remain in effect for the rest of the program unless changed by another call to SETRTEOPTS. Only the settings that you specified in the procedure call are changed.
You can specify the following run-time options with the XLFRTEOPTS environment variable or the SETRTEOPTS procedure:
The library reads data from or writes data to the file system in chunks for READ or WRITE statements, instead of piece by piece. The major benefit of buffering is performance improvement.
If you have applications in which Fortran routines work with routines in other languages or in which a Fortran process works with other processes on the same data file, the data written by Fortran routines may not be seen immediately by other parties (and vice versa), because of the buffering. Also, a Fortran READ statement may read more data than it needs into the I/O buffer and cause the input operation performed by a routine in other languages or another process that is supposed to read the next data item to fail. In these cases, you can use the buffering run-time option to disable the buffering in the XL Fortran run-time library. As a result, a READ statement will read in exactly the data it needs from a file and the data written by a WRITE statement will be flushed out to the file system at the completion of the statement.
Note: I/O buffering is always enabled for files on sequential access devices (such as pipes, terminals, sockets, and tape drives). The setting of the buffering option has no effect on these types of files.
If you disable I/O buffering for a logical unit, you do not need to call the Fortran service routine flush_ to flush the contents of the I/O buffer for that logical unit.
The suboptions for buffering are as follows:
In the following example, Fortran and C routines read a data file through redirected standard input. First, the main Fortran program reads one integer. Then, the C routine reads one integer. Finally, the main Fortran program reads another integer.
Fortran main program:
integer(4) p1,p2,p3 print *,'Reading p1 in Fortran...' read(5,*) p1 call c_func(p2) print *,'Reading p3 in Fortran...' read(5,*) p3 print *,'p1 p2 p3 Read: ',p1,p2,p3 end
C subroutine (c_func.c):
#include <stdio.h>
void
c_func(int *p2)
{
int n1 = -1;
printf("Reading p2 in C...\n");
setbuf(stdin, NULL); /* Specifies no buffering for stdin */
fscanf(stdin,"%d",&n1);
*p2=n1;
}
Input data file (infile):
11111 22222 33333 44444
The main program runs by using infile as redirected standard input, as follows:
$ main < infile
If you turn on buffering=disable_preconn, the results are as follows:
Reading p1 in Fortran... Reading p2 in C... Reading p3 in Fortran... p1 p2 p3 Read: 11111 22222 33333
If you turn on buffering=enable, the results are unpredictable.
To obtain support for items that are part of the Fortran 95 standard and are available in XL Fortran as of Version 7.1 (such as namelist comments), you must specify one of the following suboptions:
The following example contains a Fortran 95 extension (the file specifier is missing from the OPEN statement):
program test1
call setrteopts("langlvl=95std")
open(unit=1,access="sequential",form="formatted")
10 format(I3)
write(1,fmt=10) 123
Specifying langlvl=95std results in a run-time error message.
The following example contains a Fortran 95 feature (namelist comments) that was not part of Fortran 90:
program test2
INTEGER I
LOGICAL G
NAMELIST /TODAY/G, I
call setrteopts("langlvl=95std:namelist=new")
open(unit=2,file="today.new",form="formatted", &
& access="sequential", status="old")
read(2,nml=today)
close(2)
end
today.new:
&TODAY ! This is a comment
I = 123, G=.true. /
If you specify langlvl=95std, no run-time error message is issued. However, if you specify langlvl=90std, a run-time error message is issued.
The err_recovery setting determines whether any resulting errors are treated as recoverable or severe.
You can only use multiple connections within the same program for files on random-access devices, such as disk drives. In particular, you cannot use multiple connections within the same program for:
To avoid the possibility of damaging the file, keep the following points in mind:
In your program, you can now specify multiple OPEN statements that contain different values for the UNIT parameters but the same value for the FILE parameters. For example, if you have a symbolic link called mytty that is linked to TTY device /dev/pts/2, you can run the following program when you specify the multconnio=tty option:
PROGRAM iotest OPEN(UNIT=3, FILE='mytty', ACTION="WRITE") OPEN(UNIT=7, FILE='mytty', ACTION="WRITE") END PROGRAM iotest
Fortran preconnects units 0, 5, and 6 to the same TTY device. Normally, you cannot use the OPEN statement to explicitly connect additional units to the TTY device that is connected to units 0, 5, and 6. However, this is possible if you specify the multconnio=tty option. For example, if units 0, 5, and 6 are preconnected to TTY device /dev/pts/2, you can run the following program if you specify the multconnio=tty option:
PROGRAM iotest OPEN(UNIT=3, FILE='/dev/pts/2') END PROGRAM iotest
With namelist=old, the nonstandard NAMELIST format is not considered an error by either the langlvl=95std or the langlvl=90std setting.
The following examples set the cnverr run-time option to yes and the xrf_messages option to no.
# Basic format XLFRTEOPTS=cnverr=yes:xrf_messages=no export XLFRTEOPTS # With imbedded blanks XLFRTEOPTS="xrf_messages = NO : cnverr = YES" export XLFRTEOPTS
As a call to SETRTEOPTS, this example could be:
CALL setrteopts('xrf_messages=NO:cnverr=yes')
! Name is in lowercase in case -U (mixed) option is used.
The XLSMPOPTS environment variable allows you to specify options that affect SMP execution.
You can declare XLSMPOPTS by using the following ksh command format:
.-:------------------------------------------.
V |
>>-XLSMPOPTS=--+---+----runtime_option_name--=----option_setting---+--+---+-><
'-"-' '-"-'
You can specify option names and settings in uppercase or lowercase. You can add blanks before and after the colons and equal signs to improve readability. However, if the XLSMPOPTS option string contains imbedded blanks, you must enclose the entire option string in double quotation marks (").
You can specify the following run-time options with the XLSMPOPTS environment variable:
Work is assigned to threads in a different manner, depending on the scheduling type and chunk size used. A brief description of the scheduling types and their influence on how work is assigned follows:
CEILING(number_of_iterations / number_of_threads)
These partitions are then assigned to each of the threads. It is these partitions that are then subdivided into chunks of iterations. If a thread is asleep, the threads that are active will complete their assigned partition of work.
Choosing chunking granularity is a tradeoff between overhead and load balancing. The syntax for this option is schedule=suboption, where the suboptions are defined as follows:
When a thread becomes available, it takes the next chunk from its preassigned partition. If there are no more chunks in that partition, the thread takes the next available chunk from a partition preassigned to another thread.
The first chunk contains CEILING(number_of_iterations / number_of_threads) iterations. Subsequent chunks consist of CEILING(number_of_iterations_remaining / number_of_threads) iterations.
If you have not specified n, the chunks will contain CEILING(number_of_iterations / number_of_threads) iterations. Each thread is assigned one of these chunks. This is known as block scheduling.
If you have not specified schedule, the default is set to schedule=static, resulting in block scheduling.
This option allows you full control over the number of execution threads. The default value for num is 1 if you did not specify -qsmp. Otherwise, it is the number of online processors on the machine. For more information, see the NUM_PARTHDS intrinsic function in the XL Fortran for AIX Language Reference.
The xlsmp run-time library routines use both "busy-wait" and "sleep" states in their approach to waiting for work. You can control these states with the spins, yields, and delays options.
During the busy-wait search for work, the thread repeatedly scans the work queue up to num times, where num is the value that you specified for the option spins. If a thread cannot find work during a given scan, it intentionally wastes cycles in a delay loop that executes num times, where num is the value that you specified for the option delays. This delay loop consists of a single meaningless iteration. The length of actual time this takes will vary among processors. If the value spins is exceeded and the thread still cannot find work, the thread will yield the current time slice (time allocated by the processor to that thread) to the other threads. The thread will yield its time slice up to num times, where num is the number that you specified for the option yields. If this value num is exceeded, the thread will go to sleep.
In summary, the ordered approach to looking for work consists of the following steps:
The syntax for specifying these options is as follows:
Zero is a special value for spins and yields, as it can be used to force complete busy-waiting. Normally, in a benchmark test on a dedicated system, you would set both options to zero. However, you can set them individually to achieve other effects.
For instance, on a dedicated 8-way SMP, setting these options to the following:
parthds=8 : schedule=dynamic=10 : spins=0 : yields=0
results in one thread per CPU, with each thread assigned chunks consisting of 10 iterations each, with busy-waiting when there is no immediate work to do.
You can also use the environment variables SPINLOOPTIME and YIELDLOOPTIME to tune performance. Refer to the AIX Performance Management Guide for more information on these variables.
Typically, parthreshold is set to be equal to the parallelization overhead. If the computation in a parallelized loop is very small and the time taken to execute these loops is spent primarily in the setting up of parallelization, these loops should be executed sequentially for better performance.
The allowed values for this option are the numbers from 0 to 32. If you set profilefreq to one of these values, the following results will occur.
It is important to note that dynamic profiling is not applicable to user-specified parallel loops (for example, loops for which you specified the PARALLEL DO directive).
The following environment variables, which are included in the OpenMP standard, allow you to control the execution of parallel code.
The OMP_DYNAMIC environment variable enables or disables dynamic adjustment of the number of threads available for the execution of parallel regions. The syntax is as follows:
>>-OMP_DYNAMIC=--+-TRUE--+-------------------------------------><
'-FALSE-'
If you set this environment variable to TRUE, the run-time environment can adjust the number of threads it uses for executing parallel regions so that it makes the most efficient use of system resources. If you set this environment variable to FALSE, dynamic adjustment is disabled.
The default value for OMP_DYNAMIC is TRUE. Therefore, if your code needs to use a specific number of threads to run correctly, you should disable dynamic thread adjustment.
The omp_set_dynamic subroutine takes precedence over the OMP_DYNAMIC environment variable.
The OMP_NESTED environment variable enables or disables nested parallelism. The syntax is as follows:
>>-OMP_NESTED=--+-TRUE--+--------------------------------------><
'-FALSE-'
If you set this environment variable to TRUE, nested parallelism is enabled. This means that the run-time environment might deploy extra threads to form the team of threads for the nested parallel region. If you set this environment variable to FALSE, nested parallelism is disabled.
The default value for OMP_NESTED is FALSE.
The omp_set_nested subroutine takes precedence over the OMP_NESTED environment variable.
The OMP_NUM_THREADS environment variable sets the number of threads that a program will use when it runs. The syntax is as follows:
>>-OMP_NUM_THREADS=--num---------------------------------------><
The default number of threads that a program uses when it runs is the number of online processors on the machine.
If you specify the number of threads with both the PARTHDS suboption of the XLSMPOPTS environment variable and the OMP_NUM_THREADS environment variable, the OMP_NUM_THREADS environment variable takes precedence. The omp_set_num_threads subroutine takes precedence over the OMP_NUM_THREADS environment variable.
The following example shows how you can set the OMP_NUM_THREADS environment variable:
export OMP_NUM_THREADS=16
The OMP_SCHEDULE environment variable applies to PARALLEL DO and work-sharing DO directives that have a schedule type of RUNTIME. The syntax is as follows:
>>-OMP_SCHEDULE=--sched_type--+---------------+----------------><
'-,--chunk_size-'
This environment variable is ignored for PARALLEL DO and work-sharing DO directives that have a schedule type other than RUNTIME.
If you have not specified a schedule type either at compile time (through a directive) or at run time (through the OMP_SCHEDULE environment variable or the SCHEDULE option of the XLSMPOPTS environment variable), the default schedule type is STATIC, and the default chunk size is set to the following for the first N - 1 threads:
chunk_size = ceiling(Iters/N)
It is set to the following for the Nth thread, where N is the total number of threads and Iters is the total number of iterations in the DO loop:
chunk_size = Iters - ((N - 1) * ceiling(Iters/N))
If you specify both the SCHEDULE option of the XLSMPOPTS environment variable and the OMP_SCHEDULE environment variable, the OMP_SCHEDULE environment variable takes precedence.
The following examples show how you can set the OMP_SCHEDULE environment variable:
export OMP_SCHEDULE="GUIDED,4" export OMP_SCHEDULE="DYNAMIC"