# Compaq Fortran
User Manual for
Tru64 UNIX and
Linux Alpha Systems

Previous | Contents | Index

# Chapter 12
Compaq Fortran Library Routines

This chapter contains the following topics:

- Section 12.1, Overview of Compaq Fortran Library Routines
- Section 12.2, 3f Routines
- Section 12.3, 3hpf Routines
- Section 12.4, Reference Pages for the 3f and 3hpf Routines
- Section 12.5, EXTERNAL or INTRINSIC Declarations
- Section 12.6, Example Using the 3f Library Routine shcom_connect
- Section 12.7, Example of the 3f Library Routines irand and qsort

# 12.1 Overview of Compaq Fortran Library Routines

Compaq Fortran library routines consist of two groups of routines, commonly referred to by their Tru64 UNIX or Linux reference page section:

- 3f routines (see Section 12.2, 3f Routines)
- 3hpf routines (see Section 12.3, 3hpf Routines)

# 12.2 3f Routines

The 3f routines consist of two groups:

- Routines that serve as an interface or "jacket" to Tru64 UNIX or Linux operating system calls and library routines
  System calls (section 2 in reference pages) and library routines (section 3 in reference pages) provided with the operating system are typically written for use by the C language. The language interface 3f routines handle the various argument passing and function invocation differences between Compaq Fortran and C. This simplifies the programming effort needed to call a system call or C language library routine directly.
- Routines that perform special functions related to the Compaq Fortran run-time library (RTL) or calling between Compaq Fortran and C

Table 12-1 lists the groups of language interface ("jacket") 3f library routines.

Table 12-1 Summary of Language Interface (" Jacket") 3f Library Routines
Category | Routine Names | Standard-Conforming Alternatives
--- | --- | ---
Bessel mathematical operations | `besj0` , `besj1` , `besjn` , `bessel` , `besy0` , `besy1` , `besyn` , `dbesj0` , `dbesj1` , `dbesjn` , `dbesy0` , `dbesy1` , `dbesyn` | None.
Bit manipulation | `and` , `bit` , `lshift` , `not` , `or` , `rshift` , `xor` | Consider using the Compaq Fortran intrinsics with the same name instead.
Directories and files | `access` , `chdir` , `chmod` , `fstat` , `flush` , `fsync` , `isatty` , `link` , `lstat` , `rename` , `stat` , `symlnk` , `ttynam` , `umask` , `unlink` | None.
Error handling | `gerror` , `ierrno` , `perror` | Use error-handling specifiers to handle Compaq Fortran errors, such as ERR and IOSTAT. Use these routines to handle Tru64 UNIX and Linux errors.
I/O | `fgetc` , `fputc` , `fseek` , `ftell` , `getc` , `putc` | Consider using Compaq Fortran nonadvancing I/O instead of `fgetc` , `fputc` , `getc` , `putc` .
Miscellaneous | `index` , `len` , `lnblnk` , `loc` , `long` , `qsort` , `short` , `system` | Instead of `index` and `len` , use the Compaq Fortran intrinsic functions INDEX and LEN.
Random numbers | `drandm` , `irand` , `irandm` , `rand` , `random` , `srand` | Consider using the Compaq Fortran intrinsic subroutines RANDOM_NUMBER and RANDOM_SEED.
Return date and time | `ctime` , `dtime` , `etime` , `fdate` , `gmtime` , `idate` , `itime` , `ltime` , `time` | Consider using the Compaq Fortran intrinsic subroutine DATE_AND_TIME or, if you need a subset of the information returned by DATE_AND_TIME, the intrinsic subroutines (Compaq extensions) DATE, IDATE, and TIME.
Return error function | `erf` , `derf` , `erfc` , `derfc` | None.
Return process, system, or command-line information | `getarg` , `getcwd` , `getenv` , `getgid` , `getlog` , `getpid` , `getuid` , `iargc` | None.
Signals and processes | `abort` , `alarm` , `fork` , `kill` , `signal` , `sleep` , `wait` | Instead of `abort` , consider using the STOP statement.
Virtual memory allocation | `falloc` , `free` , `malloc` | For arrays and pointers, consider using the standard Fortran 95/90 ALLOCATABLE attribute or the ALLOCATE and DEALLOCATE statements.

Table 12-2 describes the 3f routines that provide special functions allowing Compaq Fortran and C language programs to work together.

Table 12-2 Summary of 3f Library Routines Providing Special Functions
Routine Name | Function and Comments
--- | ---
`for_rtl_init_` | Allows a C main language program to use the Compaq Fortran run-time library (RTL) environment by initializing the environment, including associated signal handlers; see `for_rtl_init_` in Table 12-3.
`for_rtl_finish_` | Allows a C main language program to terminate use of the Compaq Fortran run-time library (RTL) environment; see `for_rtl_finish_` in Table 12-3.
`for_get_fpe` | Returns information on the floating-point exception handling established for the current program unit; see `for_get_fpe` in Table 12-3.
`for_set_fpe` | Sets the floating-point exception handling established for the current program unit; see `for_set_fpe` in Table 12-3.
`for_set_reentrancy` | Sets reentrancy protection for the Fortran RTL.
`getfd` | Returns the file descriptor associated with a unit number, after the Compaq Fortran run-time library (RTL) environment has opened the file; see `getfd` in Table 12-3.
`omp_*` (TU*X ONLY) | Various OpenMP Fortran API run-time routines related to parallel processing. See `omp_*` in Table 12-3 and Section D.1, OpenMP Fortran API Run-Time Library Routines.
`ots*` (TU*X ONLY) | Various Compaq Fortran run-time routines related to parallel processing. See `ots*` in Table 12-3 and Section D.2, Other Parallel Threads Routines.
`shcom_connect` (TU*X ONLY) | Allows multiple processes to access common block data in a shared library (uses memory mapping). See Section 12.6, Example Using the 3f Library Routine shcom_connect.

Table 12-3 describes each Compaq Fortran 3f library routine and lists the appropriate reference page.

For those 3f library routines that serve as interface routines to a system call or a different library routine, the required related routine is listed. Most routines are invoked as functions, with the exception of those noted in the table as subroutines.

Table 12-3 3f Functions and Subroutines
Name | Reference Page | Description
--- | --- | ---
`abort` | `abort(3f)` | Terminates the program abnormally and may cause a core dump. Use as a subroutine.
`access` | `access(3f)` | Determines the accessibility of a file.
`alarm` | `alarm(3f)` | Executes a subroutine after a specified time.
`and` | `bit(3f)` | Returns the bitwise AND of two operands. Use as an intrinsic function.
`besj0` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (first kind, zero order).
`besj1` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (first kind, first order).
`besjn` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (first kind, nth order).
`bessel` | `bessel(3f)` | Returns bessel functions.
`besy0` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (second kind, zero order).
`besy1` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (second kind, first order).
`besyn` | `bessel(3f)` | Returns single-precision (REAL*4) bessel function value (second kind, nth order).
`bit` | `bit(3f)` | Returns bitwise functions.
`chdir` | `chdir(3f)` | Changes the default directory.
`chmod` | `chmod(3f)` | Changes the mode of a file.
`ctime` | `time(3f)` | Returns the system time as a 24-character ASCII string.
`dbesj0` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (first kind, zero order).
`dbesj1` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (first kind, first order).
`dbesjn` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (first kind, nth order).
`dbesy0` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (second kind, zero order).
`dbesy1` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (second kind, first order).
`dbesyn` | `bessel(3f)` | Returns a double-precision (REAL*8) bessel function value (second kind, nth order).
`derf` | `erf(3f)` | Returns a double-precision error function.
`derfc` | `erf(3f)` | Returns a double-precision error function (complementary form).
`dffrac` | `flmin(3f)` | Returns the fractional accuracy of a double-precision floating-point (REAL*8) number.
`dflmax` | `flmin(3f)` | Returns maximum positive double-precision floating-point (REAL*8) value.
`dflmin` | `flmin(3f)` | Returns minimum positive double-precision floating-point (REAL*8) value.
`dlgamma` | `lgamma(3f)` | Returns the REAL*8 log of the gamma function.
`drand` | `rand(3f)` | Generates a random number. Use `drandm` instead.
`drandm` | `random(3f)` | Generates a double-precision (REAL*8) random number.
`dtime` | `etime(3f)` | Returns the elapsed (delta) execution time.
`erf` | `erf(3f)` | Returns a single-precision error function.
`erfc` | `erf(3f)` | Returns a single-precision error function (complementary form).
`etime` | `etime(3f)` | Returns the actual execution time of a process.
`falloc` | `malloc(3f)` | Allocates space for an array in virtual memory. Use with `malloc` and `free` . Consider using the ALLOCATABLE attribute or the ALLOCATE and DEALLOCATE statements.
`fdate` | `fdate(3f)` | Returns the date and time in ASCII string. Use as a subroutine.
`ffrac` | `flmin(3f)` | Returns the fractional accuracy of single-precision floating-point (REAL*4) numbers.
`fgetc` | `fgetc(3f)` | Returns a character from a specified logical unit.
`flmax` | `flmin(3f)` | Returns the maximum positive single-precision floating-point (REAL*4) value.
`flmin` | `flmin(3f)` | Returns the minimum positive single-precision floating-point (REAL*4) value.
`flush` | `flush(3f)` | Writes (flushes) the output in a user buffer to system buffer. Discards read-ahead data in user buffer.
`for_get_fpe` | `for_get_fpe(3f)` | Returns the status of the floating-point exception (fpe) handling currently set for the program. Usually used with `for_set_fpe` . To use `for_get_fpe` from a C program, you must first call `for_rtl_init_` , described in this table. For more information, see Section 3.44, -fpen --- Control Arithmetic Exception Handling and Reporting and Chapter 14.
`for_rtl_init_` | `for_rtl_init_(3f)` | Initializes the Compaq Fortran run-time library (RTL) environment for a C program. Use this subroutine from a main program written in C that calls Compaq Fortran subprograms. Calling this subroutine from the main C program initializes Compaq Fortran RTL data. It also establishes Compaq Fortran RTL signal handlers and floating-point exception handling so that the Compaq Fortran subprograms behave as if they were the main program. The trailing underscore (_) is required, and this routine must be called from a C program.
`for_rtl_finish_` | `for_rtl_init_(3f)` | Cleans up the Compaq Fortran run-time library (RTL) environment for a C main program that previously called `for_rtl_init_` . A status value is returned by this function. The trailing underscore (_) is required, and this routine must be called from a C program. Also see `for_rtl_init_` .
`for_set_fpe` | `for_get_fpe(3f)` | Changes the floating-point exception (fpe) handling currently set for the program and also returns the status of the previous floating-point exception (fpe) handling setting. Can be used with `for_get_fpe` . To use `for_set_fpe` from a C program, you must first call `for_rtl_init_` , described in this table. For more information, see Section 3.44 and Chapter 14.
`for_set_reentrancy` | `for_set_reentrancy(3f)` | Sets reentrancy protection for the Fortran RTL.
`fork` | `fork(3f)` | Creates a copy of the calling process.
`fortran` | `intro(3f)` | Lists Fortran library routines.
`fputc` | `putc(3f)` | Writes a character to a specified logical unit.
`free` | `malloc(3f)` | Frees the memory allocated by `falloc` or `malloc` . Consider using the ALLOCATABLE attribute or the ALLOCATE and DEALLOCATE statements.
`fseek` | `fseek(3f)` | Repositions a file on a logical unit.
`fstat` | `stat(3f)` | Returns information about file status. The file is specified as a Fortran 95/90 logical unit number.
`fsync` | `fsync(3f)` | Writes the output in buffer to permanent storage.
`ftell` | `fseek(3f)` | Repositions a file on a logical unit.
`gerror` | `perror(3f)` | Writes system error messages.
`getarg` | `getarg(3f)` | Returns the command line arguments.
`getc` | `getc(3f)` | Returns a character from a logical unit.
`getcwd` | `getcwd(3f)` | Returns the directory path of the current directory.
`getenv` | `getenv(3f)` | Returns the value of environment variables.
`getfd` | `getfd(3f)` | For a file already opened by the Compaq Fortran run-time library (RTL), returns the file descriptor associated with a particular unit number.
`getgid` | `getuid(3f)` | Returns the group's id of the caller.
`getlog` | `getlog(3f)` | Returns the user's login name.
`getpid` | `getuid(3f)` | Returns the process id.
`getuid` | `getuid(3f)` | Returns the user's or group's id of the caller.
`gmtime` | `time(3f)` | Returns the system time in month, day, and so forth in G.M.T. (Greenwich Mean Time).
`iargc` | `getarg(3f)` | Returns the command-line arguments.
`idate` | `idate(3f)` | Returns the date or time in numeric form. Also available as an intrinsic subroutine (Compaq extension) described in the Compaq Fortran Language Reference Manual.
`ierrno` | `perror(3f)` | Returns a system error message number.
`index` | `index(3f)` | Returns the index of a substring within the string. Consider using INDEX intrinsic function described in the Compaq Fortran Language Reference Manual.
`inmax` | `flmin(3f)` | Returns the maximum positive integer value.
`irand` | `rand(3f)` | Generates random values. For an example program that uses `irand` , see Section 12.7.
`irandm` | `random(3f)` | Generates a positive integer random number.
`isatty` | `ttynam(3f)` | Returns whether the specified unit is a terminal port. Use as a subroutine.
`itime` | `idate(3f)` | Returns the date or time in numeric form.
`kill` | `kill(3f)` | Sends a signal to a process.
`len` | `index(3f)` | Returns the length of a string. Use the LEN intrinsic function described in the Compaq Fortran Language Reference Manual.
`lgamma` | `lgamma(3f)` | Returns the REAL*4 log of the gamma function.
`link` | `link(3f)` | Makes a directory link to an existing file.
`lnblnk` | `index(3f)` | Returns the index of the last nonblank character in a string.
`loc` | `loc(3f)` | Returns the address of an object. Similar to the %LOC built-in function described in the Compaq Fortran Language Reference Manual.
`long` | `long(3f)` | Converts INTEGER*2 to INTEGER*4.
`lshift` | `bit(3f)` | Shifts a word left by n bits. Use as an intrinsic function.
`lstat` | `stat(3f)` | Returns information about a file or a symbolic link.
`ltime` | `time(3f)` | Returns the system time in month, day, hour, minute, and seconds for the time zone.
`malloc` | `malloc(3f)` | Returns the address of a block of virtual memory. See also `free` . Consider using the ALLOCATABLE attribute or the ALLOCATE and DEALLOCATE statements.
`not` | `bit(3f)` | Returns the bitwise NOT (complement) of the operand. Use as an intrinsic function.
`omp_destroy_lock` | `omp_destroy_lock(3f)` | (TU*X ONLY) Disassociates a lock variable from any locks. See Section D.1.2.1, omp_destroy_lock.
`omp_get_dynamic` | `omp_get_dynamic(3f)` | (TU*X ONLY) Informs if dynamic thread adjustment is enabled. See Section D.1.1.1, omp_get_dynamic.
`omp_get_max_threads` | `omp_get_max_threads(3f)` | (TU*X ONLY) Gets the maximum value that can be returned by calls to the omp_get_num_threads() function. See Section D.1.1.2, omp_get_max_threads.
`omp_get_nested` | `omp_get_nested(3f)` | (TU*X ONLY) Informs if nested parallelism is enabled. See Section D.1.1.3, omp_get_nested.
`omp_get_num_procs` | `omp_get_num_procs(3f)` | (TU*X ONLY) Gets the number of processors that are available to the program. See Section D.1.1.4, omp_get_num_procs.
`omp_get_num_threads` | `omp_get_num_threads(3f)` | (TU*X ONLY) Gets the number of threads currently in the team executing the parallel region from which the routine is called. See Section D.1.1.5, omp_get_num_threads.
`omp_get_thread_num` | `omp_get_thread_num(3f)` | (TU*X ONLY) Gets the thread number, within the team, in the range from zero to `omp_get_num_threads()` minus 1. See Section D.1.1.6, omp_get_thread_num.
`omp_in_parallel` | `omp_in_parallel(3f)` | (TU*X ONLY) Informs whether or not a region is executing in parallel. See Section D.1.1.7, omp_in_parallel.
`omp_init_lock` | `omp_init_lock(3f)` | (TU*X ONLY) Initializes a lock to be used in subsequent calls. See Section D.1.2.2, omp_init_lock.
`omp_set_dynamic` | `omp_set_dynamic(3f)` | (TU*X ONLY) Enables or disables dynamic adjustment of the number of threads available for execution of parallel regions. See Section D.1.1.8, omp_set_dynamic.
`omp_set_lock` | `omp_set_lock(3f)` | (TU*X ONLY) Makes the executing thread wait until the specified lock is available. See Section D.1.2.3, omp_set_lock.
`omp_set_nested` | `omp_set_nested(3f)` | (TU*X ONLY) Enables or disables nested parallelism. See Section D.1.1.9, omp_set_nested.
`omp_set_num_threads` | `omp_set_num_threads(3f)` | (TU*X ONLY) Sets the number of threads to use for the next parallel region. See Section D.1.1.10, omp_set_num_threads.
`omp_test_lock` | `omp_test_lock(3f)` | (TU*X ONLY) Try to set the lock associated with a lock variable. See Section D.1.2.4, omp_test_lock.
`omp_unset_lock` | `omp_unset_lock(3f)` | (TU*X ONLY) Releases the executing thread from ownership of the lock. See Section D.1.2.5, omp_unset_lock.
`or` | `bit(3f)` | Returns the bitwise OR of two operands. Use as an intrinsic function.
`_OtsGetMaxThreads` | `otsgetmaxthreads(3f)` | (TU*X ONLY) Returns the number of threads that are normally used for parallel processing in the current environment. See Section D.2.1,_OtsGetMaxThreads or mpc_maxnumthreads.
`_OtsGetNumThreads` | `otsgetnumthreads(3f)` | (TU*X ONLY) Returns the number of threads being used or the number of created threads. See Section D.2.2,_OtsGetNumThreads or mpc_numthreads.
`_OtsGetThreadNum` | `otsgetthreadnum(3f)` | (TU*X ONLY) Returns a number that identifies the current thread. See Section D.2.3,_OtsGetThreadNum or mpc_my_threadnum.
`_OtsInitParallel` | `otsinitparallel(3f)` | (TU*X ONLY) Starts slave threads for parallel processing. See Section D.2.4,_OtsInitParallel.
`_OtsInParallel` | `otsinparallel(3f)` | (TU*X ONLY) Informs whether you are currently within a parallel region. See Section D.2.5,_OtsInParallel or mpc_in_parallel_region.
`_OtsSetNumThreads` | `otssetnumthreads(3f)` | (TU*X ONLY) Sets the number of threads to use for the next parallel region. See Section D.2.6,_OtsSetNumThreads .
`_OtsStopWorkers` | `otsstopworkers(3f)` | (TU*X ONLY) Stops any slave threads created by parallel library support. See Section D.2.7,_OtsStopWorkers or mpc_destroy.
`perror` | `perror(3f)` | Writes system error messages.
`putc` | `putc(3f)` | Writes a character to a Fortran 95/90 logical unit.
`qsort` | `qsort(3f)` | Performs a quick sort of array elements. For an example program that uses `qsort` , see Section 12.7.
`rand` | `rand(3f)` | Generates random values.
`random` | `random(3f)` | Generates a single-precision (REAL) random number.
`rename` | `rename(3f)` | Renames a file.
`rshift` | `bit(3f)` | Shifts a word right by n bits. Use as an intrinsic function.
`shcom_connect` | `shcom_connect(3f)` | (TU*X ONLY) Allows multiple processes to access common block data in a shared library (uses memory mapping).
`short` | `long(3f)` | Converts INTEGER*4 to INTEGER*2.
`signal` | `signal(3f)` | Changes the action of a signal.
`sleep` | `sleep(3f)` | Suspends execution for an interval.
`srand` | `rand(3f)` | Initializes the seed for subsequent use of `rand` and `irand` .
`stat` | `stat(3f)` | Returns information about the status of specified file.
`symlnk` | `link(3f)` | Makes a symbolic directory link to an existing file.
`system` | `system(3f)` | Executes a shell command.
`time` | `time(3f)` | Returns the system time in number of seconds from 00:00:00 G.M.T. January 1, 1970. Also available as an intrinsic subroutine (Compaq extension) described in the Compaq Fortran Language Reference Manual.
`ttynam` | `ttynam(3f)` | Returns the name of a terminal port or returns blanks if specified unit is not a terminal port.
`umask` | `umask(3f)` | Sets the file mode creation mask (protection).
`unlink` | `unlink(3f)` | Removes a directory entry. See also `link` .
`wait` | `wait(3f)` | Waits for the process to terminate.
`xor` | `bit(3f)` | Returns the bitwise exclusive OR of two operands. Use as an intrinsic function.

For More Information:

- On an example program that uses the `qsort` and `irand` routines, see Section 12.7.

# 12.3 3hpf Routines

The 3hpf routines (TU*X ONLY) provide functions for using High Performance Fortran (HPF) constructs to control parallel execution characteristics. Although usually used in programs that will execute in parallel, you can also use these routines for nonparallel programs.

The 3hpf routines are contained in the HPF_LOCAL_LIBRARY library (described in this chapter) and in the HPF_LIBRARY library (described in the Compaq Fortran Language Reference Manual).

HPF programs execute with the support of Compaq MPI (Message Passing Interface).

For more information about Compaq MPI, see:

    http://www.compaq.com/hpc/software/dmpi.html

Table 12-4 describes each of the Compaq Fortran 3hpf routines contained in the HPF_LOCAL_LIBRARY library.

Table 12-4 Compaq Fortran 3hpf HPF_LOCAL_LIBRARY Library Routines
Name | Reference Page | Description
--- | --- | ---
`abstract_to_physical` | `abstract_to_physical(3hpf)` | Returns processor identification for the physical processor associated with a specified abstract processor relative to a global actual argument array.
`get_hpf_my_node` | `get_hpf_my_node(3hpf)` | Returns an integer value in the range 0 to number of processors - 1. This is the unique process number on which an instance of an extrinsic(hpf_local) is executing; on a scalar computer system the value is the constant 0.
`get_hpf_numnodes` | `get_hpf_numnodes(3hpf)` | Returns the number of peers on which the program is executing.
`global_alignment` | `global_alignment(3hpf)` | Returns information about the global HPF array actual argument associated with an array local dummy argument; has the same behavior and interface as the subroutine HPF_ALIGNMENT.
`global_bounds` | `global_bounds(3hpf)` | Returns the upper and lower bounds of the actual argument associated with an assumed shape local dummy array.
`global_distribution` | `global_distribution (3hpf)` | Returns information about the global HPF array actual argument associated with an array local dummy argument; has the same behavior and interface as the subroutine HPF_DISTRIBUTION.
`global_template` | `global_template(3hpf)` | Returns information about the global HPF array actual argument associated with an array local dummy argument; has the same behavior and interface as the subroutine HPF_TEMPLATE.
`global_to_local` | `global_to_local(3hpf)` | Converts a set of global coordinates within a global HPF actual argument array to an equivalent set of local coordinates within the associated local dummy array.
`global_to_physical` | `global_to_physical (3hpf)` | Converts a global reference to an array element in the HPF global actual array argument. The argument must be associated with an assumed-shape local dummy array into the number of the process to which the element is mapped and the subscripts to access that element using the associated assumed shape array dummy argument on that process.
`hpf_synch` | `hpf_synch(3hpf)` | Synchronizes execution of all peers.
`local_to_global` | `local_to_global(3hpf)` | Converts a set of local coordinates within a local dummy array to an equivalent set of global coordinates within the associated global HPF actual argument array.
`physical_to_abstract` | `physical_to_abstract(3hpf)` | Returns coordinates for an abstract processor, relative to a global actual argument array, corresponding to a specified physical processor.

For More Information:

- On the 3hpf routines in the HPF_LIBRARY library, see the Compaq Fortran Language Reference Manual and `intro(3hpf)`.

# 12.4 Reference Pages for the 3f and 3hpf Routines

The reference page `intro(3f)` describes the 3f routines. Individual 3f functions also have their own reference pages, as shown in Table 12-3.

The reference page `intro(3hpf)` describes the 3hpf routines. Individual 3hpf functions also have their own reference pages, as shown in Table 12-4. And each routine is summarized in the Compaq Fortran Language Reference Manual.

You can use the `man` command to view online reference page information in the following ways:

- When the topic exists for multiple section numbers, specify the desired section number before the topic to view a specific reference page. For example, the following command returns the reference page for the 3f access routine, not its section 2 (system call) counterpart:

      % man 3f access

  The following `man` command returns the 3hpf intro reference page on Tru64 UNIX systems:

      % man 3hpf intro

- Use the `-f` option to view a one-line summary of the specified topic. This is useful to determine whether the same topic is associated with multiple section numbers, such as most 3f routines. The following `man` command lists all occurrences of the `access` topic:

      % man -f access

# 12.5 EXTERNAL or INTRINSIC Declarations

Certain Compaq Fortran library routines have the same names as intrinsic functions or subroutines (subprograms). You need to make sure that the correct routine or intrinsic subprogram is used, as follows:

- To use an intrinsic subprogram rather than a 3f library routine, you should not declare the function or subroutine as external in an EXTERNAL statement.
- To use a 3f library routine rather than an intrinsic subprogram, you should specify the subprogram as external in an EXTERNAL statement.

The following 3f routines have names that match similar intrinsic subprograms:

> `and`
> `idate`
> `index`
> `len`
> `lshift`
> `not`
> `or`
> `rshift`
> `time`
> `xor`

For portability reasons, you should consider using the intrinsic routines instead of the equivalent 3f external routine.

For More Information:

- On the EXTERNAL and INTRINSIC statements, see Compaq Fortran Language Reference Manual.

# 12.6 Example Using the 3f Library Routine shcom_connect

Example 12-1 shows the use of the 3f routine `shcom_connect` (UN*X ONLY)).

Example 12-1 Using the 3f Routine shcom_connect

    C
    C       FILE: shared_data.f - Example of initialized common data.
    C
            BLOCK DATA shared_block_data

            INTEGER*8 init_data
            REAL operand, result
            COMMON /shared_data/ init_data, operand, result

            DATA    init_data/42/, operand/0.0/, result/0.0/

            END

    C
    C       FILE: compute_agent.f - Example Fortran program
    C
            PROGRAM compute_agent
            INCLUDE '../include/shcom.f'

            INTEGER*8 init_data
            REAL operand, result
            COMMON /shared_data/ init_data, operand, result

            INTEGER shcom_connenct, stat
            EXTERNAL shcom_connenct

            stat = shcom_connect(init_data, '/tmp/shcom_demo')

            IF (stat .EQ. SHCOM_SUCCESS) THEN
                result = SQRT(operand)
            ELSE
                TYPE *, 'shcom_connect() failed, error = ', stat
            ENDIF

            STOP
            END
    /*
     * FILE ui_agent.c - Example of initialized common data written in C.
     */

    #include "shcom.h"

    typedef struct {
        long init_data;
        float operand;
        float result;
        } demo_t;

        extern demo_t shared_data_;

        main() {
     int stat;

     printf("shared_data_.init_data = %d\n", shared_data_.init_data);

     stat = shcom_connect(&shared_data_, "/tmp/shcom_demo");

     if (stat == SHCOM_SUCCESS) {
         shared_data_.operand = 2.0;
         shared_data_.result = 0.0;
         system("compute_agent");
         printf("shared_data_.result = %f\n", shared_data_.result);
     } else {
         printf("shcom_connect() failed, error = %d\n", stat);
     }
        }

        #
        #       FILE: Makefile  - Builds shared common example.
        #
        FC = f90
        CFLAGS = -g -I../include
        FFLAGS = -g
        LDFLAGS = -g
        LIBS = ../lib/libshcom.a

        all:    ui_agent compute_agent

        ui_agent:       ui_agent.o shared_data.so
         cc ${CFLAGS} -o ui_agent ui_agent.o shared_data.so ${LIBS}

        compute_agent:  compute_agent.o shared_data.so
         f90 ${FFLAGS} -o compute_agent compute_agent.o shared_data.so
        ${LIBS}

        shared_data.so: shared_data.o
         ld ${LDFLAGS} -shared -o shared_data.so shared_data.o -lc

        test:   shared_data.so ui_agent compute_agent
         LD_LIBRARY_PATH=.; export LD_LIBRARY_PATH; ui_agent

        clean:
         -rm -f ui_agent compute_agent
         -rm -f *.o shared_data.so
         -rm -f /tmp/shcom_demo so_locations

To compile and link this program, enter:

    % make all

To run this program, enter:

    % make test

The output from the program is as follows:

    shared_data_.init_data = 42
    shared_data_.result = 1.414214

# 12.7 Example of the 3f Library Routines irand and qsort

Example 12-2 shows the use of the 3f routines `irand` and `qsort` .

Example 12-2 Using the 3f Routines irand and qsort

          PROGRAM EXAMPLE
    !
    !     This is an example of calling the IRAND(3F) and QSORT(3F) entries.
    !
            EXTERNAL IRAND, QSORT, SUBSORT
            INTEGER (KIND=4) :: IRAND, SUBSORT
            INTEGER (KIND=4) :: IARRAY(10), I

            WRITE(6,100)
    !
    !     Initialize the array using the IRAND(3F) routine.
    !
            DO I=1,10
              IARRAY(I) = IRAND(0)
            END DO
            WRITE(6,120) 'IRAND(3F)', IARRAY
    !
    !     Now to sort the array using QSORT(3F)
    !
            CALL QSORT( IARRAY, 10, 4, SUBSORT)
            WRITE(6,120) 'QSORT(3F)', IARRAY
    !
    !     Define FORMAT statements
    !
    100     FORMAT ('0Start of EXAMPLE'//)
    120     FORMAT ('0Array contents after ',A,' call:'/, 10(/T20,I) //)
            STOP
          END PROGRAM EXAMPLE
    !
    !   Subroutine called by QSORT(3F)
    !
          INTEGER (KIND=4) FUNCTION SUBSORT (A,B)
            INTEGER (KIND=4) :: A,B
            SUBSORT = 1
            IF ( A == B ) SUBSORT = 0
            IF ( A < B ) SUBSORT = -1
            RETURN
          END FUNCTION SUBSORT

To compile and link this program (named `example` ), enter:

    % f90 -o example example.for

To run this program and redirect its output from `stdout` to `example.out` , enter:

    % example > example.out

The output from the program `example` contains the contents of the array before and after sorting, as follows:

    0Start of EXAMPLE

    0Array contents after IRAND(3F) call:

                            16838
                             5758
                            10113
                            17515
                            31051
                             5627
                            23010
                             7419
                            16212
                             4086

    0Array contents after QSORT(3F) call:

                            4086
                            5627
                            5758
                            7419
                           10113
                           16212
                           16838
                           17515
                           23010
                           31051

Previous | Next | Contents | Index