![](http://www.gnu-darwin.org/hexley-gd-sm.png)
|
UNIX (CCP4: Library)
NAME
unix.m4, vms.for, w32mvs.f - library routines for system interactions
DESCRIPTION
These subroutines allow Fortran programs to interact directly with the
appropriate operating system. There are three files for three types of operating
system: unix.m4 (UNIX), vms.for (VMS) and w32mvs.f
(Microsoft Visual Studio, for NT).
Each file should contains the same basic set of routines in the three different
implementations; differences between them are to cope with platform-specific
aspects of each system.
Contents
List of Routines
The following table lists the subroutines, and notes which file(s) they can
be found in.
Routine | Description | unix.m4 | vms.for | w32mvs.f
|
---|
CCPOPN
| Open a file
| yes | yes | yes
| UBYTES
| Returns number of bytes per word and 'words'/'bytes'
to indicate if byte handling is available
| yes | yes | yes
| UCPUTM
| Get CPU time
| yes | yes | yes
| UGERR
| Get error explanation
| yes | yes | yes
| UGTENV
| Get value of env. variable
| yes | yes | yes
| UGTUID
| Get user id - it's name
| yes | yes | yes
| UIDATE
| Get date in 3 integer format
| yes | yes | yes
| UISATT
| Is file a terminal?
| yes | yes | yes
| USTIME
| Get absolute time in seconds
| yes | yes | yes
| UTIME
| Get current time
| yes | yes | yes
| VAXVMS
| Logical function returns TRUE if VAX/VMS
| yes | yes | yes
| WINMVS
| Logical function returns TRUE if Windows/MVS
| yes | yes | yes
| TTSEND
| Write string to terminal with various carriage control
options
| yes | yes | yes
| GETELAPSED
| Print timing info for CCPERR
| yes | yes | yes
| UGTARG
| Get command-line argument
| yes | yes | yes
| CCPSPW
| Spawns a new process to run shell command
| yes | yes | yes
| CEXIT
| Wrap around for exit routines
| yes | yes | yes
| IEOR
| Integer function: "XOR" wrap around for f2c compiler
| yes | no | no
| IOR
| Integer function: "OR" wrap around f2c compiler
| yes | no | no
| IAND
| Integer function: "AND" wrap around for f2c compiler
| yes | no | no
| RTNBKS
| Character function
| yes | yes | yes
| URENAM
| Rename a file
| no | yes | no
| GETARG
| Get command line arguments
| no | yes | no
| USTENV
| Create a logical name
| no | yes | no
| CCPAL1
| Support for CCPALC
| no | yes | yes
| IARGC
| number of command line arguments
| no | yes | no
| GETPID
| Integer function: get pid
| no | yes | no
| HCIFTIME
| local date and time, and relative to GMT
| yes | yes | yes
| SRTBEG
| Integer function: (VMS version of that in binsortint)
| no | yes | no
| SRTRLS
| Integer function: (VMS version of that in binsortint)
| no | yes | no
| SRTMRG
| Integer function: (VMS version of that in binsortint)
| no | yes | no
| SRTRET
| Integer function: (VMS version of that in binsortint)
| no | yes | no
| GDUMMY
| Dummy GL stubs iff not SGI (see routine for entry's)
| yes | no | yes
| CLEAR | Null routine (dummy GL stub) iff not SGI
| yes | no | yes
|
Descriptions of the Subroutines
CCPOPN
- SUBROUTINE CCPOPN(IIUN,LOGNAM,KSTAT,ITYPE,LREC,IFAIL)
This subroutine is used to open a file
Arguments: | INTEGER | IIUN, KSTAT, ITYPE, LREC, IFAIL
| | CHARACTER*(*) | LOGNAM
|
| Input: | IIUN | unit number. If negative no messages.
| | LOGNAM | logical file name /file name
(up to 8 characters?)
| | KSTAT | - file status flag
- 1, 'UNKNOWN'
- 2, 'SCRATCH' (see below)
- 3, 'OLD'
- 4, 'NEW'
- 5, 'READONLY' (see below)
- 6, 'PRINTER' (see below)
| | ITYPE | - file type flag
- 1, 'SEQENTIAL' & 'FORMATTED'
- 2, 'SEQENTIAL' & 'UNFORMATTED'
- 3, 'DIRECT' & 'FORMATTED'
- 4, 'DIRECT' & 'UNFORMATTED'
| | LREC | record length for direct file access.
In characters for a formatted file, in words
for an unformatted file.
Not relevant for a seqential file
| | IFAIL | 0, stop on open failure
1, continue after open failure
2, continue silently after open failure
|
| Output: | IFAIL | Unchanged if file open successful
-1, error in opening file
|
The requirement to specify that leading carriage control
characters in the output records should be obeyed (or not) can't
be implemented portably; likewise specifying readonly opening.
Some compilers accept VAXtran `carriagecontrol=' and `readonly'
specifiers; if so we use them. Others have IOINIT, which can be
used to specify the carriage control. The HPUX compiler is said
not to have any means of doing this and AIX seems to be likewise,
sigh; they both seem to obey the normal unix convention of
printing the format as-is rather than obeying the first character
as carriage control. Concentrix does obey the first column a la
VMS and `traditional' Fortran; the MIPS compilers have a compile
(link?) option to do so. [Unfortunately, carriagecontrol
specification isn't even defined in Fortan90, although
`ACTION="READ"' can be used.]
Other machines, dispos, etc
UBYTES
- SUBROUTINE UBYTES(INUM,STRING)
Return statistics about byte handling
Arguments: | INTEGER | INUM
| | CHARACTER*5 | HANDLE
|
| Input: | none
|
| Output: | INUM | number of bytes per word (set to 4)
| | HANDLE | 'WORDS' or 'BYTES'
For unformated files records are usually
counted in 'BYTES', however both VAX and
SGI swap to 'WORDS' for this file type.
|
In unix.m4 _ubytes is set at the precompilation stage
dependant on the compiler.
For SGI and Dec-Fortran the value is 'WORDS', the default is 'BYTES'. In
vms.for and
w32mvs.f the values are coded, 'WORDS' for the VMS and 'BYTES' for MVS.
In all cases INUM is coded as 4.
UCPUTM
- SUBROUTINE UCPUTM(SEC)
Get CPU time in seconds
Arguments: | SEC | REAL
|
| Input/Output | SEC |
If sec <= 0.0, initialize timer and return current
elapsed cpu time since start of execution, otherwise
return elapsed cpu since timer was initialized.
Time is in seconds.
|
UGERR
- SUBROUTINE UGERR(STATUS,ERRSTR)
Get error message string for error number in STATUS
(VMS). Actually for UNIX and MVS it ignores STATUS and always uses the
*last* error that occurred.
Arguments: | INTEGER | STATUS
| | CHARACTER*(*) | ERRSTR
|
| Input: | STATUS | Error number
(If negative print error message)
|
| Output | ERRSTR | Error message string
|
UGTENV
- SUBROUTINE UGTENV(NAMENV,VALENV)
Get value of env. variable
Arguments: | CHARACTER*(*) | NAMENV, VALENV
|
| Input: | NAMENV | Logical name (trailing blanks
are stripped)
|
| Output: | VALENV | Value
|
UGTUID
- SUBROUTINE UGTUID(USRNAM)
Get user ID
Arguments: | CHARACTER*(*) | UID
|
| Input: | none
|
| Output: | UID | user ID string
|
UIDATE
- SUBROUTINE UIDATE(IMONTH,IDAY,IYEAR)
Get date in 3 integer format.
Arguments: | INTEGER | IMONTH, IDAY, IYEAR
|
| Input: | none
|
| Output: | IMONTH | month
| | IDAY | day
| | IYEAR | year
|
Variation in IDATE syntax. Alliant uses INTEGER*4 and order is IDAY,IMONTH,IYEAR
UISATT
- SUBROUTINE UISATT(FLUN,ANSWER)
This function determines whether a program is being
run online, if this information is available.
Arguments: | INTEGER | FLUN, ANS
|
| Input: | FLUN | Fortran Unit Number
|
| Output: | ANS | 1, online
0 otherwise
|
USTIME
- SUBROUTINE USTIME(ISEC)
Get absolute time in seconds.
Arguments: | INTEGER | SEC
|
| Input: | none
|
| Output: | SEC |
|
UTIME
- SUBROUTINE UTIME(CTIME)
Get current time hh:mm:ss
Arguments: | CHARACTER*(*) | CTIME
|
| Input: | None
|
| Output: | CTIME | time as a string hh:mm:ss
|
VAXVMS
- LOGICAL FUNCTION VAXVMS()
Operating Sytem in use; returns .TRUE. if VAXVMS
Arguments: | none
|
| Input: | none
|
| Returns: | .TRUE. | for VAXVMS
| | .FALSE. | otherwise
|
UNIX and MVS routines are set to .FALSE., VMS set to .TRUE.
WINMVS
- LOGICAL FUNCTION WINMVS()
Windows mircrosoft Visual Studio
Arguments: | none
|
| Input: | none
|
| Returns: | .TRUE. | for w32mvs
| | .FALSE. | otherwise
|
UNIX and VAX routines are set to .FALSE., MVS set to .TRUE.
TTSEND
- SUBROUTINE TTSEND (IUN, STR, ICC)
Write a string to a terminal with various carriage control options
[for LAUE]
Arguments: | INTEGER | IUN, ICC
| | CHARACTER*(*) | STR
|
| Input: | IUN | Unit number for output
| | STR | The string to be output
| | ICC | 0, no carriage control at the end
of the string (for prompts), e.g.
for routine TPROMP
1, normal carriage control, e.g. for
routine TWRITE
2, no carriage control (for sending
escape/control character sequences to
ANSI/T4014 terminals, e.g. for QSCREEN
graphics routines
3, output line at current point on
screen (no leading linefeed or carriage
return - trialing does not matter)
|
| Output: | none
|
UNIX and MVS versions check if leading VMS-style carriage control characters
are obeyed for file IUN (issues of support and use are discussed in
CCPOPN.
GETELAPSED
- SUBROUTNE GETELAPSED
print timing information for CCPERR.
Contains ENTRY INITFYP to initialise elapsed time.
unix.m4 contains FPE initialisation for Sun OS.
vms.for gets user id and use for argv[0] and splits command
line into arguments (referenced in VMS routines GETARG
and IARGC.
UGTARG
- SUBROUTINE UGTARG(I, ARG)
get I'th command-line argument.
UNIX and MVS use system call getarg, except for HPUX which
calls igetarg. VMS calls vms.for routine GETARG.
Arguments: | INTEGER | I
| | CHARACTER*(*) | ARG
|
| Input: | I | number of argument
|
| Output: | ARG | argument string
|
CCPSPW
- SUBROUTINE CCPSPW(STRING)
Spawns a new process to run shell command
Arguments: | CHARACTER*(*) | STRING
|
| Input: | STRING | command
|
| Output: | none
|
Uses system (UNIX, MVS) or LIB$SPAWN (VMS)
CEXIT
- SUBROUTINE CEXIT(ICODE)
Wrap around for EXIT routines.
Arguments: | INTEGER | ICODE
|
| Input: | ICODE | error code
|
| Output: | none
|
Machine specific routines are called to exit and flush FORTRAN buffers.
EXIT in most cases. See unix.mt code for details.
RTNBKS
- CHARACTER FUNCTION RTNBKS()
Returns a Backslash for NT as unix compilers are fussy!
Arguments: | none
|
| Input: | none
|
| Returns: | '\' if MVS
' ' if UNIX or VMS
|
Result is coded in appropriate library.
URENAM
- SUBROUTINE URENAM(NAME1,NAME2,STATUS)
Rename file assigned to NAME1 to NAME2.
VMS (vms.for) only.
Arguments: | CHARACTER*(*) | NAME1, NAME2
| | INTEGER | STATUS
|
| Input: | NAME1 | file name
| | NAME2 | file name
|
| Output: | STATUS | 0, if ok
<> if an error
|
GETARG
- SUBROUTINE GETARG(INUM,LINE)
Get INUM'th command line argument or ' ' into LINE
VMS (vms.for) only. Replaces getarg system call.
Arguments: | INTEGER | INUM
| | CHARACTER*(*) | LINE
|
| Input: | INUM | desired command line argument
|
| Output: | LINE | command line argument
|
Gets the value from a common block (ARGS) set up in ENTRY INITFYP of
GETELAPSED.
USTENV
- SUBROUTINE USTENV(LINE,IRESULT)
Logical name assignment
VMS (vms.for) only. UNIX and MVS versions use
library.c version which accesses putenv (POSIX) or setenv
(non-POSIX).
Arguments: | CHARACTER*(*) | LINE
| | INTEGER | IRESULT
|
| Input: | LINE | line takes the form
'<logical name>=<filename>'
|
| Output: | IRESULT | 0 iff successful
|
Under VMS there is no standard way of setting the environmental variables.
The work around stores the file name in a STRUCTURE array.
CCPAL1
- SUBROUTINE CCPAL1 (ROUTNE, N, TYPE, LENGTH)
Arrange to call ROUTNE with N TYPEd array arguments of given.
LENGTH (see calling routine CCPALC
for fuller discussion).
Arguments: | EXTERNAL | ROUTNE
| | INTEGER | N
| | INTEGER*(*) | LENGTH
| | CHARACTER*1 (*) | TYPE
| Input | ROUTNE | routine to call
| | N | number of arguements to ROUTNE (<=12)
| | TYPE | - type of argument to ROUTNE
- 'I': INTEGER
- 'R': REAL
- 'D': DOUBLE
- 'C': COMPLEX
| | LENGTH | number of elements on each array
|
| Output: | none
|
Note: assumes 32 bit (4 byte words).
VMS and MVS routines. UNIX uses a C routine in
library.c.
IARGC
- INTEGER FUNCTION IARGC(IDUMMY)
Gets the number of command-line arguments.
VMS only. UNIX and MVS use system call iargc.
Arguments: | INTEGER (dummy) | IDUMMY
|
| Input: | IDUMMY | dummy argument
|
| Returns: | | number of command-line arguments.
|
Gets value from common block (ARGCOUNT) variable set up in ENTRY INITFYP of
GETELAPSED. If value not set calls INITFYP.
GETPID
- INTEGER FUNCTION GETPID(IDUMMY)
Get process ID.
VMS only, using VMS specific system call. UNIX and MVS use system call
getpid.
Arguments: | INTEGER (dummy) | IDUMMY
|
| Input: | IDUMMY | dummy argument
|
| Returns: | | process id
|
HCIFTIME
- SUBROUTINE HCIFTIME(CIFTIME)
Get local time and difference from GMT.
1997-08-12T13:55:58-05:00
local GMT
Arguments: | CHARACTER*(*) (>25) | CIFTIME
|
| Input: | none
|
| Output: | CIFTIME | local time stamp
and difference to GMT.
|
version of the routine in SCALA.
VMS uses f90 intrinsic Date_and_Time. MVS uses same intrinic.
Using f77: works on VMS Fortran V7 but not earlier versions
works on Digital UNIX V4.0F.
UNIX uses fortran system call Ltime and gmtime which
disect a UNIX time into month, day, etc., either for the local time zone
or as GMT.
Binsortint Routines
SRTBEG, SRTRLS, SRTMRG and SRTRET in this file are the VMS
versions of library routines in binsortint.c (UNIX) and
w32binsort (MVS). binsortint is a set of routines used as an interface to
binsort mainly from FORTRAN programs.
SRTBEG
- INTEGER FUNCTION SRTBEG(NKEYS,KEYB,LRECL,MEMSIZE)
integer binsort -sort initialisation. Launches VMS specific sort library
routine.
Arguments: | INTEGER | NKEYS, LRECL, MEMSIZE
| | INTEGER*2(*) | KEYB
|
| Input: | NKEYS | number of keys
| | KEYB | for each key block have five data items
- key type (=7 only REAL implemented)
- sort order (ascending (0) or descending (1))
- position within record (BYTES, 1st is position 0)
- length (data units chars, shorts ...)
- mask applied to data element before
comparison (= 0 no mask, only implemented)
| | LRECL | (fixed) length of record (BYTES)
| | MEMSIZE | size of memory used by sort (BYTES)
if == 0, default size
| |
| Returns: | == 0 | status OK
| | == 1 | failure
|
SRTRLS
- INTEGER FUNCTION SRTRLS(RECORD)
integer binsort -pipes one record into sort routine
Arguments: | REAL(*) | RECORD
|
| Input: | RECORD | one record of data to be sorted
|
| Returns: | ==0 | status OK
|
SRTMRG
- INTEGER FUNCTION SRTMRG()
integer binsort -finishes sequence of input records(?)
Arguments: | none
|
| Returns | ==0 | status OK
|
SRTRET
- INTEGER FUNCTION SRTRET(RECORD)
integer binsort -gets one record from sort routine
Arguments: | REAL(*) | RECORD
|
| Input: | none
|
| Output: | RECORD | one record of sorted data
|
| Returns: | ==0 | status OK
| | ==-1 | sort failure
|
|