Language Reference

The alarm_ function sends an alarm signal at time TIME to invoke the function FUNC. The returned value is the remaining time from the last alarm.

Format/ Example

INTEGER(4) REMAINING, TIME,
  FUNC, alarm_
REMAINING =  alarm_ (TIME, FUNC)

The bic_ subroutine sets bit X1 of X2 to 0. X1 has a value range 0 <= X1 <= 31.

Format/ Example

INTEGER(4) X1, X2
CALL bic_ (X1, X2)

The bis_ subroutine sets bit X1 of X2 to 1. X1 has a value range 0 <= X1 <= 31.

Format/ Example

INTEGER(4) X1, X2
CALL bis_ (X1, X2)

The bit_ function returns the value .TRUE. in BITCHK if bit X1 of X2 equals 1. Otherwise, bit_ returns the value 0. X1 has a value range 0 <= X1 <= 31.

Format/ Example

INTEGER(4) X2, X1
LOGICAL BITCHK, bit_
BITCHK = bit_ (X1, X2)

The clock_ function returns the time in hh:mm:ss format. This function is different from the operating system clock function.

Format/ Example

CHARACTER(8) C, clock_
C = clock_()

The clr_fpscr_flags subroutine clears the floating-point status and control register flags you specify in the MASK argument. Flags that you do not specify in MASK remain unaffected. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsic procedures described in Integer Bit Model.

For more information on the FPSCR constants, see fpscr constants.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) MASK
 
MASK=(IOR(FP_OVERFLOW,FP_UNDERFLOW))
CALL clr_fpscr_flags(MASK)
 

For another example of the clr_fpscr_flags subroutine, see get_fpscr_flags.

The ctime_ subroutine converts the system time TIME to a 26-character ASCII string.

Format/ Example

INTEGER(KIND=TIME_SIZE) TIME
CHARACTER(26) STR
CALL ctime_(STR, TIME)

The date function returns the current date in mm/dd/yy format.

Format/ Example

CHARACTER(8) D, date
D = date()

The dtime_ function sets the time accounting information for the user time and system time in DTIME_STRUCT. The returned value, DELTA, is the sum of the user time and the system time since the last call to dtime_. The resolution for all timing is 1/100 of a second. The output appears in units of seconds.

Format/ Example

REAL(4) DELTA, dtime_
TYPE TB_TYPE
  SEQUENCE
  REAL(4) USRTIME
  REAL(4) SYSTIME
END TYPE
TYPE (TB_TYPE) DTIME_STRUCT
DELTA = dtime_(DTIME_STRUCT)

The etime_ function sets the user-elapsed time and system-elapsed time in ETIME_STRUCT since the start of the execution of a process. The returned value, ELAPSED, is the sum of the user-elapsed time and the system-elapsed time. The resolution for all timing is 1/100 of a second. The output appears in units of seconds.

Format/ Example

REAL(4) ELAPSED, etime_
TYPE TB_TYPE
  SEQUENCE
  REAL(4) USRTIME
  REAL(4) SYSTIME
END TYPE
TYPE (TB_TYPE) ETIME_STRUCT
ELAPSED = etime_(ETIME_STRUCT)

The exit_ subroutine stops execution of the process with the exit status of EXIT_STATUS.

Format/ Example

INTEGER(4) EXIT_STATUS
CALL exit_(EXIT_STATUS)

The fdate_ subroutine returns the date and time in a 26-character ASCII string. In the example, the date and time are returned in STR.

Format/ Example

CHARACTER(26) STR
CALL fdate_(STR)

The fiosetup_ function sets up the requested I/O behavior for the logical unit specified by UNIT. The request is specified by argument COMMAND. The argument ARGUMENT is an argument to the COMMAND. The Fortran include file 'fiosetup_.h' is supplied with the compiler to define symbolic constants for the fiosetup_ arguments and error return codes.

UNIT

is a logical unit that is currently connected to a file

COMMAND

IO_CMD_FLUSH_AFTER_WRITE (1). Specifies whether the buffers of the specified UNIT be flushed after every WRITE statement.

 

IO_CMD_FLUSH_BEFORE_READ (2). Specifies whether the buffers of the specified UNIT be flushed before every READ statement. This can be used to refresh the data currently in the buffers.

ARGUMENT

IO_ARG_FLUSH_YES (1). Causes the buffers of the specified UNIT to be flushed after every WRITE statement. This argument should be specified with the commands IO_CMD_FLUSH_AFTER_WRITE and IO_CMD_FLUSH_BEFORE_READ.

 

IO_ARG_FLUSH_NO (0) Instructs the I/O library to flush buffers at its own discretion. Note the units connected to certain device types must be flushed after each WRITE operation regardless of the IO_CMD_FLUSH_AFTER_WRITE setting. Such devices include terminals and pipes. This argument should be specified with the commands IO_CMD_FLUSH_AFTER_WRITE and IO_CMD_FLUSH_BEFORE_READ. This is the default setting for both commands.

Format/ Example

FUNCTION fiosetup_
(UNIT, COMMAND, ARGUMENT)
INTEGER(4) fiosetup_, IRESULT
INTEGER(4) UNIT, COMMAND, ARGUMENT
INCLUDE 'fiosetup_.h'
OPEN ( UNIT=42, FILE="foo", ...)
IRESULT = fiosetup_(42, &
     IO_CMD_FLUSH_AFTER_WRITE, &
     IO_ARG_FLUSH_YES)

The service routine FIOSETUP_ returns 0 if it succeeds. Otherwise, it returns one of the
following error codes:

IO_ERR_NO_RTE (1000) the run-time environment is not running. IO_ERR_BAD_UNIT(1001) the specified UNIT is unconnected. IO_ERR_BAD_CMD (1002) invalid command. IO_ERR_BAD_ARG (1003) invalid argument.

The flush_ subroutine flushes the contents of the input/output buffer for the logical unit LUNIT. The value of LUNIT must be within the range 0 <= LUNIT <=  2**31-1.

Format/ Example

INTEGER(4) LUNIT
CALL flush_(LUNIT)

The subroutines fpgets and fpsets retrieve and set the status of the floating-point operations, respectively. The include file fpdc.h contains the data declarations (specification statements) for the two subroutines. The include file fpdt.h contains the data initializations (data statements) and must be included in a block data program unit.

fpgets retrieves the floating-point process status and stores the result in a logical array called fpstat.

fpsets sets the floating-point status equal to the logical array fpstat.

This array contains logical values that can be used to specify floating-point rounding modes. See the User's Guide for examples and information on the elements of the fpstat array.

Note:

The XLF_FP_UTIL module provides procedures for manipulating the status of floating-point operations that are more efficient than the fpgets and fpsets subroutines. For more information, see Efficient Floating-point Control and Inquiry Procedures.

Format/ Example

CALL fpgets( fpstat )
 ...
CALL fpsets( fpstat )
BLOCK DATA
INCLUDE '/usr/include/fpdc.h'
INCLUDE '/usr/include/fpdt.h'
END

The fp_trap function allows you to query or change the mode of the user process to allow floating-point exceptions to generate traps. fp_trap returns an INTEGER(FP_MODE_KIND) in the form of an fp_trap constant. The argument TRAP_MODE should be an fp_trap constant. For information on fp_trap constants, see fpscr constants.

For more information, see fp_trap in Technical Reference: Base Operating System and Extensions Volume 1.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FP_MODE_KIND) FP_MODE, TRAP_MODE
 
TRAP_MODE = FP_TRAP_IMP
FP_MODE = fp_trap(TRAP_MODE)

For another example of how to use fp_trap, see set_fpscr_flags.

The ftell_ function returns the offset of the current byte relative to the beginning of the file associated with the specified logical unit UNIT. If the unit is not connected, the ftell_ function returns -1.

The ftell64_ function is identical to the ftell_ function with the exception that it can operate on files larger than 2 gigabytes in large file enabled file systems.

The offset returned by the ftell_ or ftell64_ function is the result of previously completed I/O operations. No references to ftell_ or ftell64_ on a unit with outstanding asynchronous data transfer operations are allowed until the matching WAIT statements for all outstanding asynchronous data transfer operations on the same unit are executed.

The offset returned by the ftell_ or ftell64_ function is the absolute offset of the current byte relative to the beginning of the file. This means that all bytes from the beginning of the file to the current byte are counted, including the data of the records and record terminators if they are present.

Format/ Example

INTEGER(4) ftell_, UNIT1, UNIT2, IRESULT
INTEGER(8) ftell64_, IRESULT8
 
UNIT1 = 42
IRESULT = ftell_(UNIT1)
 
UNIT2 = 44
IRESULT8 = ftell64_(UNIT2)      
! Unit 44 might be connected to a
! file larger than 2 gigabytes

The getarg subroutine returns a command line argument of the current process. I1 is an integer argument that specifies which command line argument to return. C1 is an argument of character type and will contain, upon return from getarg, the command line argument. If I1 is equal to 0, the program name is returned.

Format/ Example

INTEGER(4) I1
CHARACTER(n) C1
CALL getarg(I1,C1)

The getcwd_ function retrieves the pathname NAME of the current working directory where the maximum length is 1024 characters. The returned value, IS_CWD, is 0 if successful, and an error number otherwise.

Format/ Example

INTEGER(4) IS_CWD, getcwd_
CHARACTER(1024) NAME
IS_CWD = getcwd_ (NAME)

Given a Fortran logical unit, the getfd function returns the underlying file descriptor for that unit, or -1 if the unit is not connected.

Note:

Because XL Fortran does its own I/O buffering, using this function may require special care, as described in "Mixed-Language Input and Output" in the User's Guide.

Format/ Example

INTEGER(4) LUNIT, FD, getfd
FD = getfd(LUNIT)

The get_fpscr function returns the current value of the floating-point status and control register (fpscr) of the processor.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) FPSCR
 
FPSCR=get_fpscr()

The get_fpscr_flags function returns the current state of the floating-point status and control register flags you specify in the MASK argument. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsics described in Integer Bit Model.

For more information on the FPSCR constants, see fpscr constants.

Format/ Example

USE XLF_FP_UTIL
 
! ...
 
IF (get_fpscr_flags(IOR(FP_DIV_BY_ZERO,FP_INVALID)) .NE. 0) THEN
  ! Either Divide-by-zero or an invalid operation occurred.
 
  ! ...
 
  ! After processing the exception, the exception flags are
  ! cleared.
  CALL clr_fpscr_flags(IOR(FP_DIV_BY_ZERO,FP_INVALID))
END IF

The getgid_ function returns the group id of a process, where GROUP_ID is the requested real group id of the calling process.

Format/ Example

INTEGER(4) GROUP_ID, getgid_
GROUP_ID = getgid_()

The getlog_ subroutine stores the user's login name in NAME. NAME has a maximum length of 8 characters. If the user's login name is not found, NAME is filled with blanks.

Format/ Example

CHARACTER(8) NAME
CALL getlog_ (NAME)

The getpid_ function returns the process id of the current process in PROCESS_ID.

Format/ Example

INTEGER(4) PROCESS_ID, getpid_
PROCESS_ID = getpid_()

The get_round_mode function returns the current floating-point rounding mode. The return value will be one of the constants FP_RND_RN, FP_RND_RZ, FP_RND_RP or FP_RND_RM. For more information on the rounding mode constants, see fpscr constants.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) MODE
 
MODE=get_round_mode()
IF (MODE .EQ. FP_RND_RZ) THEN
! ...
END IF

The getuid_ function returns the real user id of the current process in USER_ID.

Format/ Example

INTEGER(4) USER_ID, getuid_
USER_ID = getuid_()

The global_timef function returns the elapsed time in milliseconds since the first call to global_timef was first executed among all running threads. The first call to global_timef returns 0.0 in milliseconds. This function returns the global timing results from all running threads. For thread-specific timing results, see the timef function.

Format/ Example

INTEGER N
REAL(8) global_timef, T1, T2, T3
  T1 = global_timef()   ! returns 0.0
    DO I = 1, N         ! loop 1
      H = I + 1000
    END DO
    DO I = 1, N         ! loop 2
      M = I + 2000
    END DO
  T2 = global_timef()
! returns the elapsed time of
!  loop 1 and loop 2
    DO I = 1, N         ! loop 3
      M = I + 3000
    END DO
  T3 = global_timef()
! returns the elapsed time of
!  loop 1, 2 and 3
END

The gmtime_ subroutine converts the system time STIME into the array TARRAY. The data is stored in TARRAY in the following order: seconds (0 to 59)
minutes (0 to 59)
hours (0 to 23)
day of the month (1 to 31)
month of the year (0 to 11)
year (year = current year - 1900)
day of week (Sunday = 0)
day of year (0 to 365)
daylight saving time (0 or 1)

Format/ Example

INTEGER(KIND=TIME_SIZE) STIME, TARRAY(9)
CALL gmtime_(STIME, TARRAY)

The hostnm_ function retrieves the machine's host name NAME. NAME has a maximum length of 32 characters. The returned value, ISHOST, is 0 if the host name is found, and an error number otherwise.

Format/ Example

INTEGER(4) ISHOST, hostnm_
CHARACTER(32) NAME
ISHOST = hostnm_ (NAME)

The iargc function returns an integer that represents the number of arguments following the program name that have been entered on the command line at run time.

Format/ Example

INTEGER(4) I1, iargc
I1 = iargc()

The idate_ subroutine returns the current date in a numerical format containing the day, month and year in IDATE_STRUCT.

Format/ Example

TYPE IDATE_TYPE
  SEQUENCE
  INTEGER(4) IDAY
  INTEGER(4) IMONTH
  INTEGER(4) IYEAR
END TYPE
TYPE (IDATE_TYPE) IDATE_STRUCT
CALL idate_(IDATE_STRUCT)

The ierrno_ function returns the error number, SYSERROR, of the last detected system error.

Format/ Example

INTEGER(4) SYSERROR, ierrno_
SYSERROR = ierrno_()

The irand function generates a positive integer number greater than 0 and less than or equal to 32768. The intrinsic subroutine SRAND(SEED) is used to provide the seed value for the random number generator.

Format/ Example

INTEGER(4) I1, irand
CALL SRAND(I1)
I1 = irand()

The irtc function returns an INTEGER(8) value of the number of nanoseconds since the initial value of the machine's real-time clock.

Format/ Example

INTEGER(8) A, B, irtc
A = irtc()
DO M = 1,20000
  N = N + M
END DO
B = irtc()
! How many nanoseconds elapsed?
PRINT *, B - A
END

The itime_ subroutine returns the current time in a numerical form containing seconds, minutes, and hours in ITIME_STRUCT.

Format/ Example

TYPE IAR
  SEQUENCE
  INTEGER(4) IHR
  INTEGER(4) IMIN
  INTEGER(4) ISEC
END TYPE
TYPE (IAR) ITIME_STRUCT
CALL itime_(ITIME_STRUCT)

The jdate function returns the current Julian date in yyddd format.

Format/ Example

CHARACTER(8) D, jdate
D = jdate()

The lenchr_ function stores the length of the character string STR in LENGTH.

Format/ Example

INTEGER(4) LENGTH, lenchr_
CHARACTER*(*) STR
LENGTH = lenchr_(STR)

The lnblnk_ function returns the index, INDEX, of the last non-blank character in the string STR. If the string is not found, INDEX is set to 0.

Format/ Example

INTEGER(4) INDEX, lnblnk_
CHARACTER(n) STR
INDEX = lnblnk_(STR)

The ltime_ subroutine dissects the system time STIME, which is in seconds, into the array TARRAY containing the GMT where the dissected time is corrected for the local time zone. The data is stored in TARRAY in the following order: seconds (0 to 59)
minutes (0 to 59)
hours (0 to 23)
day of the month (1 to 31)
month of the year (0 to 11)
year (year = current year - 1900)
day of week (Sunday = 0)
day of year (0 to 365)
daylight saving time (0 or 1)

Format/ Example

INTEGER(KIND=TIME_SIZE) STIME, TARRAY(9)
CALL ltime_(STIME, TARRAY)

The mclock function returns time accounting information about the current process and its child processes. The returned value is the sum of the current process's user time and the user and system time of all child processes. The unit of measure is one one-hundredth (1/100) of a second.

Format/ Example

INTEGER(4) I1, mclock
I1 = mclock()

The qsort_ subroutine performs a parallel quicksort on a one-dimensional array ARRAY whose length LEN is the number of elements in the array with each element having a size of ISIZE, and a user-defined sorting order function COMPAR to sort the elements of the array. Requirements for the COMPAR function are described under the qsort subroutine that is described in the AIX Technical Reference: Base Operating System and Extensions Volume 2.

Format/ Example

INTEGER(4) FUNCTION COMPAR_UP(C1, C2)
INTEGER(4) C1, C2
IF (C1.LT.C2) COMPAR_UP = -1
IF (C1.EQ.C2) COMPAR_UP =  0
IF (C1.GT.C2) COMPAR_UP =  1
RETURN
END
SUBROUTINE FOO()
INTEGER(4) COMPAR_UP
EXTERNAL COMPAR_UP
INTEGER(4) ARRAY(8), LEN, ISIZE
DATA ARRAY/0, 3, 1, 2, 9, 5, 7, 4/
LEN = 6
ISIZE = 4
CALL qsort_(ARRAY(3:8), LEN, ISIZE, COMPAR_UP)
! sorting ARRAY(3:8)
PRINT *, ARRAY
! result value is [0, 3, 1, 2, 4, 5, 7, 9]
RETURN
END

The qsort_down subroutine performs a parallel quicksort on a one-dimensional array ARRAY whose length LEN is the number of elements in the array with each element having a size of ISIZE. The result is stored in array ARRAY in descending order. As opposed to qsort_, the qsort_down subroutine does not require the COMPAR function.

Format/ Example

SUBROUTINE FOO()
  INTEGER(4) ARRAY(8), LEN, ISIZE
  DATA ARRAY/0, 3, 1, 2, 9, 5, 7, 4/
  LEN = 8
  ISIZE = 4
  CALL qsort_down(ARRAY, LEN, ISIZE)
  PRINT *, ARRAY
! Result value is [9, 7, 5, 4, 3, 2, 1, 0]
RETURN
END

The qsort_up subroutine performs a parallel quicksort on a one-dimensional, contiguous array ARRAY whose length LEN is the number of elements in the array with each element having a size of ISIZE. The result is stored in array ARRAY in ascending order. As opposed to qsort_, the qsort_up subroutine does not require the COMPAR function.

Format/ Example

SUBROUTINE FOO()
  INTEGER(4) ARRAY(8), LEN, ISIZE
  DATA ARRAY/0, 3, 1, 2, 9, 5, 7, 4/
  LEN = 8
  ISIZE = 4
  CALL qsort_up(ARRAY, LEN, ISIZE)
  PRINT *, ARRAY
! Result value is [0, 1, 2, 3, 4, 5, 7, 9]
RETURN
END

The rtc function returns a REAL(8) value of the number of seconds since the initial value of the machine's real-time clock.

Format/ Example

REAL(8) A, B, rtc
A = rtc()
DO M = 1,20000
  N = N + M
END DO
B = rtc()
! How many seconds elapsed?
PRINT *, B - A
END

The set_fpscr function sets the floating-point status and control register (fpscr) of the processor to the value provided in the FPSCR argument, and returns the value of the register before the change.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) FPSCR, OLD_FPSCR
 
FPSCR=get_fpscr()
 
! ...  Some changes are made to FPSCR  ...
 
OLD_FPSCR=set_fpscr(FPSCR)  ! OLD_FPSCR is assigned the value of
                            ! the register before it was
                            ! set with set_fpscr
 

The set_fpscr_flags subroutine allows you to set the floating-point status and control register flags you specify in the MASK argument. Flags that you do not specify in MASK remain unaffected. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsics described in Integer Bit Model.

For more information on the FPSCR constants, see fpscr constants.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) SAVED_FPSCR
INTEGER(FP_MODE_KIND) FP_MODE
 
SAVED_FPSCR = get_fpscr()           ! Saves the current value of
                                    ! the fpscr register.
FP_MODE = fp_trap(FP_TRAP_SYNC)     ! Enables precise trapping.
 
CALL set_fpscr_flags(TRP_DIV_BY_ZERO) ! Enables trapping of 
! ...                                 ! divide-by-zero.
FP_MODE=fp_trap(FP_MODE)              ! Restores initial trap   
                                      ! mode.
SAVED_FPSCR=set_fpscr(SAVED_FPSCR)    ! Restores fpscr register.
 

The set_round_mode function sets the current floating-point rounding mode, and returns the rounding mode before the change. You can set the mode to FP_RND_RN, FP_RND_RZ, FP_RND_RP or FP_RND_RM. For more information on the rounding mode constants, see fpscr constants.

Format/ Example

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) MODE
 
MODE=set_round_mode(FP_RND_RZ)  ! The rounding mode is set to
                                ! round towards zero.  MODE is
! ...                           ! assigned the previous rounding
                                ! mode.
MODE=set_round_mode(MODE)       ! The rounding mode is restored.
 

The setrteopts subroutine changes the setting of one or more of the run-time options during the execution of a program. See "Setting Runtime Options for Input/Output" in the User's Guide for details about the run-time options.

Format/ Example

CHARACTER(n) C1
CALL setrteopts (C1)
! For example,
! CALL setrteopts &
!   ('langlvl=90std:cnverr=no')

The sleep_ subroutine suspends the execution of the current process for SEC seconds.

Format/ Example

INTEGER(4) SEC
CALL sleep_(SEC)

The time_ function returns the current time (GMT) CURRTIME, in seconds.

Format/ Example

INTEGER(KIND=TIME_SIZE) CURRTIME, time_
CURRTIME = time_()

The timef function returns the elapsed time in milliseconds since the first instance timef was called. The first instance timef is called, the value 0.0d0 is returned.

Format/ Example

REAL(8) ELAPSED, timef
ELAPSED = timef()
DO M = 1,20000
  A = A ** 2
ENDDO
ELAPSED = TIMEF()

The timef_delta function returns the elapsed time in milliseconds since the last instance timef_delta was called with its argument set to 0.0 within the same thread. In order to get the correct elapsed time, you must determine which region of a thread you want timed. This region must start with a call to timef_delta(T0), where T0 is initialized (T0=0.0). The next call to timef_delta must use the first call's return value as the input argument if the elapsed time is expected.

Format/ Example

REAL(8) timef_delta, T0, T1, T2
  T0 = 0.0
    DO I = 1, N        ! Loop 1
      H = I + 1000
    END DO
  T1 = timef_delta(T0)
    DO I = 1, N        ! T1 gives the
      M = I + 2000     ! starting time
    END DO             ! of loop 2
  T2 = timef_delta(T1)
    DO I = 1, N        ! T2 gives the
      M = I + 3000     ! elapsed time
    END DO             ! of loop 2

The umask_ function sets the file mode creation mask to CMASK. The returned value, LASTMASK, is the previous value of the file mode creation mask.

Format/ Example

INTEGER(4) CMASK, LASTMASK, umask_
LASTMASK = umask_ (CMASK)

The usleep_ function suspends the execution of the current process for an interval of MSEC microseconds. The returned value, IS_SLEEP, is 0 if the function is successful, or an error number otherwise.

Format/ Example

INTEGER(4) IS_SLEEP, MSEC, usleep_
IS_SLEEP = usleep_ (MSEC)

The xl_ _trbk subroutine provides a traceback starting from the invocation point. xl_ _trbk can be called from your code, although not from signal handlers. The subroutine requires no parameters.

Format/ Example

INTEGER res, n
IF (n .EQ. 1) THEN
   res=1
   CALL XL_ _TRBK()
ELSE
   res=n * FACTORIAL(n-1)
ENDIF