Application Programmer’s Library

Reference Manual, Volume 1

004–2165–002
Copyright © 1994, 1995, 1997–1999 Silicon Graphics, Inc. All Rights Reserved. This manual or parts thereof may not be
reproduced in any form unless permitted by contract or by written permission of Silicon Graphics, Inc.

Portions of this manual are based on material reproduced or adapted from IEEE Std 1003.9–1992, copyright (c) 1992 by the
Institute of Electrical and Electronics Engineers, Inc. The IEEE takes no responsibility for and will assume no liability for damages
resulting from the reader’s misinterpretation of said information resulting from the placement and context in this publication.
Information is reproduced with the permission of the IEEE.

LIMITED AND RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in the Rights in Data clause at FAR
52.227-14 and/or in similar or successor clauses in the FAR, or in the DOD, DOE or NASA FAR Supplements. Unpublished rights
reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre
Pkwy., Mountain View, CA 94043-1351.

Autotasking, CF77, Cray, Cray Ada, CraySoft, Cray Y-MP, Cray-1, CRInform, CRI/TurboKiva, HSX, LibSci, MPP Apprentice, SSD,
SUPERCLUSTER, UNICOS, X-MP EA, and UNICOS/mk are federally registered trademarks and Because no workstation is an
island, CCI, CCMT, CF90, CFT, CFT2, CFT77, ConCurrent Maintenance Tools, COS, Cray Animation Theater, Cray APP, Cray C90,
Cray C90D, Cray C++ Compiling System, CrayDoc, Cray EL, Cray J90, Cray J90se, CrayLink, Cray NQS, Cray/REELlibrarian,
Cray S-MP, Cray SSD-T90, Cray SV1, Cray T90, Cray T3D, Cray T3E, CrayTutor, Cray X-MP, Cray XMS, Cray-2, CSIM, CVT,
Delivering the power . . ., DGauss, Docview, EMDS, GigaRing, HEXAR, IOS, ND Series Network Disk Array,
Network Queuing Environment, Network Queuing Tools, OLNET, RQS, SEGLDR, SMARTE, SUPERLINK,
System Maintenance and Remote Testing Environment, Trusted UNICOS, and UNICOS MAX are trademarks of Cray Research,
L.L.C., a wholly owned subsidiary of Silicon Graphics, Inc.

SGI is a trademark of Silicon Graphics, Inc. IRIX and Silicon Graphics are registered trademarks and the Silicon Graphics logo is a
trademark of Silicon Graphics, Inc.

CDC is a trademark of Control Data Systems, Inc. DEC, ULTRIX, VAX, and VMS are trademarks of Digital Equipment
Corporation. ER90 is a trademark of EMASS, Inc. ETA is a trademark of ETA Systems, Inc. IBM is a trademark of International
Business Machines Corporation. MIPS is a trademark of MIPS Computer Systems. UNIX is a registered trademark in the United
States and other countries, licensed exclusively through X/Open Company Limited. X/Open is a registered trademark of X/Open
Company Ltd. X Window System and the X device are trademarks of The Open Group.

The UNICOS operating system is derived from UNIX® System V. The UNICOS operating system is also based in part on the
Fourth Berkeley Software Distribution (BSD) under license from The Regents of the University of California.
 New Features

Application Programmer’s Library Reference Manual, Volume 1 004–2165–002

This manual describes the Application Library for CrayLibs 3.3. The changes to the manual are detailed
below.
New conversion routines are available for IRIX systems. See IEG2MIPS(3F) and VAX2MIPS(3F).
New FFIO layers are available for IRIX systems. See INTRO_FFIO(3F) for details. In addition, a new
routine was add which maps an error number to an error message string. See ffstrerror(3C) for details.
 Record of Revision

Version Description

1.2 October 1994

Original Printing. This manual supports the Programming Environment 1.2 release.
Many of the routines in this manual were originally printed in the UNICOS Fortran
Language Reference Manual, publication SR–2079.

2.0 November 1995

Reprint to support the Programming Environment 2.0 release.

3.0 June 1997

Reprint to support the Programming Environment 3.0 release. The Shared Memory
Library routines (SHMEM) are deferred until a later release on IRIX systems.

3.1 August 1998

Reprint to support the Programming Environment 3.1 release. The printed text of
this manual was made available in postscript (.ps) format only for this release.

3.3 July 1999

Reprint to support the Programming Environment 3.3 release. The printed text of
this manual was made available in postscript (.ps) format only for this release.

004–2165–002 i
 About This Guide

This publication documents Fortran-callable subprograms and routines

available to users of the CrayLibs product, which is included in the
Programming Environment (PE) 3.3 release.
The CrayLibs product contains several libraries; the library routines can be
called from source code written in a number of programming languages,
including Fortran, C, Pascal, and assembly language. The information in this
document supplements information contained in other manuals of the
Programming Environment documentation set.
This is a reference manual for application and system programmers. Readers
should also have a working knowledge of either the UNICOS, UNICOS/mk, or
UNIX operating system and a working knowledge of the Fortran or C
programming language.
Portions of this manual are based on materials reproduced or adapted from
IEEE Std 1003.9–1992, copyright (c) 1992 by the Institute of Electrical and
Electronics Engineers, Inc. The IEEE takes no responsibility for and will assume
no liability for damages resulting from the placement and context in this
publication. Information is reproduced with the permission of the IEEE.

Documentation Organization
The printed versions of the application library man pages appear in 2 volumes
and are grouped according to topics. See the INTRO_APPLIBS(3F) man page
for details about the contents of each volume.
Each topic section also has an introductory man page which explains the
contents of the section and provides other information about the usage of those
routines. The following introductory man pages are available:
INTRO_CONVERSION(3F) INTRO_PROGAIDS(3F)
INTRO_FFIO(3F) INTRO_PXF(3F)

INTRO_HEAP(3F) INTRO_SORTSEARCH(3F)

INTRO_INTERFACE(3F) INTRO_STREAMS(3)

INTRO_IO(3F) INTRO_SYNC(3F)

004–2165–002 iii
Application Programmer’s Library Reference Manual, Volume 1

Related Publications
The following documents contain additional information that may be helpful:
• Segment Loader (SEGLDR) and ld Reference Manual
• UNICOS User Commands Reference Manual
• Guide to Parallel Vector Applications
• Tape Subsystem User’s Guide
• UNICOS System Libraries Reference Manual
• UNICOS System Calls Reference Manual
• Application Programmer’s I/O Guide
• Optimizing Application Code on UNICOS Systems
The following manuals document the CrayLibs product. All man pages in these
manuals can also be viewed online by using the man command:
• Scientific Library Reference Manual
• Intrinsic Procedures Reference Manual
• Scientific Libraries Ready Reference
• Application Programmer’s Library Ready Reference
In addition to these documents, several documents are available that describe
the compiler systems available on UNICOS and UNICOS/mk. Some of these
manuals are:
• CF90 Ready Reference
• CF90 Commands and Directives Reference Manual
• Fortran Language Reference Manual, Volume 1
• Fortran Language Reference Manual, Volume 2
• Fortran Language Reference Manual, Volume 3
• Cray C/C++ Reference Manual

iv 004–2165–002
 About This Guide

The following manuals document the compilers that are available on IRIX
systems:
• MIPSPro 7 Fortran 90 Commands and Directives Reference Manual
• MIPSpro Assembly Language Programmer’s Guide
• MIPSpro Fortran 77 Language Reference Manual
• MIPSpro Fortran 77 Programmer’s Guide
• MIPSpro 64-Bit Porting and Transition Guide

Obtaining Publications
SGI maintains information about available publications at the following URL:
http://techpubs.sgi.com/library

This Web site contains information that allows you to browse documents online,
order documents, and send feedback to SGI. You can also order a printed SGI
document by calling 1 800 627 9307.
The User Publications Catalog describes the availability and content of all Cray
hardware and software documents that are available to customers. Customers
who subscribe to the Cray Inform (CRInform) program can access this
information on the CRInform system.
SGI maintains information on publicly available Cray documents at the
following URL:
http://www.cray.com/swpubs/

This Web site contains information that allows you to browse documents online
and send feedback to SGI. To order a printed Cray document, either call
+1 651 683 5907 or send a facsimile of your request to fax number
+1 651 683 3840. SGI employees may also order printed Cray documents by
sending their orders via electronic mail to orderdsk.
Customers outside of the United States and Canada should contact their local
service organization for ordering information and documentation information.

Conventions
The following conventions are used throughout this document:

004–2165–002 v
Application Programmer’s Library Reference Manual, Volume 1

Convention Meaning
command This fixed-space font denotes literal items such as
commands, files, routines, path names, signals,
messages, and programming language structures.
variable Italic typeface denotes variable entries and words
or concepts being defined.
user input This bold, fixed-space font denotes literal items
that the user enters in interactive sessions.
Output is shown in nonbold, fixed-space font.
In addition to these formatting conventions, several naming conventions are
used throughout the documentation. “Cray PVP systems” denotes all
configurations of Cray parallel vector processing (PVP) systems that run the
UNICOS operating system. “Cray MPP systems” denotes all configurations of
the Cray T3E series that run the UNICOS/mk operating system. “IRIX
systems” denotes SGI platforms which run the IRIX operating system.
The default shell in the UNICOS and UNICOS/mk operating systems, referred
to as the standard shell, is a version of the Korn shell that conforms to the
following standards:
• Institute of Electrical and Electronics Engineers (IEEE) Portable Operating
System Interface (POSIX) Standard 1003.2–1992
• X/Open Portability Guide, Issue 4 (XPG4)
The UNICOS and UNICOS/mk operating systems also support the optional use
of the C shell.

Man page sections

The entries in this document are based on a common format. The following list
shows the order of sections in an entry and describes each section. Most entries
contain only a subset of these sections.

Section heading Description

NAME Specifies the name of the entry and briefly states
its function.
SYNOPSIS Presents the syntax of the entry.
IMPLEMENTATION Identifies the systems to which the entry applies.

vi 004–2165–002
 About This Guide

STANDARDS Provides information about the portability of a

utility or routine.
DESCRIPTION Discusses the entry in detail.
NOTES Presents items of particular importance.
CAUTIONS Describes actions that can destroy data or
produce undesired results.
WARNINGS Describes actions that can harm people,
equipment, or system software.
ENVIRONMENT Describes predefined shell variables that
VARIABLES determine some characteristics of the shell or that
affect the behavior of some programs, commands,
or utilities.
RETURN VALUES Describes possible return values that indicate a
library or system call executed successfully, or
identifies the error condition under which it
failed.
EXIT STATUS Describes possible exit status values that indicate
whether the command or utility executed
successfully.
MESSAGES Describes informational, diagnostic, and error
messages that may appear. Self-explanatory
messages are not listed.
ERRORS Documents error codes. Applies only to system
calls.
FORTRAN Describes how to call a system call from Fortran.
EXTENSIONS Applies only to system calls.
BUGS Indicates known bugs and deficiencies.
EXAMPLES Shows examples of usage.
FILES Lists files that are either part of the entry or are
related to it.

004–2165–002 vii
Application Programmer’s Library Reference Manual, Volume 1

SEE ALSO Lists entries and publications that contain related

information.

Reader Comments
If you have comments about the technical accuracy, content, or organization of
this document, please tell us. Be sure to include the title and part number of
the document with your comments.
You can contact us in any of the following ways:
• Send e-mail to the following address:
[email protected]

• Send a fax to the attention of “Technical Publications” at: +1 650 932 0801.
• Use the Feedback option on the Technical Publications Library World Wide
Web page:
http://techpubs.sgi.com

• Call the Technical Publications Group, through the Technical Assistance

Center, using one of the following numbers:
For SGI IRIX based operating systems: 1 800 800 4SGI
For UNICOS or UNICOS/mk based operating systems or Cray Origin 2000
systems: 1 800 950 2729 (toll free from the United States and Canada) or
+1 651 683 5600
• Send mail to the following address:
Technical Publications
SGI
1600 Amphitheatre Pkwy.
Mountain View, California 94043–1351
We value your comments and will respond to them promptly.

viii 004–2165–002
CONTENTS

Introductory page

intro_applibs, INTRO_APPLIBS ..................... Introduction to CrayLibs Application Libraries ............................................ 1

Calling Sequence
callseq .................................................................... Details the calling sequence for UNICOS systems ....................................... 3

I/O routines
intro_io, INTRO_IO ............................................. Introduction to Fortran-callable I/O routines ................................................ 9
acptbad, ACPTBAD .................................................. Makes bad data available ............................................................................ 19
aqclose, AQCLOSE .................................................. Closes an asynchronous queued I/O file ..................................................... 22
aqopen, AQOPEN, AQOPENM .................................... Opens a file for asynchronous queued I/O .................................................. 23
aqread, AQREAD, AQREADC .................................... Queues a simple or compound asynchronous I/O read request .................. 25
aqrecall, AQRECALL ............................................. Waits for completion of asynchronous queued I/O request ........................ 27
aqstat, AQSTAT ...................................................... Checks the status of asynchronous queued I/O requests ............................ 29
aqwait, AQWAIT ...................................................... Waits for completion of asynchronous queued I/O requests ...................... 31
aqwrite, AQWRITE, AQWRITEC ............................ Queues a simple or compound asynchronous I/O write request ................. 32
asnctl, ASNCTL ...................................................... Controls function of ASSIGN, ASNFILE, ASNUNIT, and ASNRM
routines ........................................................................................................ 34
asnqfile, ASNQFILE, ASNQUNIT ........................ Returns the assign options currently in effect for a file name or
unit number ................................................................................................. 36
assign, ASSIGN, ASNUNIT, ASNFILE, ASNRM ... Provides library interface to assign processing ....................................... 38
asyncms, ASYNCMS, ASYNCDR ............................... Sets I/O mode for random-access routines to asynchronous ...................... 40
checkms, CHECKMS, CHECKDR ............................... Checks status of asynchronous random-access I/O operation ..................... 42
checktp, CHECKTP .................................................. Checks tape position .................................................................................... 44
closev, CLOSEV ...................................................... Closes volume and mounts next volume in Volume Identifier list ............ 45
closms, CLOSMS, CLOSDR ...................................... Writes master index and closes random-access file .................................... 46
endsp, ENDSP ........................................................... Disables special tape processing ................................................................. 48
findms, FINDMS ...................................................... Reads record into data buffers used by random-access routines ................ 49
flush, FLUSH ........................................................... Writes data buffered by Fortran output statements to a file ....................... 51
fsup, FSUP, ISUP .................................................... Suppress values in Fortran edit-directed output .......................................... 53
gettp, GETTP ........................................................... Gets information about an opened tape file ................................................ 54
getwa, GETWA, SEEK ............................................... Synchronously and asynchronously reads data from the
word-addressable, random-access file ......................................................... 57
gtstdptr, GTSTDPTR ............................................. Returns pointer to standard file ................................................................... 59
numblks, NUMBLKS .................................................. Returns the current size of a file in 4096-byte blocks ................................ 60
openms, OPENMS, OPENDR ...................................... Opens a local file as a random-access file that can be accessed or
changed by the record-addressable, random-access file I/O routines ......... 61
putwa, PUTWA, APUTWA ........................................... Writes to a word-addressable, random-access file ...................................... 64
read, READ, READP .................................................. Reads words, full or partial record modes .................................................. 66
readc, READC, READCP ........................................... Reads characters, full or partial record mode ............................................. 68
readibm, READIBM .................................................. Reads two IBM 32-bit floating-point words from each Cray Research
64-bit word .................................................................................................. 70
readms, READMS, READDR ...................................... Reads a record from a random-access file to memory ............................... 71
rnl, RNLFLAG, RNLDELM, RNLSEP, RNLREP,
RNLCOMM .................................................................... Manipulates characters recognized by NAMELIST ..................................... 73
rnlecho, RNLECHO .................................................. Specifies output unit for NAMELIST error messages and echo lines ......... 75

004– 2165– 002 ix

rnlskip, RNLSKIP .................................................. Takes appropriate action when an undesired NAMELIST group is
encountered .................................................................................................. 76
rnltype, RNLTYPE .................................................. Determines action if type mismatch occurs across equal sign on
NAMELIST input record ............................................................................. 77
setsp, SETSP ........................................................... Enables and disables EOV processing ........................................................ 78
settp, SETTP ........................................................... Positions a tape file at a tape block and/or a tape volume ......................... 79
skipbad, SKIPBAD .................................................. Skips bad data ............................................................................................. 81
skipf, SKIPF ........................................................... Skips files .................................................................................................... 83
startsp, STARTSP .................................................. Enables special tape processing .................................................................. 85
stindx, STINDX, STINDR ...................................... Allows an index to be used as the current index by creating a
subindex ....................................................................................................... 86
syncms, SYNCMS, SYNCDR ...................................... Sets I/O mode for random-access routines to synchronous ........................ 88
tsync, TSYNC ........................................................... Requests tape synchronization ..................................................................... 90
waitms, WAITMS, WAITDR ...................................... Waits for completion of an asynchronous I/O operation ............................ 91
wclose, WCLOSE ...................................................... Finalizes changes and closes word-addressable, random-access file .......... 93
wnl, WNLFLAG, WNLDELM, WNLSEP, WNLREP ....... Provides user control of NAMELIST output format ................................... 94
wnlline, WNLLINE .................................................. Allows each NAMELIST variable to begin on a new line ......................... 96
wnllong, WNLLONG .................................................. Selects NAMELIST output line length ........................................................ 97
wopen, WOPEN ........................................................... Opens a word-addressable, random-access file ........................................... 98
write, WRITE, WRITEP ........................................... Writes words, full or partial record mode ................................................. 100
writec, WRITEC, WRITECP .................................... Writes characters, full or partial record mode .......................................... 102
writibm, WRITIBM .................................................. Writes two IBM 32-bit floating-point words from each Cray 64-bit
word ........................................................................................................... 104
writms, WRITMS, WRITDR ...................................... Writes to a random-access file on disk ..................................................... 105

FFIO routines
intro_ffio, INTRO_FFIO ................................... Describes performance options available with the FFIO layers ............... 113
ffassign .................................................................. Provides library interface to assign processing ......................................... 127
fffcntl .................................................................... Performs functions on files opened using flexible file I/O ....................... 128
ffiolock, ffiounlock ........................................ Provide locking for FFIO functions .......................................................... 136
fflistio .................................................................. Initiates a list of I/O requests using flexible file I/O ................................ 137
ffopen, ffopens, ffclose, ffopenf,
ffclosef .................................................................. Opens or closes a file using flexible file I/O ............................................ 141
ffpos ......................................................................... Positions files opened using flexible file I/O ............................................ 145
ffread, ffwrite, ffweof, ffweod,
ffreadf, ffwritef, ffweodf, ffweoff,
ffflush .................................................................... Provides flexible file I/O ........................................................................... 149
ffreada .................................................................... Provides asynchronous read using flexible file I/O ................................... 152
ffseek, ffbksp, ffseekf, ffbkspf ................. Repositions a flexible file I/O file ............................................................. 156
ffsetsp .................................................................... Initiates EOV processing for files opened using flexible file I/O ............. 159
ffstrerror, FFSTRERROR ................................... Get FFIO error message string .................................................................. 160
ffwritea .................................................................. Provides asynchronous write using flexible file I/O ................................. 161
glio_group, glio_group_mpi,
glio_group_shmem ............................................... Defines a group of processes to be associated with a global file. ............ 163

PXF library routines

intro_pxf, INTRO_PXF ........................................ Introduction to PXF POSIX library .......................................................... 165
ipxfargc, IPXFARGC ............................................. Returns the number of command-line arguments excluding the
command name .......................................................................................... 170
ipxfwexitstatus, IPXFWEXITSTATUS ............ Returns the lower bits of exit argument ................................................ 171

x 004– 2165– 002

ipxfwstopsig, IPXFWSTOPSIG .......................... Returns part of the lower bits of signal number that terminates child
process ....................................................................................................... 174
ipxfwtermsig, IPXFWTERMSIG .......................... Returns lower bit of signal that terminates a child process ...................... 177
pxfaccess, PXFACCESS ........................................ Checks the accessibility of a named file ................................................... 180
pxfalarm, PXFALARM ............................................. Schedule alarm signal ................................................................................ 182
pxfchdir, PXFCHDIR ............................................. Changes the current directory to a specified directory ............................. 184
pxfchmod, PXFCHMOD ............................................. Sets file modes for a named file ................................................................ 186
pxfchown, PXFCHOWN ............................................. Changes the owner and group of a file ..................................................... 189
pxfchroot, PXFCHROOT ........................................ Changes the root directory to a specified directory .................................. 191
pxfclearenv, PXFCLEARENV ............................... Clears all environment variables ............................................................... 193
pxfconst, PXFCONST, PXFISCONST,
IPXFCONST ................................................................ Returns the value associated with symbolic constants .............................. 195
pxfcreat, PXFCREAT ............................................. Creates a new file or rewrites an existing file .......................................... 199
pxfctermid, PXFCTERMID ................................... Generates terminal pathname .................................................................... 202
pxfdirectory, PXFOPENDIR, PXFREADDIR,
PXFREWINDDIR, PXFCLOSEDIR, .......................... Performs directory operations ................................................................... 204
pxfestrget, PXFESTRGET ................................... Accesses a single string element of a structure component that is an
array ........................................................................................................... 207
pxfexecv, PXFEXECV, PXFEXECVE,
PXFEXECVP ................................................................ Executes a new process image file ............................................................ 209
pxffcntl, PXFFCNTL ............................................. Provides a subset of fcntl(2) functionality, except the third
argument is always an integer ................................................................... 216
pxffileno, PXFFILENO ........................................ Returns the file descriptor for a specified unit .......................................... 218
pxffork, PXFFORK .................................................. Creates a process ....................................................................................... 219
pxfgetarg, PXFGETARG ........................................ Returns a command-line argument ............................................................ 222
pxfgetcwd, PXFGETCWD ........................................ Gets the pathname of the working directory ............................................. 223
pxfgetegid, PXFGETEGID ................................... Gets the effective group ID ....................................................................... 225
pxfgetenv, PXFGETENV ........................................ Returns a value for the environment name ............................................... 226
pxfgeteuid, PXFGETEUID ................................... Gets effective user ID ............................................................................... 229
pxfgetgid, PXFGETGID ........................................ Gets the real group ID ............................................................................... 230
pxfgetgrgid, PXFGETGRGID ............................... Gets group information using the group ID .............................................. 231
pxfgetgrnam, PXFGETGRNAM ............................... Gets group information using the group name ......................................... 233
pxfgetgroups, PXFGETGROUPS .......................... Gets supplementary group IDs .................................................................. 235
pxfgetlogin, PXFGETLOGIN ............................... Gets user name .......................................................................................... 237
pxfgetpgrp, PXFGETPGRP ................................... Gets the process group ID ......................................................................... 239
pxfgetpid, PXFGETPID ........................................ Gets the process ID ................................................................................... 241
pxfgetppid, PXFGETPPID ................................... Gets the parent process ID ........................................................................ 243
pxfgetpwnam, PXFGETPWNAM ............................... Gets password information about login name ........................................... 245
pxfgetpwuid, PXFGETPWUID ............................... Gets password information by using user ID ............................................ 247
pxfgetuid, PXFGETUID ........................................ Gets the real user ID ................................................................................. 249
pxfintget, PXFINTGET ........................................ Allows values stored in individual components of a structure to be
extracted and used ..................................................................................... 250
pxfintset, PXFINTSET ........................................ Allows components of a structure to be set or modified .......................... 251
pxfisatty, PXFISATTY ........................................ Determines if file descriptor corresponds to a valid file descriptor .......... 252
pxfisblk, PXFISBLK ............................................. Tests for block special file ........................................................................ 254
pxfischr, PXFISCHR ............................................. Tests for character special file ................................................................... 256
pxfisdir, PXFISDIR ............................................. Tests for directory file ............................................................................... 258
pxfisfifo, PXFISFIFO ........................................ Tests for pipe or a FIFO special file ......................................................... 260
pxfisreg, PXFISREG ............................................. Tests for regular file .................................................................................. 262
pxflink, PXFLINK .................................................. Creates a link to a file ............................................................................... 264
pxflocaltime, PXFLOCALTIME .......................... Converts to local time ............................................................................... 266

004– 2165– 002 xi

pxfopen, PXFOPEN .................................................. Provides a Fortran interface to the open(2) system call ......................... 268
pxfrename, PXFRENAME ........................................ Renames a file ........................................................................................... 271
pxfrmdir, PXFRMDIR ............................................. Removes a directory entry ........................................................................ 273
pxfsetenv, PXFSETENV ........................................ Sets environment variable pair .................................................................. 275
pxfsetgid, PXFSETGID ........................................ Sets group ID ............................................................................................ 277
pxfsetpgid, PXFSETPGID ................................... Set process group ID ................................................................................. 279
pxfsetsid, PXFSETSID ........................................ Creates a new session for a calling process .............................................. 281
pxfsetuid, PXFSETUID ........................................ Sets user ID ............................................................................................... 283
pxfsleep, PXFSLEEP ............................................. Delays process execution .......................................................................... 285
pxfstat, PXFSTAT .................................................. Retrieves the file status ............................................................................. 287
pxfstrget, PXFSTRGET ........................................ Allows values stored in individual components of a structure to be
extracted and used ..................................................................................... 289
pxfstrset, PXFSTRSET ........................................ Allows values stored in individual components of a structure to be
set ............................................................................................................... 291
pxfstructcopy, PXFSTRUCTCOPY ..................... Copies structure ......................................................................................... 293
pxfstructcreate, PXFSTRUCTCREATE ............ Creates an instance of the desired structure and returns a nonzero
handle in the argument jhandle ................................................................. 295
pxfstructfree, PXFSTRUCTFREE ..................... Deletes the instance of the structure referenced by jhandle ..................... 297
pxfsysconf, PXFSYSCONF ................................... Retrieves the value of configurable system variables ............................... 299
pxftime, PXFTIME .................................................. Gets system time ....................................................................................... 301
pxftimes, PXFTIMES ............................................. Gets process times ..................................................................................... 303
pxfucompare, PXFUCOMPARE ............................... Compares unsigned integers ...................................................................... 305
pxfumask, PXFUMASK ............................................. Sets the file creation mask ........................................................................ 307
pxfuname, PXFUNAME ............................................. Retrieves the operating system name ........................................................ 309
pxfunlink, PXFUNLINK ........................................ Removes a directory entry ........................................................................ 311
pxfwait, PXFWAIT, PXFWAITPID ........................ Obtains information about a calling process’ child process ..................... 313
pxfwifexited, PXFWIFEXITED .......................... Determines if child process exited with exit ......................................... 317
pxfwifsignaled, PXFWIFSIGNALED ................. Determines if the child process terminated because of a signal ............... 319
pxfwifstopped, PXFWIFSTOPPED ..................... Determines if a child process has stopped ................................................ 322
pxfutime, PXFUTIME ............................................. Sets access and modification times of a file ............................................. 325

xii 004– 2165– 002

INTRO_APPLIBS ( 3F ) INTRO_APPLIBS ( 3F )

NAME
INTRO_APPLIBS – Introduction to CrayLibs Application Libraries

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This manual describes different routines provided in the CrayLibs Application Libraries, which includes
libsma, libf, and libu. A library is a collection of subroutines usually organized around a specific
subject such as I/O. Intrinsic procedures and subprograms are documented in the Intrinsic Procedures
Reference Manual.
The printed versions of the routines appear in two volumes and are grouped according to topics.
Volume 1 contains the following topic sections:
• Calling Sequence: Calling sequences for UNICOS systems.
• I/O Routines: File positioning, auxiliary NAMELIST, logical record, random-access file, asynchronous
queued I/O, output suppression, and BOV/EOV tape processing.
• FFIO Routines: File opening, closing, read, and write for files using flexible file I/O (FFIO).
• Specialized Libraries: POSIX interface routines.
Volume 2 contains the following topic sections:
• Conversion Routines: Foreign file conversion (IBM, CDC, and VAX), numeric conversion, ASCII
conversion, IEEE conversion, and other conversion routines.
• System Interface Routines: Job control, floating-point interrupt, and special purpose interface routines.
• Heap, Table, and SDS Management Routines: Routines for manipulating and managing memory within
heaps, tables, and secondary data segments (SDS).
• Programming Aid Routines: Flowtrace, traceback, dump, exchange package processing, and signal
routines.
• Streams: Hardware streaming routines
• Synchronization Routines: Task, lock, event, and barrier routines.
• Search Routines: Search options to find maximum and minimum elements in vectors.
• Appendix A: C Library Interface Routines: C routines and system calls that provide a C interface to
Fortran programmers.

004– 2165– 002 1

INTRO_APPLIBS ( 3F ) INTRO_APPLIBS ( 3F )

SUBPROGRAM CLASSIFICATION
Unless otherwise noted, all routines in this manual are described as Fortran or C subroutines or functions. In
some cases (for example, SECOND), the routine may be called as either a subroutine or a function. Programs
written in C can call library functions intended for use by Fortran programs. C programmers are responsible
for passing arguments by address and not by value, which is the normal case in C.
C programs can also be written to accommodate Fortran users. Such programs must be written to accept
arguments passed by address rather than by value, which is the normal case in C. The program names must
be in uppercase.
Pascal programs can call library functions intended for use by Fortran programs. Similarly, Fortran codes
can invoke subroutines and functions written in Pascal. Unlike C, the Pascal compiler passes all arguments
by address, and it supports several predefined conversion functions to facilitate communication with Fortran
routines.
For more information on interlanguage calls, see Interlanguage Programming Conventions.

LIBRARY USAGE AND LOADERS

If you created a routine with the same name as a default routine (one described in this manual or in your
Fortran reference manual), your routine will be loaded if you specify it on your loader’s command line. See
the loader reference material for your compiler for more information.

NOTES
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.

SEE ALSO
INTRO_CONVERSION(3F), INTRO_FFIO(3F), INTRO_HEAP(3F), INTRO_INTERFACE(3F),
INTRO_IO(3F), INTRO_PROGAIDS(3F), INTRO_PXF(3F), INTRO_SHMEM(3),
INTRO_SORTSEARCH(3F), INTRO_STREAMS(3), INTRO_SYNC(3F)

2 004– 2165– 002

CALLSEQ ( 3F ) CALLSEQ ( 3F )

NAME
callseq – Details the calling sequence for UNICOS systems

IMPLEMENTATION
UNICOS systems

DESCRIPTION
This section details how subprograms are interlinked while running on UNICOS systems. A subprogram
corresponds to a function in C, a PROGRAM, SUBROUTINE or FUNCTION in Fortran, or a set of
ENTER/EXIT macros in CAL.
Frame
A frame is a contiguous region of memory associated with a subprogram. At a minimum, a frame contains a
pointer to the Traceback Name Block (TNB), the address of the caller (the return address, register B00), the
address of the argument list (register B01), and the address of the caller’s frame (register B02).
All subprograms have a frame except certain low-level (BASELVL) routines (see following).
In a stack environment (the default) the frame is allocated on the stack when the subprogram is invoked and
the memory is released for re-use when the subprogram exits. A stack frame (see figure 1) will also contain
storage for local variables and argument lists. For subprograms that are compiled with a static option, the
frame is allocated at compile-time and is never released. Local variables and argument lists are also
allocated at compile-time, though not as part of the frame.
Static and stack subprograms may call each other, but a static routine should not be called recursively nor
should it be used in a multitasking environment.
Stack
The stack is created prior to entering the main program. The stack is implemented as one or more blocks
(called stack segments) of memory in the user heap. The B66 register points to the current top of the stack;
the B67 register points to the end of the current stack segment. As subprograms are invoked, their stack
frame is created by incrementing the top of the stack by the size of the stack frame. When a stack frame
cannot fit in the current segment this is called a stack overflow, and the stack manager is called to extend the
segment, if possible, or to allocate a new segment from the heap. A link is established between the old and
new segments and processing continues. When exiting subprograms, the top of the stack is decremented by
the size of the stack frame. When a stack segment is empty, it may be returned to the heap.
The stack manager maintains a 128-word pad area beyond the end of the stack within the current stack
segment. This is done so that subprograms can save B and T registers prior to checking for a segment
overflow. If the stack manager must allocate a new segment, the saved B and T registers will be copied to
the new segment. If the stack manager cannot extend a segment nor allocate a new segment to contain a
stack frame, the program terminates with a stack allocation failure.

004– 2165– 002 3

CALLSEQ ( 3F ) CALLSEQ ( 3F )

Traceback
The traceback information is a statically allocated block called the Traceback Name Block (TNB) which is
generated at compile-time. The TNB contains information about each subprogram including its name, the
address of its entry point, and information about the contents of the frame. The subprogram entry sequence
puts the address of the TNB into the first word of the frame (non-BASELVL routines only). The TNB
information can be used by run-time debuggers or to print out a traceback in the event of an abnormal
program termination.
Subprogram Arguments
Most subprograms pass their arguments (both call-by-address and call-by-value arguments) in consecutive
memory locations called an argument list. A one-word Argument List Header (ALH) is added to the
beginning of the argument list. The ALH contains the number of words of arguments (for use by
subprograms which accept a variable number of arguments) and the line number of the caller (for use by
traceback and run-time debugging).
Certain intrinsic functions and VFUNCTIONS do not use an argument list. Instead, they pass arguments
(usually call-by-value) through registers. These subprograms can accept only a limited number of arguments
and do not have access to an ALH. By convention, these subprograms have a percent (%) as the last
character of their name. The arguments are passed through consecutive S registers starting with S1. Note
that each multi-word call-by-value argument requires the corresponding number of registers (for example, a
complex value requires two registers). Vectorized versions of these functions are usually available. By
convention, these vectorized subprograms have a percent (%) has the first and last character of their name.
The arguments to vectorized functions are passed through the V registers in a manner analogous to the scalar
functions. In addition, the VL register contains the vector length.
Function Results
Subprograms expect one-word function results (integers, pointers, floating-point numbers, and so forth) to be
in the S1 register; two-word function results (complex or double-precision) to be in S1 and S2; and a
double-precision complex result is returned in S1 through S4.
Languages which support functions that return aggregates (arrays, structures, and so forth) will pass an
"extra" argument to the function containing the address of the aggregate.
Register Conventions
All registers are considered saved, scratch, or reserved, as follows:
• Saved registers must be saved and restored if used by the subprogram.
• Scratch registers may be used by the subprogram without saving and restoring them.
• Reserved registers must not be used by the subprogram except as outlined below.
The A, S, V, VL, and VM registers are scratch registers. The VL register is also an argument register for
vectorized subprograms where it contains the vector length, but in those subprograms it can otherwise be
treated as a scratch register.

4 004– 2165– 002

CALLSEQ ( 3F ) CALLSEQ ( 3F )

Most of the B and T registers are saved registers. Subprogram linkage information is passed through B
registers (B00 through B02) which are also saved registers. The stack pointers (B66 through B67) are
reserved registers and are altered only during subprogram entry/exit.

Register Status Purpose

B00 saved Return address (parcel form)

B01 saved Pointer to the argument list
B02 saved Pointer to the caller’s frame
B03 through B65 saved Saved B registers
B66 reserved Pointer to the top of the stack
B67 reserved Stack segment limit pointer
B70 through B77 scratch Scratch B registers
T00 through T67 saved Saved T registers
T70 through T77 scratch Scratch T registers

It is important that the saved registers be stored in the proper place in the frame so that traceback, longjump,
and so forth can locate the necessary information.
All of the shared B and T registers are considered scratch registers in non-multitasked programs. In
multitasked programs, SB0 through SB3 and ST0 through ST3 are reserved for use by the multitasking
library and should not be altered; the remaining shared B and T registers are available to the user.
Semaphores SM0 through SM15 are reserved for the multitasking and other run-time libraries and should not
be altered. The remaining semaphores are available to the user.
The matrix in the Bit Matrix Multiply (BMM) functional unit (when present) is considered a scratch register.
BASELVL subprograms
Certain subprograms may utilize a light-weight entry/exit sequence (called BASELVL) to obtain better
performance. However, these subprograms must operate under certain constraints:
• They must be leaf routines; that is, they cannot call other subprograms.
• They must not declare any local (stack) variables.
• They do not have a frame, thus certain traceback/debugging information must be kept in specific registers.
These registers are considered reserved while executing a BASELVL subprogram.

Register Purpose

B00 Return address (parcel form)

B01 -1 (indicates a BASELVL routine)
B77 TNB pointer
A1 Callers argument list pointer

004– 2165– 002 5

CALLSEQ ( 3F ) CALLSEQ ( 3F )

Because BASELVL subprograms do not have a frame, they can execute their entry/exit sequence without
memory references.
Argument List Header
The following table describes the Argument List Header

Field Word Bits Description

ARFLAG 0 0 Nonstandard calling sequence flag (unused)

ARVAL 0 1 0 ≥ call-by-address, 1 ≥ call-by-value
ARCHR 0 2 0 ≥ non-character function; 1 ≥ char. function
ARCHK 0 3 Runtime argument checking flag (1 = on)

TRACEBACK Name Block

The following table describes the Traceback Name Block.
The following table describes the traceback information added before the entry point.

Field Word Bits Description

TNBNN -1 0-63 Last (or only) 8 characters of name.

TNBO 0 0-31 Mandatory zero.
TNBL 0 32-47 Number of following words (excluding this one).
TNBLN 0 48-63 Number of characters in the name. The first character of the name is
contained in the -1 word -ICEIL(TNBLN,8) word of the table.
TNBPA 1 0-63 Parcel address of entry point.
TNBBL 2 0 Base level flag; set if this subprogram makes no calls.
TNBLT 2 1-7 Language type:
0 = cft or cft2
1 = PCC 2.0
2 = Pascal
3 = cft77
4 = CAL
5 = CFT 90
6 = C++
7 = Reserved
8 = SCC (ANSI C)
9 = Ada
10 = Lisp
11 = PCC
TNBCR 2 8-19 Maximum size of parameter list built by this subprogram.
TNBTVS 2 32-63 Size of stack temporary variable store.
TNBSCS 3 0-31 Size of static constant space.

6 004– 2165– 002

CALLSEQ ( 3F ) CALLSEQ ( 3F )

Field Word Bits Description

TNBSVS 3 32-63 Size of static variable space.

TNBNT 4 50-56 Number of T registers.
TNBNB 4 57-63 Number of B registers.
TNBPS 5 0-63 Language-specific information; otherwise unspecified.

SEE ALSO
Cray Assembler for MPP (CAM) Reference Manual, for information about calling sequences on UNICOS/mk
systems.

004– 2165– 002 7

8 004– 2165– 002
INTRO_IO ( 3F ) INTRO_IO ( 3F )

NAME
INTRO_IO – Introduction to Fortran-callable I/O routines

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION
The I/O routines include the following:
• Assign processing routines
• File positioning routines
• Auxiliary NAMELIST routines
• Logical record I/O routines
• Random-access file I/O routines
• Asynchronous queued I/O routines
• Fortran-callable tape processing routines involving beginning- and end-of-volume processing
• Miscellaneous I/O routines
• Fortran I/O units

ASSIGN PROCESSING ROUTINES

Assign processing routines provide a library interface to assign processing. See the assign(1) man page
for details about assign processing.
The following routines are available for assign processing.
• ASNCTL(3F): controls functioning of ASSIGN, ASUNIT, ASNFILE, and ASNRM
• ASSIGN(3F): provides interface to assign processing from Fortran
• ASNUNIT(3F): assigns attributes to units (documented on the ASSIGN(3F) man page)
• ASNFILE(3F): assigns attributes to files (documented on the ASSIGN(3F) man page)
• ASNRM(3F): removes all entries in the assign environment (documented on the ASSIGN(3F) man page)
• ASNQFILE(3F): returns attributes for a file
• ASNQUNIT(3F): returns attributes for a unit (documented on the ASNQFILE(3F) man page)

004– 2165– 002 9

INTRO_IO ( 3F ) INTRO_IO ( 3F )

FILE POSITIONING ROUTINES

These routines are not available on IRIX systems.
File positioning routines change or indicate the position of the current file. These routines set the current
positioning direction to input (read). If the previous processing direction is output (write), end-of-data is
written on a blocked sequential file, and the buffer may be flushed. On a random file, the buffer is flushed.
The following routines are used for positioning:
• GETPOS(3I): returns current position of tape or mass storage file (this routine is documented in the
Fortran Language Reference Manual, Volume 3.)
• SETPOS(3I): returns to the position retained from the GETPOS request (documented on the GETPOS(3I)
man page in the Fortran Language Reference Manual, Volume 3.)
• GETTP(3F): receives position information about an opened tape file
• SETTP(3F): positions a specified tape file at a tape block
• SKIPF(3F): skips files
AUXILIARY NAMELIST ROUTINES
NAMELIST routines let you control input and output defaults. No arguments are returned. For a more
complete description of the NAMELIST feature, see the CF90 Commands and Directives Reference Manual.
The following routines are used for auxiliary NAMELIST routines:
• RNLCOMM(3F): deletes or adds a trailing comment indicator (documented on the rnl(3F) man page)
• RNLDELM(3F): deletes or adds a delimiting character (documented on the rnl(3F) man page)
• RNLFLAG(3F): deletes or adds an echo character (documented on the rnl(3F) man page)
• RNLREP(3F): deletes or adds a replacement character (documented on the rnl(3F) man page)
• RNLSEP(3F): deletes or adds a separator character (documented on the rnl(3F) man page)
• RNLECHO(3F): specifies the output unit for error messages and echo lines
• RNLSKIP(3F): takes action when an undesired NAMELIST group is encountered
• RNLTYPE(3F): determines the action if a type mismatch occurs across the equal sign on an input record
• WNLDELM(3F): defines an ASCII NAMELIST delimiter (documented on the wnl(3F) man page)
• WNLFLAG(3F): indicates the first ASCII character of the first line (documented on the wnl(3F) man
page)
• WNLREP(3F): defines an ASCII NAMELIST separator (documented on the wnl(3F) man page)
• WNLLINE(3F): allows each NAMELIST variable to begin on a new line
• WNLLONG(3F): indicates output line length

10 004– 2165– 002

INTRO_IO ( 3F ) INTRO_IO ( 3F )

LOGICAL RECORD I/O ROUTINES

Not available on IRIX systems.
The logical record I/O routines are divided into read routines, write routines, and bad data error recovery
routines. The following routines are used for logical record I/O:
• ACPTBAD(3F): makes bad data available
• READ(3F): reads words, full record mode
• READP(3F): reads words, partial record mode (documented on the READ(3F) man page)
• READC(3F): reads characters, full record mode
• READCP(3F): reads characters, partial record mode (documented on the READC(3F) man page)
• READIBM(3F): reads two IBM 32-bit real number words from each Cray 64-bit word
• SKIPBAD(3F): skips bad data
• WRITE(3F): writes words, full record mode
• WRITEP(3F): writes words, partial record mode (documented on the WRITE(3F) man page)
• WRITEC(3F): writes characters, full record mode
• WRITECP(3F): writes characters, partial record mode (documented on the WRITEC(3F) man page)
• WRITIBM(3F): writes two IBM 32-bit real number words from each Cray 64-bit number word
READIBM(3F), and WRITIBM(3F) are not supported on UNICOS/mk systems.
Read Routines
Read routines transfer partial or full records of data from the external device to the user data area.
Depending on the read request issued, the data is placed in the user data area either 1 character per word or
in full words. In partial mode, the file maintains its position after the read is executed. In record mode, the
file position is maintained after the end-of-record (EOR) that terminates the current record. Operation of
these routines depends on the -F and -s options on the assign(1) command.
Write Routines
Write routines transfer partial or full records of data from the user data area to the external device.
Depending on the write operation requested, data is either taken from the user data area 1 character per word
and packed 8 characters per word or is transferred in full words. In partial mode, no end-of-record (EOR) is
inserted in the external device in the word following the data that terminates the record. Operation of these
routines depends on the -F and -s options on the assign(1) command.

004– 2165– 002 11

INTRO_IO ( 3F ) INTRO_IO ( 3F )

Bad Data Error Recovery Routines

Bad data error recovery routines enable a user program to continue processing a file when bad data is
encountered. Bad data refers to an unrecovered error encountered while the file was being read. Skipping
the data forces the file to a position past the bad data, so that no data is transferred to the user-specified
buffer. Accepting the data causes the bad data to be transferred to a user-specified buffer. The file is then
positioned immediately following the bad data.
When an unrecovered data error is encountered, continue processing by calling either the SKIPBAD or the
ACPTBAD routine.
These routines do not work with foreign data conversion.

RANDOM-ACCESS FILE I/O ROUTINES

These routines are not available on IRIX systems.
Sequentially accessed files are used for applications that read input only once during a process and write
output only once during a process. However, when large numbers of intermediate results are used randomly
as input at various stages of programs, a random-access file capability is more efficient than sequential
access. A random-access file consists of records that are accessed and changed. Random access of data
eliminates the slow processing and inconvenience of sequential access when the order of reading and writing
records differs in various applications.
Random-access file I/O routines let you specify how records of a file are to be changed, without the usual
limitations of sequential access. Choose specific routines based on performance requirements and the type of
access needed.
Random-access files can be created and accessed by the record-addressable, random-access file routines
(READMS/WRITMS and READDR/WRITDR) or the word-addressable, random-access file routines
(GETWA/PUTWA).
Note: Files created by this method are distinct from Fortran direct-access I/O files. Also, random-access file
I/O routines used in a program with segmented programs should reside in the root segment. However, if all
I/O is done within one segment, the routines can reside in that segment.
Record-addressable, Random-access File I/O Routines
These routines are not available on IRIX systems.
Record-addressable, random-access file I/O routines let you generate files containing variable-length,
individually addressable records. These records can be read and rewritten at your discretion. The library
routines update indexes and pointers. The random-access file information is stored in two places: in an
array in user memory and at the end of the random-access file.
When a random-access file is opened, the OPEN routine initializes an array in user memory to contain the
master index to the records of the file. This master index contains the pointers to and, optionally, the names
of the records within the file. Although you provide this storage area, it must be modified only by the
random-access file I/O routines.

12 004– 2165– 002

INTRO_IO ( 3F ) INTRO_IO ( 3F )

When a random-access file is closed and optionally saved, the storage area containing the master index is
rewritten at the end of the random-access file, thus recording changes to the contents of the file.
The following Fortran-callable routines can change or access a record-addressable, random-access file:
OPENMS, WRITMS, READMS, CLOSMS, FINDMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, OPENDR,
WRITDR, READDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, SYNCDR, and STINDX.
The READDR/WRITDR random-access I/O routines are direct-to-disk versions of READMS/WRITMS. All
input or output goes directly between the user data area and the mass storage file without passing through a
system-maintained buffer. Because mass storage can be addressed only in 512-word blocks, all record
lengths are rounded up to the next multiple of 512 words.
You can intermix READMS/WRITMS and READDR/WRITDR files in the same program, but you must not
use the same file in both packages simultaneously.
OPENMS/OPENDR opens a file and specifies the file as a random-access file that can be accessed or changed
by the record-addressable, random-access file I/O routines. If the file does not exist, the master index
contains zeros; if the file does exist, the master index is read from the file. The master index contains the
current index to the file. The current index is updated when the file is closed using CLOSMS/CLOSDR.
A single program can use up to 40 active READMS/WRITMS files and 20 READDR/WRITDR files.
The following routines are used for record-addressable, random-access I/O:
• ASYNCMS(3F), ASYNCDR(3F): sets the I/O mode to be asynchronous
• CHECKMS(3F), CHECKDR(3F): checks the status of an asynchronous I/O operation
• CLOSMS(3F), CLOSDR(3F): closes a random-access file and writes the master index
• FINDMS(3F): reads records into data buffers used by random-access file routines
• OPENMS(3F), OPENDR(3F): opens a local file as a random-access file
• READMS(3F), READDR(3F): reads a record from a random-access file to memory
• STINDX(3F), STINDR(3F): allows an index to be used as the current index by creating a subindex
• SYNCMS(3F), SYNCDR(3F): sets the I/O mode to be synchronous
• WAITMS(3F), WAITDR(3F): waits for completion of an asynchronous I/O operation
• WRITMS(3F), WRITDR(3F): writes data from user memory to a random-access file and updates the index
Word-addressable, Random-access File I/O Routines
These routines are not available on IRIX systems.

004– 2165– 002 13

INTRO_IO ( 3F ) INTRO_IO ( 3F )

A word-addressable, random-access file consists of an adjustable number of contiguous words. You can
access any word or contiguous sequence of words from a word-addressable, random-access file by using the
associated routines. These files and their I/O routines are similar to the record-addressable, random-access
files and their routines, except that an index is not meaningful. The Fortran-callable, word-addressable
random-access I/O routines are WOPEN, WCLOSE, PUTWA, APUTWA, GETWA, and SEEK. WOPEN opens a
file and specifies it as a word-addressable, random-access file that can be accessed or changed with the
word-addressable routines. The WOPEN call is optional. If a call to GETWA or PUTWA is executed first, the
file is opened for you with the default number of blocks (16), and istats is turned on.
The following routines are used for word-addressable, random-access file I/O:
• GETWA(3F): synchronously reads words from the file into user memory
• SEEK(3F): asynchronously reads data into file buffers (documented on the GETWA(3F) man page)
• PUTWA(3F): synchronously writes words from memory to the file
• APUTWA(3F): asynchronously writes words from memory to the file (documented on the PUTWA(3F)
man page)
• WCLOSE(3F): finalizes additions and changes and closes the file
• WOPEN(3F): opens a file and specifies it as a word-addressable, random-access file
ASYNCHRONOUS QUEUED I/O ROUTINES
These routines are not available on IRIX systems.
Asynchronous queued I/O routines initiate a transfer of data and allow the subsequent execution sequence to
proceed concurrently with the actual transfer.
The following routines are used for asynchronous queued I/O:
• AQCLOSE(3F): closes an asynchronous queued I/O file
• AQOPEN(3F): opens a file for asynchronous queued I/O
• AQOPENM(3F): opens a file for asynchronous queued I/O using specified status flag (documented on the
AQOPEN(3F) man page)
• AQREAD(3F): queues a simple asynchronous I/O read request
• AQREADC(3F): queues a compound asynchronous I/O read request (documented on the AQREAD(3F)
man page)
• AQRECALL(3F): waits for completion of a particular set of asynchronous queued I/O requests
• AQSTAT(3F): checks the status of asynchronous queued I/O requests
• AQWAIT(3F): waits for completion of all asynchronous queued I/O requests
• AQWRITE(3F): queues a simple asynchronous I/O write request
• AQWRITEC(3F): queues a compound asynchronous I/O write request (documented on the AQWRITE(3F)
man page)

14 004– 2165– 002

INTRO_IO ( 3F ) INTRO_IO ( 3F )

FORTRAN-CALLABLE TAPE PROCESSING ROUTINES

See individual man pages for implementation details.
Fortran-callable routines perform special functions on a tape file.
• CHECKTP(3F): checks tape position
• CLOSEV(3F): closes volume and mounts next volume in Volume Identifier list
• ENDSP(3F): disables special tape processing
• SETSP(3F): enables and disables EOV processing
• STARTSP(3F): enables special tape processing

MISCELLANEOUS I/O ROUTINES

FLUSH(3F) writes to a file any buffered data previously written by Fortran output statements.
GTSTDPTR(3F) maps a standard file descriptor into the corresponding address of the FILE structure (stream
pointer) for subsequent use in the Fortran-callable fread(3C) and fwrite(3C) routines.
The LENGTH(3I) and UNIT(3I) routines allow a Fortran program to issue a wait until a BUFFER IN or
BUFFER OUT operation has completed. This type of wait is crucial if the program must synchronize a data
transfer with further use of the information being transferred.
The NUMBLKS(3F) function returns the current file size of a specified unit or file.

FORTRAN I/O UNITS

The SGI Fortran implementation allows I/O units to be connected to files, and they serve as a means of
referring to that file. This subsection describes the characteristics of those unit identifiers.
A Fortran unit identifier is one of the following:
• An integer variable or expression with a 0 or positive value. Each integer unit identifier (i) is associated
with the file fort.i, which may exist. For example, unit 10 is associated with the file fort.10 in the
current working directory.
• An asterisk, identifying a particular file that is connected for formatted, sequential access (allowed only
on READ and WRITE statements). On READ statements, an asterisk refers to unit 100 (standard input).
On WRITE statements, an asterisk refers to unit 101 (standard output).
• UNICOS and UNICOS/mk systems only: A Hollerith (integer) variable consisting of 1 to 7 left-justified,
zero-filled ASCII characters. Each Hollerith unit identifier is associated with the file of the same name,
which may or may not exist. For example, unit ’red’L is associated with the file red in the current
working directory.
Certain Fortran I/O statements have an implied unit number. The PRINT statement always refers to unit
101 (standard output).

004– 2165– 002 15

INTRO_IO ( 3F ) INTRO_IO ( 3F )

Fortran INQUIRE and CLOSE statements may refer to any valid or invalid unit number. All other Fortran
I/O statements may refer only to valid unit numbers. For the purposes of an executing Fortran program, all
unit numbers in use or available for use by that program are valid (that is, they exist). All unit numbers that
are not available for use are invalid (that is, they do not exist).
A valid unit number is any positive integer. Unit numbers 100 through 102 are reserved. Unit numbers 0,
5, and 6 are normally associated with the standard error, standard input, and standard output files,
respectively, although that association can be overridden. All other valid unit numbers are associated with
the file fort.i, as previously indicated. You can use the INQUIRE statement to check the validity
(existence) of any unit number prior to using it. Example:
LOG ICAL UNITOK , UNITOP
...
INQ UIRE (UNIT = I, EXI ST = UNITOK, OPENED = UNI TOP)
IF (UNITOK .AND. .NO T. UNITOP) THE N
OPE N (UN IT = I, ...)
END IF

Initially, all valid units are closed. A unit is connected to a file as the result of one of three types
of opens:
• An implicit open occurs when the first reference to a unit number is an I/O statement other than OPEN,
CLOSE, INQUIRE, BACKSPACE, ENDFILE, or REWIND. Example:
WRITE (4) I, J, K

If unit number 4 is not open, the WRITE statement will cause it to be connected to the associated file
(fort.4), unless overridden by an assign(1) command referencing unit 4.
• An explicit unnamed open occurs when the first reference to a unit number is an OPEN statement without
a FILE specifier. Example:
OPE N (7, FORM=’ UNFORM ATT ED’)

If unit number 7 is not open, the OPEN statement will cause it to be connected to the associated file
(fort.7), unless overridden by an assign command referencing unit 7.
• An explicit named open occurs when the first reference to a unit number is an OPEN statement with a
FILE specifier. Example:
OPE N (9, FILE=’blue’)

If unit number 9 is not open, the OPEN statement will cause it to be connected to the file blue, unless
overridden by an assign command referencing unit 9 or the file blue.
The BACKSPACE, ENDFILE, and REWIND statements will not do an implicit open. If the unit is not
connected to a file, the requested operation is disregarded.

16 004– 2165– 002

INTRO_IO ( 3F ) INTRO_IO ( 3F )

Unit numbers 100 through 102 are permanently associated with the standard input, standard output, and
standard error files, respectively. They may be referenced on READ and WRITE statements. A CLOSE
statement on these unit numbers has no effect. An INQUIRE statement on these unit numbers will indicate
they are nonexistent (invalid). These unit numbers exist to allow guaranteed access to the standard input,
standard output, and standard error files, without regard to any unit actions taken by an executing program.
Thus, a READ or WRITE I/O statement with an asterisk unit identifier (or a PRINT statement) will always
work. Nonstandard I/O operations on these units (for example, BUFFER IN, BUFFER OUT, READMS,
WRITEMS, and so on) are not supported.
Fortran application or library subroutines that want to access the standard error file, standard input file, or
standard output file can use unit numbers 100 through 102, even if the user program closes or reuses unit
numbers 0, 5, and 6.
Special Files
For all unit numbers associated with the standard input, standard output, and standard error files, the nature
of that association is sequential and formatted. That is, unformatted and/or direct-access statements are not
allowed on those files. Furthermore, the standard input file is read-only. ENDFILE, PRINT, and WRITE
statements are not allowed, and the standard error and standard output files are write-only (READ statements
are not allowed).
REWIND and BACKSPACE statements are permitted on terminal files, but with no effect.
ENDFILE is permitted on terminal files, unless they are read-only (standard input); it writes a logical endfile
record.
For all unit numbers associated with pipes, the REWIND statement is invalid. If the file logically has to be
repositioned, the BACKSPACE statement is invalid. A situation in which the file may not have to be
positioned is a BACKSPACE over an endfile record for a file that has only a logical representation of an
endfile record (for example, text files).
Inquire-by-Unit Processing
The INQUIRE statement can be used to retrieve the name of a file connected to a specified unit, if the file
has a name. The Fortran standard allows for unnamed files.
The standard input, standard output, and standard error files are unnamed, and an INQUIRE on a unit
connected to any of these files indicates that it is unnamed (the NAMED parameter is set to .FALSE.).
An INQUIRE on any unit connected using an explicit named open will indicate that the file is named and
will return as the name, the name that was given on the FILE specifier on the OPEN statement.
An INQUIRE on any unit connected using an explicit unnamed open or an implicit open, may or may not
indicate that the file is named. A name will be returned only if the Fortran run-time library can ensure that a
subsequent open, with the FILE specified as the name, will connect to the same file. For scratch files (files
opened with STATUS=’SCRATCH’), a name is returned so the same assign(1) options associated with
the file name are used.

004– 2165– 002 17

INTRO_IO ( 3F ) INTRO_IO ( 3F )

CAUTIONS
The property of unit numbers 100 through 102, whereby they appear nonexistent or invalid on an INQUIRE
or OPEN and yet I/O is permitted, is an extension to the Fortran standard.
It is possible that the special files (standard input, standard output, and standard error) can have two different
units connected to them simultaneously (units 0/102, 5/100, and 6/101). This is an SGI extension to the
Fortran standard.

SEE ALSO
assign(1)
For more information about I/O for Fortran programmers, see the Application Programmer’s I/O Guide.
This guide describes the type of I/O available and provides insight into the efficiencies and inefficiencies of
each. It demonstrates how to speed up various forms of I/O and describes tools that extract statistics from
the execution of a Fortran program.

18 004– 2165– 002

ACPTBAD ( 3F ) ACPTBAD ( 3F )

NAME
ACPTBAD – Makes bad data available

SYNOPSIS
CALL ACPTBAD(unit, uda, wrdcnt, termcnd, ubcnt [,acptcnt])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
ACPTBAD makes bad data available to you by transferring it to the user-specified buffer.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit Unit number.
uda User data area to receive bad data.
wrdcnt On exit, number of words transferred.
termcnd On exit, address of termination condition:
=0 Positioned at end-of-block
=1 Positioned at end-of-file
=2 Positioned at end-of-data
<0 Not positioned at end-of-block
ubcnt On exit, unused bit count. Defined only if termcnd is 0, and wrdcnt is nonzero.
acptcnt Optional integer parameter. On input, it specifies the maximum number of words of bad data
that you want to accept. If the number of words of bad data in the block exceeds this value, the
excess is discarded.

004– 2165– 002 19

ACPTBAD ( 3F ) ACPTBAD ( 3F )

EXAMPLES
Example 1 demonstrates the use of ACPTBAD when used with the READ library routine.
PROGRA M EXA MPL E1
IMPLIC IT INT EGER(A -Z)
PARAME TER(NB YTES=40000,N DIM =NBYTES/8 ,DN =99)
DIM ENSION BUF FER(1: NDIM)
DIMENS ION UDA (1:2*N DIM)

2000 CONTIN UE
NWORDS = NDI M
CAL L REA D(DN,B UFFER, NWORDS ,STATU S)
IF((ST ATUS.E Q.2) .OR. (ST ATUS.E Q.3 )) THEN ! EOF or EOD
STO P ’CO MPLETE ’
ELS E IF (STATU S .EQ. 4) THE N ! Parity err or
NWORDS = 2*NDIM
CALL ACP TBAD(D N, UDA , WC, TER MCND, UBC NT, NWO RDS)
IF (TERMC ND .LT. 0) THEN
PRINT *,’ERROR WHE N ACC EPTING BAD DAT A = ’,TERM CND
STOP ’ERROR ’
END IF
NWO RDS = WC
ENDIF
C ...
C Proces s dat a
C ...
GOT O 200 0 ! Contin ue rea ding
END
Example 2 shows how ACPTBAD works with the Fortran READ statement.

20 004– 2165– 002

ACPTBAD ( 3F ) ACPTBAD ( 3F )

PRO GRA M EXAMPL E1

IMP LIC IT INT EGE R(A -Z)
PAR AME TER(NB YTE S=4 000 0,N DIM =NBYTE S/8 ,DN =99 )
DIM ENS ION BUF FER (1: NDI M)
DIM ENS ION UDA (1: 2*N DIM )
PAR AME TER(BA DDA TA= 135 6)

200 0 CONTINUE
REA D(DN,E RR= 3000,IOST AT= IST AT, END=50 00)BUF FER
C ...
C Proces s dat a
C ...
GOTO 200 0 ! Contin ue reading
3000 CONTIN UE
IF (ISTAT .EQ. BAD DAT A) THE N ! Par ity err or
NWORDS = 2*N DIM
CALL ACPTBA D(D N, UDA, WC, TER MCND, UBCNT, NWO RDS)
IF (TERMC ND .LT . 0) THE N
PRI NT *,’ERR OR WHE N ACC EPTING BAD DAT A = ’,TERMCND
STO P ’ER ROR’
ENDIF
ELS E
PRI NT *,’ ERR OR ’,I STA T,’ FRO M REA D’
STO P ’ER ROR’
END IF
C ...
C Pro ces s bad dat a
C ...
GOT O 200 0
500 0 CON TIN UE
STO P ’CO MPLETE ’
END

SEE ALSO
SKIPBAD(3F)

004– 2165– 002 21

AQCLOSE ( 3F ) AQCLOSE ( 3F )

NAME
AQCLOSE – Closes an asynchronous queued I/O file

SYNOPSIS
CALL AQCLOSE(aqp, status [,reply])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQCLOSE closes a file opened by using AQOPEN(3F). AQCLOSE starts all queued AQIO requests, waits for
their completion, and then closes the file. If any queued or busy requests have pending error conditions, an
error status is returned, and reply (if present) is set to the request ID of the failed request.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer variable or array element. The name of the array in the user’s program that contains the
asynchronous queued I/O file handle. This must be the same variable specified in the AQOPEN
request.
status Integer variable. Status code status returns any errors or status information to the user. On
output from AQCLOSE, status has one of the following values:
=0 No error detected.
<0 Error detected. The absolute value of status indicates the cause of the error. See
intro(2) and the Fortran library error messages. The conditions that may cause
AQCLOSE to return an error status include the close(2) of the file failed; the aqp
argument was invalid; a previously asynchronous I/O request to this file failed, and the
resulting error status had not previously been returned to the program.
reply Optional integer variable. If present, and if an error is due to a failed I/O request, it returns the
request ID of the most recent failed request.

SEE ALSO
AQOPEN(3F), AQREAD(3F), AQREADC (see AQREAD(3F)), AQRECALL(3F), AQSTAT(3F), AQWAIT(3F),
AQWRITE(3F), AQWRITEC (see AQWRITE(3F))
Application Programmer’s I/O Guide

22 004– 2165– 002

AQOPEN ( 3F ) AQOPEN ( 3F )

NAME
AQOPEN, AQOPENM – Opens a file for asynchronous queued I/O

SYNOPSIS
CALL AQOPEN(aqp, aqpsize, dn, status)
CALL AQOPENM(aqp, aqpsize, name, oflag, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQOPEN opens a file to be used in subsequent AQIO requests, such as AQREAD(3F) or AQWRITE(3F).
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
aqp Integer variable or array element that will be assigned the asynchronous queued I/O file handle.
aqpsize Integer variable, expression, or constant. Maximum number of queued I/O requests.
dn A Fortran character constant or variable containing the name of the file. An integer variable,
expression, or constant. dn can be a unit number or the name of the file as an L-type Hollerith
constant.
name A Fortran character constant or variable containing the name of the file.
oflag An integer input variable. oflag contains the status flags that AQOPENM passes to the open(2)
system call when opening the specified file. The value for oflag may be obtained from
IPXFCONST. For more information about the possible values, see the open(2) man page.
AQOPENM does not verify the validity of the oflag specified. For the default file type, the status
flag that AQOPEN uses includes the O_RAW bit; if you use AQOPENM, you must explicitly
specify this if it is desired.
Some assign(1) options may cause the oflag to be modified. These are: -l, -w, -p, -q, and
-n:st.

004– 2165– 002 23

AQOPEN ( 3F ) AQOPEN ( 3F )

status Integer variable. Status code status returns any errors or status information to the user. On
output from AQOPEN, status has one of the following values:
=0 No errors detected.
<0 Error detected. If the absolute value of status is ≥ 1000, it is a library error, and you can
type explain lib-x to view an explanation. If the absolute value of status is < 1000,
it is probably a system error; type explain sys-x to view an explanation.
Asynchronous queued I/O provides a method of random access to or from mass storage into buffers in user
memory.

NOTES
A file opened using AQOPEN must be closed by AQCLOSE(3F). Failure to close the file in this way will
cause unpredictable behavior.
It is not valid to mix calls to AQIO routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
AQCLOSE(3F), AQREAD(3F), AQRECALL(3F), AQSTAT(3F), AQWAIT(3F), AQWRITE(3F)
Application Programmer’s I/O Guide

24 004– 2165– 002

AQREAD ( 3F ) AQREAD ( 3F )

NAME
AQREAD, AQREADC – Queues a simple or compound asynchronous I/O read request

SYNOPSIS
CALL AQREAD(aqp, cpuadd, blknum, blocks, reqid, queue, status)
CALL AQREADC(aqp, cpuadd, mstride, blknum, blocks, dstride, incs, reqid, queue, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQREAD and AQREADC transfer data between the data buffer and the device on which the file resides.
Requests can be simple (AQREAD) or compound (AQREADC). A simple request is one in which data from
consecutive sectors on the disk is read into one buffer. A compound request is one in which several simple
requests are separated by a constant number of sectors on disk, a constant number of memory words for
buffers, or both.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer array. The name of the array in the user’s program that contains the asynchronous
queued I/O file handle. Must be the same array as specified in the AQOPEN(3F) request.
cpuadd Type determined by the user; this may not be a Fortran character variable. Starting memory
address; the location where the first word of data is placed.
blknum Integer variable, expression, or constant. Starting block number. The block number of the first
block to be read on this request. Block numbering starts at 0.
blocks Integer variable, expression, or constant. The number of 4096-byte blocks to be read.
reqid Integer variable, expression, or constant. A user-supplied value for identifying a particular
request.
queue Integer variable, expression, or constant. Queue flag. If 0, I/O is initiated provided that I/O on
the file is not already active. If the queue flag is set to nonzero, the request is added to the
queue but no attempt is made to start I/O.
status Integer variable. Status code status returns any errors to the user. On output from these
routines, status has one of the following values:
=0 No error detected.

004– 2165– 002 25

AQREAD ( 3F ) AQREAD ( 3F )

<0 Error detected. The absolute value of status indicates the cause of the error. See
intro(2) for more information. AQREAD and AQREADC may return an error status if a
previous asynchronous I/O request to this file failed, and the resulting error status had not
been returned to the program.
dstride Integer variable, expression, or constant. Disk stride; the number of disk blocks to skip between
the base addresses of consecutive transfers. The stride value may be positive (to skip forward),
negative (to skip backward), or 0. This parameter is valid only for compound requests.
incs Integer variable, expression, or constant. The number of simple requests minus 1 that comprise
a compound request. Zero (0) implies a simple request. This parameter is valid only for
compound requests.
mstride Integer variable, expression, or constant. Data buffer stride; the number of memory words to
skip between the base addresses of consecutive transfers. The stride value may be positive (to
skip forward), negative (to skip backward), or 0 (implying a contiguous data flow to memory).
This parameter is valid only for compound read requests.

SEE ALSO
AQCLOSE(3F), AQOPEN(3F), AQRECALL(3F), AQSTAT(3F), AQWAIT(3F), AQWRITE(3F)
intro(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

26 004– 2165– 002

AQRECALL ( 3F ) AQRECALL ( 3F )

NAME
AQRECALL – Waits for completion of asynchronous queued I/O request

SYNOPSIS
CALL AQRECALL(aqp, status, reqid, reply)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQRECALL leaves the program suspended until a particular asynchronous queued I/O request (and all the
asynchronous I/O requests made with the same aqp that preceded it) is complete, or until an error is
encountered.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer array. The name of the array in the user’s program that contains the asynchronous
queued I/O file handle. This must be the same array specified in the AQOPEN(3F) request.
status Integer variable. This status code returns one of the following values on output from
AQRECALL:
0 The requested ID is not found in the list of I/O requests.
+5 I/O has been completed.
<0 A negative value indicates that the I/O request indicated by reply has failed. Control is
returned immediately. The absolute value of the status returned indicates the reason. See
intro(2) for more details.
reqid If nonzero, AQRECALL waits until the I/O identified by this value (and all that preceded it) are
complete, or until an error is encountered.
If zero, AQRECALL waits until all outstanding I/O is complete, or until an error is encountered.
AQRECALL searches the queue of requests until it finds the first match for reqid. If more than
one entry in the request queue has the same reqid, results are unpredictable. To effectively use
AQRECALL, ensure that each entry in the queue has a unique request ID. Entries may remain in
the queue after AQWAIT or AQRECALL.
reply Integer variable. If an error occurred, reply is set to the request ID of the entry that incurred the
error. Control is returned immediately. If more than one outstanding request has a pending
error, AQRECALL must be called repeatedly until the return status is 0 to call all error returns.

004– 2165– 002 27

AQRECALL ( 3F ) AQRECALL ( 3F )

SEE ALSO
AQOPEN(3F), AQREAD(3F), AQSTAT(3F), AQWAIT(3F), AQWRITE(3F)
intro(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

28 004– 2165– 002

AQSTAT ( 3F ) AQSTAT ( 3F )

NAME
AQSTAT – Checks the status of asynchronous queued I/O requests

SYNOPSIS
CALL AQSTAT(aqp, reply, reqid, status [,wait])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQSTAT returns the status of a particular queued request. If the optional wait argument is specified, return
is delayed until that request is complete.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer array. The name of the array in the user’s program that contains the asynchronous
queued I/O file handle. This must be the same array specified in the AQOPEN(3F) request.
reply Integer variable. Specify a dummy integer in this position because the routine expects four
arguments in a particular order.
reqid Integer variable, expression, or constant. Specifies the request ID for which status information
will be returned.
status Integer variable. This status code returns one of the following values on output from AQSTAT:
0 The requested ID is not found in the list of I/O requests. This can occur if the requested
ID does not correspond to an actual request, or if the requested ID has completed and the
entry has been overwritten.
+2 The requested ID is in the library queue, but the system request to start this I/O has not
been made.
+4 The asynchronous request is queued for I/O in the operating system.
+5 I/O has been completed.
<0 A negative value indicates that this I/O request failed. The absolute value of the status
returned indicates the reason. See intro(2) for more details.
wait Optional argument. If present and nonzero, return is delayed until the specified request is
complete.

004– 2165– 002 29

AQSTAT ( 3F ) AQSTAT ( 3F )

SEE ALSO
AQCLOSE(3F), AQOPEN(3F), AQREAD(3F), AQRECALL(3F), AQWAIT(3F), AQWRITE(3F)
intro(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

30 004– 2165– 002

AQWAIT ( 3F ) AQWAIT ( 3F )

NAME
AQWAIT – Waits for completion of asynchronous queued I/O requests

SYNOPSIS
CALL AQWAIT(aqp, status [,reply])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQWAIT delays program execution until all pending requests have completed or until an error is
encountered. If necessary, requests that are queued but not started are started.
If any of the pending requests encounters an error, control is returned immediately, and the variable reply, if
specified, is set to the request ID of the request that encountered the error.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer array. The name of the array in the user’s program that contains the asynchronous
queued I/O parameter block. This must be the same array specified in the AQOPEN(3F) request.
status Integer variable that returns any errors or status information to the user. On output from
AQWAIT, status has one of the following values:
2 No I/O is active or queued.
=0 No errors detected.
<0 Error detected. The absolute value of the status indicates the cause of the error. See
intro(2) for more information.
reply Optional argument. Request ID of request in error.

SEE ALSO
AQCLOSE(3F), AQOPEN(3F), AQREAD(3F), AQRECALL(3F), AQSTAT(3F), AQWRITE(3F)
intro(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

004– 2165– 002 31

AQWRITE ( 3F ) AQWRITE ( 3F )

NAME
AQWRITE, AQWRITEC – Queues a simple or compound asynchronous I/O write request

SYNOPSIS
CALL AQWRITE(aqp, cpuadd, blknum, blocks, reqid, queue, status)
CALL AQWRITEC(aqp, cpuadd, mstride, blknum, blocks, dstride, incs, reqid, queue, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
AQWRITE and AQWRITEC transfer data between the device on which the file resides and the data buffer.
Requests can be simple (AQWRITE) or compound (AQWRITEC). A simple request is one in which data
from one buffer is written to consecutive sectors on disk. A compound request is one in which several
simple requests are separated by a constant number of sectors on disk, a constant number of memory words
for buffers, or both.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
aqp Integer array. The name of the array in the user’s program that contains the asynchronous
queued I/O file handle. Must be the same array specified in the AQOPEN request.
cpuadd Type determined by user; this may not be a Fortran character variable. Starting memory
address; the location of the first word in the user’s program to be written.
blknum Integer variable, expression, or constant. The block number of the first block to be written on
this request. Block numbering starts at 0.
blocks Integer variable, expression, or constant. The number of 4096-byte blocks to be written.
reqid Integer variable, expression, or constant. A user-supplied value for identifying a particular
request.
queue Integer variable, expression, or constant. Queue flag. If 0, I/O is initiated when I/O on the file
is not already active. If the queue flag is set to nonzero, the request is added to the queue but
no attempt is made to start I/O.
status Integer variable. Status code status returns any errors to the user. On output from these
routines, status has one of the following values:
=0 No error detected.

32 004– 2165– 002

AQWRITE ( 3F ) AQWRITE ( 3F )

<0 Error detected. The absolute value of status indicates the cause of the error. See
intro(2) for more information. AQREAD and AQREADC may return an error status if a
previous asynchronous I/O request to this file failed, and the resulting error status had not
been returned to the program.
mstride Integer variable, expression, or constant. Data buffer stride; the number of memory words to
skip between the base addresses of consecutive transfers. The stride value may be positive (to
skip forward), negative (to skip backward), or 0 (implying contiguous data flow from memory).
This parameter is valid only for compound write requests.
dstride Integer variable, expression, or constant. Disk stride; the number of disk blocks to skip between
the base addresses of consecutive transfers. The stride value may be positive (to skip forward),
negative (to skip backward), or 0. This parameter is valid only for compound requests.
incs Integer variable, expression, or constant. The number of simple requests minus 1 that compose a
compound request. Zero (0) implies a simple request. This parameter is valid only for
compound requests.

SEE ALSO
AQCLOSE(3F), AQOPEN(3F), AQREAD(3F), AQRECALL(3F), AQSTAT(3F), AQWAIT(3F)
intro(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

004– 2165– 002 33

ASNCTL ( 3F ) ASNCTL ( 3F )

NAME
ASNCTL – Controls function of ASSIGN, ASNFILE, ASNUNIT, and ASNRM routines

SYNOPSIS
CALL ASNCTL(option, value, ier)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION

This routine is supported on IRIX systems for programs compiled with the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
The ’LOCAL’ and ’NEWLOCAL’ modes are useful for any utility written in Fortran when you want to use
ASSIGN(3F) but do not want to access the assign environment file set up by the user.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine.
option A Fortran character variable containing either of the following values:
’LOCAL’ Causes ASNCTL to establish a local assign environment. The old assign
environment is copied into the newly created local assign environment.
Subsequent calls to ASSIGN, ASNUNIT, ASNFILE, and ASNRM (see
ASSIGN(3F)) affect only the newly created local assign environment. Any
future Fortran OPEN requests will also read from the local assign environment
initiated by this call to ASNCTL. The user must set value to 1 when calling
ASNCTL with option=’LOCAL’.
’NEWLOCAL’ Causes ASNCTL to establish an empty local assign environment. Subsequent
calls to ASSIGN, ASNUNIT, ASNFILE, and ASNRM (see ASSIGN(3F)) affect
the newly created local assign environment. Any future Fortran OPEN
requests will also read from the local assign environment initiated by this call
to ASNCTL. The user must set value to 1 when calling ASNCTL with
option=’NEWLOCAL’.
’RESTORE’ Restores the assign environment that was active before the preceding
’LOCAL’ or ’NEWLOCAL’ request. Sets value to 1 when calling ASNCTL with
option=’RESTORE’.
value Integer variable, constant, or array element containing the option value.

34 004– 2165– 002

ASNCTL ( 3F ) ASNCTL ( 3F )

ier Integer variable or array element that is assigned the error status on return. Zero (0) is usually
returned, indicating no errors were encountered; otherwise, a positive error status is returned.

EXAMPLES
The writer of the following Fortran program wants to disregard any assign information provided by the
user. However, the program requires sequential unformatted I/O on unit 11 with an unblocked file structure.
This is accomplished by the following:
CAL L ASN CTL (’N EWL OCA L’, 1,i er) ! sta rt loc al ass ign env iro nme nt
CAL L ASN UNI T(1 1,’ -s unb loc ked ’,i er) ! ass ign the "un blo cke d" fil e str uct ure
OPE N(1 1,f orm =’u nfo rma tte d’) ! ope n uni t 11

SEE ALSO
ASSIGN(3F)

004– 2165– 002 35

ASNQFILE ( 3F ) ASNQFILE ( 3F )

NAME
ASNQFILE, ASNQUNIT – Returns the assign options currently in effect for a file name or unit number

SYNOPSIS
CALL ASNQFILE(file, attr, istat)
CALL ASNQUNIT(iun, attr, istat)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION

This routine is supported on IRIX systems for programs compiled with the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
ASNQFILE queries the assign environment for any assign options currently in effect for a file name.
ASNQUNIT queries the assign environment for any assign options currently in effect for a unit number.
The assign options may have been established earlier by the assign(1) command or the ASSIGN,
ASNUNIT, or ASNFILE (see ASSIGN(3F)) library routines.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine.
file A character variable or array element containing the file name.
attr A character variable or array element that receives the option’s value in the form of a character
string. If the options exceed the length of attr, istat is set to a positive error code. If no
assign options are found for the specified unit or file, ’ ’ is returned in attr.
istat An integer variable or array element that receives one of the following return statuses:
0 Options were found for the specified file or iun
-1 No options were found for the specified file or iun.
>0 An error condition was encountered. Use the explain(1) command to obtain
information about a particular error code.
iun An integer variable or array element containing the unit number.

36 004– 2165– 002

ASNQFILE ( 3F ) ASNQFILE ( 3F )

SEE ALSO
ASNCTL(3F), ASSIGN(3F)
assign(1) in the Application Programmer’s I/O Guide
explain(1) in the UNICOS User Commands Reference Manual

004– 2165– 002 37

ASSIGN ( 3F ) ASSIGN ( 3F )

NAME
ASSIGN, ASNUNIT, ASNFILE, ASNRM – Provides library interface to assign processing

SYNOPSIS
All systems:
CALL ASNUNIT(iunit, astring, ier)
CALL ASNFILE(fname, astring, ier)
CALL ASNRM(ier)
CALL ASSIGN(cmd ,ier)
UNICOS and UNICOS/mk systems only:
CALL ASSIGN(cmd)

IMPLEMENTATION
UNICOS, UNICOS/mk and IRIX systems

DESCRIPTION

This routine is supported on IRIX systems for programs compiled with the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
ASSIGN provides an interface to assign processing from Fortran.
ASNUNIT and ASNFILE assign attributes to units and files, respectively.
ASNRM removes all entries currently in the assign environment.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
These routines have the following arguments:
cmd A Fortran character variable containing a complete assign(1) command in the format also
acceptable to ISHELL(3F). The -V option cannot be processed by the ASSIGN routine.
ier An integer variable that is assigned the exit status on return. A 0 indicates normal return; >0
indicates a specific error status
iunit An integer variable or constant containing the unit number to which attributes are assigned.
astring A Fortran character variable containing any attribute options and option values that could be
passed to assign(1). Control options -I, -O, and -R can also be passed.
fname A character variable or constant containing the file name to which attributes are assigned.

38 004– 2165– 002

ASSIGN ( 3F ) ASSIGN ( 3F )

NOTES
Users are encouraged to use the ASSIGN library routines rather than ISHELL(’assign’), because
ISHELL(3F) causes vfork(2), an exec(2) of sh(1), another fork(2), and another exec(2) of
assign(1).
EXAMPLES
Example 1: The following is equivalent to assign -s unblocked f:file
CALL ASSIGN (’a ssign -s unb loc ked f:file’ ,ier)

Example 2: The following has the same effect as assign -I -n 2 u:99

INT EGE R IUN
IUN = 99
CAL L ASN UNIT(I UN, ’-I -n 2’, IER)

Example 3: The following is equivalent to executing assign -s tape u:1

CAL L ASN UNI T(1,’ -s tap e’,IER )

SEE ALSO
ASNCTL(3F), ASNQFILE(3F), ASNQUNIT(3F), ISHELL(3F)
assign(1)

004– 2165– 002 39

ASYNCMS ( 3F ) ASYNCMS ( 3F )

NAME
ASYNCMS, ASYNCDR – Sets I/O mode for random-access routines to asynchronous

SYNOPSIS
CALL ASYNCMS(dn [,ierr])
CALL ASYNCDR(dn [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
As the ASYNCMS or ASYNCDR routine sets the I/O mode for the random-access routines to be asynchronous,
I/O operations can be initiated, and subsequent execution can proceed simultaneously with the actual data
transfer. If using READMS(3F), precede asynchronous reads with calls to FINDMS(3F).
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
ierr Error control and code. Specify an integer variable. If you specified ierr on the call to
ASYNCMS/ASYNCDR, ierr returns any error codes to you. If ierr>0, no error messages are put
into the stderr file; otherwise, an error code is returned, and the message is added to the
program’s stderr file. On output from ASYNCMS/ASYNCDR, ierr has one of the following
values:
=0 No errors detected.
≤ 0 Error detected. ierr contains one of the following error codes:
–1 The file name or unit number is not valid.
-15 OPENMS/OPENDR was not called on this file.

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking and if you are multitasking your I/O calls.

40 004– 2165– 002

ASYNCMS ( 3F ) ASYNCMS ( 3F )

It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
CHECKMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), READMS(3F), STINDX(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

004– 2165– 002 41

CHECKMS ( 3F ) CHECKMS ( 3F )

NAME
CHECKMS, CHECKDR – Checks status of asynchronous random-access I/O operation

SYNOPSIS
CALL CHECKMS(dn, istat [,ierr])
CALL CHECKDR(dn, istat [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CHECKMS and CHECKDR routines check the status of an asynchronous random-access I/O operation.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn Integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
istat File I/O activity flag. Specify an integer variable.
= 0 No I/O activity on the specified file
= 1 I/O activity on the specified file
ierr Error control and code. Specify an integer variable. If you specify ierr on the call to CHECKMS
or CHECKDR, ierr returns any error codes to you. If ierr>0, no error messages are put into the
stderr file. Otherwise, an error code is returned, and the message is added to the program’s
stderr file. On output from CHECKMS or CHECKDR, ierr contains one of the following error
codes:
=0 No error detected.
<0 Error detected. ierr contains one of the following error codes:
–1 The file name or unit number is not valid.
-15 OPENMS/OPENDR was not called on this file.

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking, and if you are multitasking your I/O calls.

42 004– 2165– 002

CHECKMS ( 3F ) CHECKMS ( 3F )

It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
ASYNCMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), READMS(3F), STINDX(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

004– 2165– 002 43

CHECKTP ( 3F ) CHECKTP ( 3F )

NAME
CHECKTP – Checks tape position

SYNOPSIS
CALL CHECKTP(unit, istat, icbuf)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CHECKTP checks the tape position.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
istat Result of CHECKTP:
-1 No status
0 At EOV
1 Tape off reel
2 Tape mark detected
3 Blank tape detected
icbuf Number of blocks in circular buffer. Always 0 under the UNICOS operating system (included
for COS compatibility).

NOTES
The file must be an opened tape or ER90 file and must use the FFIO tape layer.

SEE ALSO
CLOSEV(3F), ENDSP(3F), SETSP(3F), STARTSP(3F)

44 004– 2165– 002

CLOSEV ( 3F ) CLOSEV ( 3F )

NAME
CLOSEV – Closes volume and mounts next volume in Volume Identifier list

SYNOPSIS
CALL CLOSEV(unit, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CLOSEV closes a volume and mounts the next volume.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
istat Result of CLOSEV:
=0 No error occurred
≠0 Error or warning occurred

NOTES
The file must be an opened tape file.

SEE ALSO
CHECKTP(3F), ENDSP(3F), SETSP(3F), STARTSP(3F)

004– 2165– 002 45

CLOSMS ( 3F ) CLOSMS ( 3F )

NAME
CLOSMS, CLOSDR – Writes master index and closes random-access file

SYNOPSIS
CALL CLOSMS(dn [,ierr])
CALL CLOSDR(dn [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CLOSMS/CLOSDR writes the master index specified in OPENMS/OPENDR from the user program area to the
random-access file and then closes the file.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
ierr Error control and code. Specify an integer variable. If you specify ierr on the call to
CLOSMS/CLOSDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned and the message is added to the program’s
stderr file. On output from CLOSMS/CLOSDR, ierr has one of the following values:
=0 No error detected.
<0 Error detected. ierr contains one of the following error codes:
–1 The file name or unit number is not legal.
-15 OPENMS/OPENDR was not called on this file.
Statistics on the activity of the random-access file are written to the stderr file (see the following table).
CLOSMS/CLOSDR writes a message to stderr on closing the file.

46 004– 2165– 002

CLOSMS ( 3F ) CLOSMS ( 3F )

Message Description

TOTAL ACCESSES = number of accesses

READS = number of reads
WRITES = number of writes
SEQUENTIAL READS = number of sequential reads
SEQUENTIAL WRITES = number of sequential writes
REWRITES IN PLACE = number of rewrites in place
WRITES TO EOI = number of writes to EOI
TOTAL WORDS MOVED = number of words moved
MINIMUM RECORD = minimum record size
MAXIMUM RECORD = maximum record size
TOTAL ACCESS TIME = total access time
AVERAGE ACCESS TIME = average access time

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking, and if you are multitasking your I/O calls.
It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

CAUTIONS
If a program terminates without closing the random-access file with CLOSMS/CLOSDR, file integrity is
questionable.

SEE ALSO
OPENMS(3F)

004– 2165– 002 47

ENDSP ( 3F ) ENDSP ( 3F )

NAME
ENDSP – Disables special tape processing

SYNOPSIS
CALL ENDSP(unit, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine disables special tape processing.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
istat Result of ENDSP:
=0 Special processing was successfully disabled.
≠0 Error occurred when disabling special processing.

NOTES
The following preconditions must exist:
• The file must be an opened tape file.
• EOV processing must be enabled.
• Special processing must be disabled before you can enable it and it must be enabled before you can
disable it.
ENDSP removes an alternate path to or from a tape. Tape blocks that were held aside are written to tape.

SEE ALSO
CHECKTP(3F), CLOSEV(3F), SETSP(3F), STARTSP(3F)

48 004– 2165– 002

FINDMS ( 3F ) FINDMS ( 3F )

NAME
FINDMS – Reads record into data buffers used by random-access routines

SYNOPSIS
CALL FINDMS(dn, n, irec [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
FINDMS asynchronously reads the desired record into the data buffers used by the random-access file
routines for the specified file. The next READMS(3F) or WRITMS(3F) call waits for this read to complete
and transfers data appropriately.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
n The number of words to be read, as in READMS or WRITMS. Type integer variable, expression,
or constant.
irec As in READMS or WRITMS, the record name or number to be read into the data buffers. Specify
an integer variable, expression, or constant.
ierr Error control and code. Specify a type integer variable. If you specify ierr on the call to
FINDMS, ierr returns any error codes to you. If ierr>0, no error messages are put in the
stderr file; otherwise, an error code is returned, and the message is added to the stderr file.
On output from FINDMS, ierr has one of the following values:
=0 No errors or warnings detected.
<0 Error or warning condition detected. ierr contains one of the following error or
warning codes:
-6 The user-supplied named index is not valid.
-8 The index number is greater than the maximum on the file.
-10 The named record was not found in the index array.
-15 OPENMS/OPENDR was not called on this file.
-17 The index entry is less than or equal to 0 in the user’s index array.

004– 2165– 002 49

FINDMS ( 3F ) FINDMS ( 3F )

-18 The user-supplied word count is less than or equal to 0.

-19 The user-supplied index number is less than or equal to 0.
-22 The record does not fit in the buffer. (warning)

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or if microtasking and you are multitasking your I/O calls.
It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), OPENMS(3F), READMS(3F), STINDX(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

50 004– 2165– 002

FLUSH ( 3F ) FLUSH ( 3F )

NAME
FLUSH – Writes data buffered by Fortran output statements to a file

SYNOPSIS
UNICOS and UNICOS/mk systems:
CALL FLUSH(iunit)
CALL FLUSH(iunit,[istat])
IRIX systems:
CALL FLUSH(iunit, istat)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
FLUSH writes to a file any buffered data previously written by Fortran output statements. FLUSH may be
called after reading or writing. The current file position is not changed.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
This routine has the following arguments:
iunit Integer variable, expression, or constant containing a Fortran unit number. If this value is 101, it
flushes the unit which is connected to standard output. If this value is 102, it flushes the unit
which is connected to standard error.
istat Integer variable or array element that receives the return status as follows:
=0 Indicates that all buffered data, if any, was flushed. A file that was immediately read, or a
file with a buffer that has not changed since the last flush, might return a 0 status even
though no new data would be written to the file.
-1 Indicates that the Fortran unit does not support FLUSH, and no data was written to the file.
>0 Indicates that an error condition was encountered. The specific error number is returned.
Use the explain(1) command for a description of the error code.
The istat argument is optional on UNICOS systems; the user program is aborted if FLUSH is called without
istat and an error condition is encountered.

004– 2165– 002 51

FLUSH ( 3F ) FLUSH ( 3F )

NOTES
If FLUSH is called with an unconnected unit, an error condition results (except for units 101 and 102).
Calling FLUSH for a file for which the program does not have write permission returns a 0 status if no data
was written to that file previously with Fortran I/O statements.
A WRITE I/O statement with an asterisk unit identifier (or a PRINT statement) uses unit 101. See "Fortran
I/O Units" in INTRO_IO(3F) on UNICOS and UNICOS/mk systems for more information (INTRO_IO is
not available on IRIX systems).

SEE ALSO
explain(1) in the UNICOS User Commands Reference Manual to see a description of the error code.

52 004– 2165– 002

FSUP ( 3F ) FSUP ( 3F )

NAME
FSUP, ISUP – Suppress values in Fortran edit-directed output

SYNOPSIS
CALL FSUP(fvalue)
CALL ISUP(ivalue)
CALL FSUPC
CALL ISUPC

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
fvalue and ivalue are real and integer arguments of default KIND. When FSUP is called, all REAL values
equal to fvalue are suppressed (are output as blanks) when they are encountered in a Fortran edit-directed
formatted I/O operation. FSUP may be recalled to redefine itself.
FSUPC undoes the call to FSUP, and all types are output as ordinary Fortran I/O.
FSUPC and ISUPC invalidate the function obtained by calling FSUP or ISUP, returning to ordinary Fortran
I/O.
ISUP and ISUPC are the integer equivalents of FSUP and FSUPC.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.

004– 2165– 002 53

GETTP ( 3F ) GETTP ( 3F )

NAME
GETTP – Gets information about an opened tape file

SYNOPSIS
CALL GETTP(unit, len, ipa, synch, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION

GETTP retrieves information about an opened tape file, including its current status.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
len Integer length (in Cray words) of information array ipa. GETTP uses this parameter to
determine the maximum number of information words to return. This parameter also allows for
the addition of more fields in an upward-compatible manner. Currently, 48 words are defined.
ipa Integer information array. On exit, this array contains tape information, as follows:
ipa(1) Current volume identifier (left-justified, zero-filled).
ipa(2)– ipa(7)
Characters 1 through 48 of the path name of the file opened to this tape
(left-justified, zero-filled).
ipa(8) Integer file section number.
ipa(9) Integer file sequence number.
ipa(10) Integer block number relative to tape mark number specified in ipa(23).
ipa(11) Integer number of blocks in the tape layer library buffer. If additional processing
layers have been specified with assign(1) or asgcmd(1), those layers may also
hold buffered data, but they will not be included in this field.
ipa(12) Integer number of blocks in the IOP buffer.
ipa(13) Device ID or unit number in integers.
ipa(14) Device identifier or name (left-justified, zero-filled).
ipa(15) Generic device name (left-justified, zero-filled).

54 004– 2165– 002

GETTP ( 3F ) GETTP ( 3F )

ipa(16) Last device function as an integer.

ipa(17) Last device status as an integer.
ipa(18) Data transfer count in bytes as an integer.
ipa(19) Buffer memory sector count as an integer.
ipa(20) Partial block bytes in buffer memory as an integer.
ipa(21) Outstanding sector count as an integer.
ipa(22) Outstanding block count as an integer.
ipa(23) User tape mark number as an integer, including tape marks embedded in the data.
ipa(24) Direction from tape mark in previous word: 0= after tape mark and 1= before tape
mark.
ipa(25) Today’s year modulus 100 as an integer.
ipa(26) Today’s Julian day as an integer.
ipa(27) File identifier, up to the first 8 characters (left-justified, zero-filled).
ipa(28) Record format name (left-justified, zero-filled).
ipa(29) Tape density as an integer: 1=1600 b/i, 2= 6250 b/i.
ipa(30) Maximum block size as an integer.
ipa(31) Record length as an integer.
ipa(32) File status as an integer: 1= new, 2= old, 3= append.
ipa(33) Label type as an integer: 1= no label, 2= ANSI label, 3= IBM standard label, 4=
bypass label.
ipa(34) Integer file sequence number of first file on volume.
ipa(35) Ring status as an integer: 0= ring out, 1= ring in.
ipa(36) Expiration year modulus 100 as an integer.
ipa(37) Expiration Julian day as an integer.
ipa(38) First volume identifier of file as an integer.
ipa(39) User end-of-volume processing status as an integer: 0= EOV processing off,
1= EOV processing on.
ipa(40) User end-of-volume processing status as an integer: 0= EOV processing is not
currently active, 1= EOV processing is currently active.
ipa(41) User read/write tape mark status as an integer: 0= user read/write tape mark is not
allowed, 1= user read/write tape mark allowed.

004– 2165– 002 55

GETTP ( 3F ) GETTP ( 3F )

ipa(42) Block attribute (left-justified, zero-filled).

’B’L= blocked records
’S’L= spanned records if the record format is ’V’, or standard records if
the record format is ’F’
’R’L= blocked and spanned records if the record format is ’V’
’R’L= blocked and standard records if the record format is ’F’
’ ’L (blank)= none of the above
ipa(43)– ipa(48)
File identifier (left-justified, zero-filled).
synch This parameter is ignored if the last I/O operation was a read. If the last operation was a write,
this parameter is meaningful. In this case, the following values apply:
=0 Do not synchronize dataset.
=1 Synchronize dataset before obtaining position information. It is invalid to specify this
value in the following circumstance: end-of-volume (EOV) processing is enabled, and the
user has reached the EOV but has not started special processing. This parameter has no
effect on data buffered in library layers other than the tape layer.
istat Integer return status. On exit, this parameter contains a value indicating the status of the
information request:
=0 Indicates that the file was successfully queried, and ipa array is defined.
≠0 Indicates that an error was encountered during an attempt to query the tape file, or an
invalid argument was passed to GETTP (for example, len≤0). The ipa array is undefined.

NOTES
The er90 layer is not available on Cray T3E systems. See the assign(1) man page and the Tape
Subsystem User’s Guide, for more information about the er90 FFIO layer.

SEE ALSO
SETTP(3F)

56 004– 2165– 002

GETWA ( 3F ) GETWA ( 3F )

NAME
GETWA, SEEK – Synchronously and asynchronously reads data from the word-addressable, random-access
file

SYNOPSIS
CALL GETWA(dn, result, addr, count [,ierr])
CALL SEEK(dn, addr, count [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
Use the SEEK and GETWA calls together when possible to improve efficiency; SEEK calls are never
functionally required. The SEEK call reads the data asynchronously; the GETWA call waits for I/O to
complete and then transfers the data. The SEEK call moves the last write operation pages from memory to
disk, loading the user-requested word addresses to the front of the I/O buffers. You can load as much data
as fits into the file buffers. Subsequent GETWA and PUTWA calls that reference word addresses in the same
range do not cause any disk I/O.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
result Variable or array of any type. The location in the user program at which the first word is placed.
addr For GETWA, the word location of the file from which the first word is transferred. For SEEK, the
word address of the next read. Specify a type integer variable, expression, or constant.
count For GETWA, the number of words written from the file into user memory. For SEEK, the number
of words of the next read. Specify a type integer variable, expression, or constant.
ierr Error control and code. Specify a type integer variable. If you specify ierr on the call to GETWA
or SEEK, ierr returns any error codes to you. If ierr is not specified, an error aborts the program.
On output from GETWA, ierr has one of the following values:
=0 No errors detected.
<0 Error detected. ierr contains one of the following error codes:
+1 Request for a seek is outside page buffers.
-1 Invalid unit number.

004– 2165– 002 57

GETWA ( 3F ) GETWA ( 3F )

-2 The number of files has exceeded memory or size availability.

-3 User attempt to read past end-of-data (EOD).
-4 User-supplied word address less than or equal to 0.
-5 User-requested word count greater than maximum allowed.
-6 Illegal file name.
-7 User word count less than or equal to 0.

NOTES
Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are
single threaded. Some library routines, however, must be locked at the user level if they are used by more
than one task. GETWA is not internally locked. You must lock each call to GETWA if it is called from more
than one task.
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to the stderr file.
It is not valid to mix calls to word-addressable routines with standard Fortran I/O statements that use the
same unit number.

EXAMPLES
Assume that you want to use a routine that reads word addresses 1,000,000 to 1,051,200. A file is opened
with 101 blocks of buffer space, and the following call is used before calling the routine:
CALL SEE K(filename,10 000 00,512 00, ierr)

Subsequent GETWA or PUTWA calls with word addresses in the range of 1,000,000 to 1,051,200 do not
trigger any disk I/O.

SEE ALSO
PUTWA(3F), WCLOSE(3F), WOPEN(3F)

58 004– 2165– 002

GTSTDPTR ( 3F ) GTSTDPTR ( 3F )

NAME
GTSTDPTR – Returns pointer to standard file

SYNOPSIS
INTEGER fd, stream, GTSTDPTR
stream = GTSTDPTR(fd)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GTSTDPTR maps a standard file descriptor (0, 1, or 2) into the corresponding address of the FILE structure
(stream pointer) for use in the Fortran-callable fread(3C) and fwrite(3C) routines.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
This routine has the following arguments:
fd Integer file descriptor. The following values are available:
0 Return address of standard input (stdin)
1 Return address of standard output (stdout)
2 Return address of standard error (stderr)
stream
Address of the FILE structure (stream pointer). Null (0) if the file descriptor is not valid (that is, if it
is not 0, 1, or 2).

SEE ALSO
fread(3C), fwrite(3C) in the UNICOS System Libraries Reference Manual

004– 2165– 002 59

NUMBLKS ( 3F ) NUMBLKS ( 3F )

NAME
NUMBLKS – Returns the current size of a file in 4096-byte blocks

SYNOPSIS
INTEGER NUMBLKS
val = NUMBLKS(unit)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION

This routine is supported on IRIX systems for programs compiled with the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
NUMBLKS returns the current size of a file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, the
argument must be type integer with default KIND, and the function must be type integer with KIND=8.
The following is a list of arguments for this routine.
val File size in 4096-byte blocks. This returned value reflects only the data actually written to disk
and does not take into account data still in the buffers. A value of 0 is returned if the file is a
pipe or character special device. A negative value indicates that unit is not connected or a
system operation failed unexpectedly.
unit An integer variable, expression, or constant containing a Fortran unit number.

60 004– 2165– 002

OPENMS ( 3F ) OPENMS ( 3F )

NAME
OPENMS, OPENDR – Opens a local file as a random-access file that can be accessed or changed by the
record-addressable, random-access file I/O routines

SYNOPSIS
CALL OPENMS(dn, index, length, it [,ierr])
CALL OPENDR(dn, index, length, it [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
OPENMS/OPENDR opens a file and specifies it as a random-access file that can be modified by the
random-access I/O routines. If the file does not exist, the master index contains zeros; if it does exist, the
master index is read from the file. The master index contains the current index to the file that is updated
when the file is closed by using CLOSMS/CLOSDR.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The default number of open files is 20 for OPENDR and 40 for OPENMS.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
index The name of the array in the user program that is going to contain the master index to the
records of the file. Specify a type integer array. This array must be changed only by the
random-access file I/O routines. index should be a multiple of 512 words.
length The length of the index array. Specify a type integer variable, expression, or constant. The
length of index depends on the number of records on, or to be written to, the file, using the
master index and on the type of master index. The length specification must be at least 2(nrec)
if it=1 or 3, or nrec if it=0 or 2. nrec is the number of records in, or to be written to, the file,
using the master index.
it Flag indicating the type of master index. Specify a type integer variable, expression, or constant.
it can have one of the following values:
0 Records synchronously referenced with a number between 1 and length
1 Records synchronously referenced with an alphanumeric name of 8 or fewer characters
2 Records asynchronously referenced with a number between 1 and length
3 Records asynchronously referenced with an alphanumeric name of 8 or fewer characters

004– 2165– 002 61

OPENMS ( 3F ) OPENMS ( 3F )

For a named index, odd-numbered elements of the index array contain the record name, and
even-numbered elements of the index array contain the pointers to the location of the record
within the file. For a numbered index, a given index array element contains the pointers to the
location of the corresponding record within the file.
ierr Error control and code. Specify a type integer variable. If you specify ierr on the call to
OPENMS/OPENDR, ierr returns any error codes to you. If ierr is not specified, an error aborts
the program. If you set ierr>0 on input to OPENMS/OPENDR, error messages are not placed in
the stderr file; otherwise, an error code is returned, and the error message is added to the
stderr file. OPENMS/OPENDR writes an open message to the stderr file whether or not the
value of ierr selects messages. On output from OPENMS/OPENDR ierr has the following
values:
=0 No errors detected.
<0 Error detected. ierr contains one of the following error codes:
-1 The file name or unit number is not valid.
-2 The user-supplied index length is less than or equal to 0.
-3 The number of files has exceeded memory or size availability.
-4 The file index length read from the file is greater than the user-supplied index length
(nonfatal message).
-5 The user-supplied index length is greater than the index length read from the file
(nonfatal message).
-11 The index word address read from the file is less than or equal to 0.
-12 The index length read from the file is less than 0.
-13 The file has a checksum error.
-14 OPENMS has already opened the file.
-20 File created by WRITDR/WRITMS.
-21 Memory limit exceeded while allocating internal tables.
-22 Could not open an unsupported DRIO file version.

NOTES
A file opened with OPENMS should be closed only by CLOSMS(3F). If you close the file in some other way,
the future behavior of the program is unpredictable.
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking, and if you are multitasking your I/O calls.

62 004– 2165– 002

OPENMS ( 3F ) OPENMS ( 3F )

It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), FINDMS(3F), READMS(3F), STINDX(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

004– 2165– 002 63

PUTWA ( 3F ) PUTWA ( 3F )

NAME
PUTWA, APUTWA – Writes to a word-addressable, random-access file

SYNOPSIS
CALL PUTWA(dn, source, addr, count [,ierr])
CALL APUTWA(dn, source, addr, count [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
PUTWA synchronously writes a number of words from memory to a word-addressable, random-access file.
APUTWA asynchronously writes a number of words from memory to a word-addressable, random-access file.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
source Variable or array of any noncharacter type. The location of the first word in the user program to
be written to the file.
addr The word location of the file that is to receive the first word from the user program. addr=1
indicates beginning of file. Specify a type integer variable, expression, or constant.
count The number of words from source to be written. Specify a type integer variable, expression, or
constant.
ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
PUTWA/APUTWA, ierr returns any error codes to you. If ierr is not supplied, an error causes the
program to abort. On return from PUTWA/APUTWA, ierr has one of the following values:
0 No errors detected.
+1 Request did not fit in the page table (buffer cache) in one pass; therefore, request was not
truly asynchronous.
-1 Invalid unit number.
-2 Number of files has exceeded memory size availability.
-4 User-supplied word address less than or equal to 0.
-5 User-requested word count greater than maximum allowed.

64 004– 2165– 002

PUTWA ( 3F ) PUTWA ( 3F )

-6 Invalid file name.

-7 User word count less than or equal to 0.

NOTES
Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are
single-threaded. Some library routines, however, must be locked at the user level if they are used by more
than one task.
PUTWA is not internally locked. You must lock each call to PUTWA if it is called from more than one task.
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to stderr.
It is not valid to mix calls to word-addressable routines with standard Fortran I/O statements that use the
same unit number.

SEE ALSO
GETWA(3F), WCLOSE(3F), WOPEN(3F)

004– 2165– 002 65

READ ( 3F ) READ ( 3F )

NAME
READ, READP – Reads words, full or partial record modes

SYNOPSIS
CALL READ(unit, word, count, status, [ubc])
CALL READP(unit, word, count, status, [ubc])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The READ and READP routines move words of data from disk or tape to a variable or array. After reading
less than a full record from disk or tape, READ leaves the file positioned at the beginning of the next record,
while READP leaves the file positioned at the next item in the record just read.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable, expression, or constant. unit can be a unit number or name of the file as a
Hollerith constant of 7 characters or less (’MYFILE’L).
word Word-receiving data area, such as a variable or array.
count Integer variable. On entry, the number of words requested. (Do not specify a constant.) On
exit, the number of words actually transferred.
status Integer variable. On exit, status has one of the following values:
=-1 Words remain in record
= 0 End-of-record (EOR)
= 1 Null record
= 2 End-of-file (EOF)
= 3 End-of-data (EOD)
= 4 Hardware error
≥5 Error. The value may represent a Fortran library error or a system error. If it is a system
error, a definition may be found in <errno.h>. See the explain(1) command for
further details. See intro(2) in the UNICOS System Calls Reference Manual, for a
description of the system error names and numbers.

66 004– 2165– 002

READ ( 3F ) READ ( 3F )

ubc Integer variable. Optional unused bit count. Number of unused bits contained in the last word of
the record.

NOTES
If foreign record translation is enabled for the specified unit, the bits from the foreign logical records are
delivered to the user data area without data conversion.

EXAMPLES
The following example reads the first 2 words of the next record on unit 15. It also checks for success by
examining the returned value of status and writing a message containing the number of words read.
INTEGE R REC(10 )
IUNIT = 15
NUM = 2
CALL REA D(I UNI T, REC , NUM, ISTAT)
IF (IS TAT .GT . 1) THE N
C han dle exc eption al condit ion s (EOF, EOD, err or)
CAL L ABO RT( ’unexp ected sta tus enc ountered’ )
END IF
WRITE( *,* )’ Read ’ ,NU M,’ actual wor ds’
END

SEE ALSO
ACPTBAD(3F), READC(3F), READIBM(3F), SKIPBAD(3F), WRITE(3F), WRITEC(3F), WRITIBM(3F)

004– 2165– 002 67

READC ( 3F ) READC ( 3F )

NAME
READC, READCP – Reads characters, full or partial record mode

SYNOPSIS
CALL READC(unit, char, count, status)
CALL READCP(unit, char, count, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
READC and READCP routines unpack characters from the I/O buffer and insert them in the user data area
beginning at the first word address. Characters are placed into the data area, 1 character per word,
right-justified. This process continues until the count is satisfied or an end-of-record (EOR) is encountered.
If an EOR is encountered first, the remainder of the field specified by the character count is filled with
blanks.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable, expression, or constant. unit can be a unit number or file name as a
Hollerith constant of 7 characters or less (’MYFILE’L).
char Character-receiving data area.
count Integer variable. On entry, the number of characters requested. On exit, the number of
characters actually transferred.
status Integer variable. On exit, status has one of the following values:
=-1 Characters remain in record
= 0 End-of-record (EOR)
= 1 Null record
= 2 End-of-file (EOF)
= 3 End-of-data (EOD)
= 4 Hardware error
≥5 Error. If it is a system error, a definition may be found in <errno.h>. See
explain(1) for complete details. See intro(2) in the UNICOS System Calls Reference
Manual, for a description of the system error names and numbers.

68 004– 2165– 002

READC ( 3F ) READC ( 3F )

NOTES
If foreign record translation is enabled for the specified unit, the bits from the foreign logical records are
delivered after character conversion as specified with the assign(1) command.

SEE ALSO
ACPTBAD(3F), READ(3F), READIBM(3F), SKIPBAD(3F), WRITE(3F), WRITEC(3F), WRITIBM(3F)
explain(1) in UNICOS User Commands Reference Manual

004– 2165– 002 69

READIBM ( 3F ) READIBM ( 3F )

NAME
READIBM – Reads two IBM 32-bit floating-point words from each Cray Research 64-bit word

SYNOPSIS
CALL READIBM(unit, fwa, word, increment)

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
READIBM reads two IBM 32-bit floating-point words from each Cray Research 64-bit word.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable, expression, or constant. unit can be a unit number or file name as a
Hollerith constant of 7 characters or less.
fwa First word address (FWA) of the user data area.
word Number of words needed.
increment Increment of the IBM words read.
On exit, the IBM 32-bit format is converted to the equivalent Cray Research 64-bit value. The Cray
Research 64-bit words are stored in the user data area.

NOTES
IBM2CRAY(3F) is the recommended routine for performing the same conversion.

SEE ALSO
ACPTBAD(3F), READ(3F), READC(3F), SKIPBAD(3F), WRITE(3F), WRITEC(3F), WRITIBM(3F)

70 004– 2165– 002

READMS ( 3F ) READMS ( 3F )

NAME
READMS, READDR – Reads a record from a random-access file to memory

SYNOPSIS
CALL READMS(dn, ubuff, n, irec [,ierr])
CALL READDR(dn, ubuff, n, irec [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
READMS and READDR read records from a random-access file to a contiguous memory area in the user’s
program.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
ubuff The location in your program where the first word of the record is placed. User-specified type;
do not use type character.
n The number of words to be read. Specify a type integer variable, expression, or constant. n
words are read from the random-access record irec and placed contiguously in memory,
beginning at ubuff. If necessary, READDR rounds n up to the next multiple of 512 words. If the
file is in synchronous mode, the data is saved and restored after the read. The maximum record
size is limited to 4,194,303 words.
irec The record number or record name of the record to be read. Specify a type integer variable,
expression, or constant. A record name is limited to a maximum of 8 characters. For a
numbered index, irec must be between 1 and the length of the index declared in the
OPENMS/OPENDR(3) call, inclusive. For a named index, irec is any 64-bit entity you specify.
ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
READMS/READDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned, and the message is added to the stderr
file.
On output from READMS/READDR, ierr has one of the following values:
=0 No errors detected.
<0 Error detected. ierr contains one of the following error codes:

004– 2165– 002 71

READMS ( 3F ) READMS ( 3F )

-1 The file name or unit number is invalid.

-6 The user-supplied named index is invalid.
-8 The index number is greater than the maximum on the file.
-10 The named record was not found in the index array.
-15 OPENMS/OPENDR was not called on this file.
-17 The index entry is less than or equal to 0 in the user’s index array.
-18 The user-supplied word count is less than or equal to 0.
-19 The user-supplied index number is less than or equal to 0.

NOTES
Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are
single threaded. Some library routines, however, must be locked at the user level if they are used by more
than one task.
READMS and READDR are not internally locked. You must lock each call to these routines if they are called
from more than one task.
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to stderr.
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking and if you are multitasking your I/O calls.
It is not valid to mix calls to word-addressable routines with standard Fortran I/O statements that use the
same unit number.

CAUTIONS
If you are using READDR in asynchronous mode, and the record size is not a multiple of 512 words, user
data can be overwritten and not restored. With SYNCDR(3F), the file can be switched to read synchronously,
causing data to be copied out and restored after the read has completed.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), STINDX(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

72 004– 2165– 002

RNL ( 3F ) RNL ( 3F )

NAME
RNLFLAG, RNLDELM, RNLSEP, RNLREP, RNLCOMM – Manipulates characters recognized by NAMELIST

SYNOPSIS
CALL RNLFLAG(char, mode)
CALL RNLDELM(char, mode)
CALL RNLSEP(char, mode)
CALL RNLREP(char, mode)
CALL RNLCOMM(char, mode)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
These routines perform character manipulation.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX, all arguments must
be of default kind unless documented otherwise. On UNICOS the default kind is KIND=8 for integer, real,
complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine.
char For RNLFLAG, an echo character. Default is E.
For RNLDELM, a delimiting character. The defaults are $ and &.
For RNLSEP, a separator character. Default is a comma (,).
For RNLREP, a replacement character. Default is =.
For RNLCOMM, a trailing comment indicator. Defaults are a colon (:) and a semicolon (;).
mode mode can have the following values:
=0 Delete character
≠0 Add character
In each of these user-control subroutine argument lists, char is a character variable that contains any ASCII
character. Except on the Cray T90 series, char may also be a Hollerith character, specified by 1Lx or 1Rx.
These routines support the Cray Fortran 77 (CF77) namelist extension. The ANSI Fortran 90 standard
introduced a standardized version of namelist I/O. The facilities provided by these routines are not used by
namelist I/O in a Fortran program compiled with Cray Fortran 90 (CF90) unless the -f77 option is supplied
on the assign command for a file or unit.

004– 2165– 002 73

RNL ( 3F ) RNL ( 3F )

RNLFLAG adds or removes char from the set of characters that, if found in column 1, initiates echoing of
the input lines to stdout.
RNLDELM adds or removes char from the set of characters that precede the NAMELIST group name and
signal end-of-input.
RNLSEP adds or removes char from the set of characters that must follow each constant to act as a
separator.
RNLREP adds or removes char from the set of characters that occur between the variable name and the
value.
RNLCOMM adds or removes char from the set of characters that initiate trailing comments on a line.
No checks are made to determine the reasonableness, usefulness, or consistency of these changes.

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNLECHO(3F), RNLSKIP(3F), RNLTYPE(3F), WNL(3), WNLLINE(3F), WNLLONG(3F)

74 004– 2165– 002

RNLECHO ( 3F ) RNLECHO ( 3F )

NAME
RNLECHO – Specifies output unit for NAMELIST error messages and echo lines

SYNOPSIS
CALL RNLECHO(unit)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
RNLECHO specifies the output unit for NAMELIST error messages and echo lines.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX, all arguments must
be of default kind unless documented otherwise. On UNICOS the default kind is KIND=8 for integer, real,
complex, and logical arguments; on IRIX, the default kind is KIND=4.
unit Output unit to which error messages and echo lines are sent. If unit= – 1, error messages and
lines echoed because of an E in column 1 go to standard output (stdout).
If unit ≤ 0, error messages and input lines are echoed to unit, regardless of any echo flags
present. If unit=6 or unit=101, stdout is implied.

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLSKIP(3F), RNLTYPE(3F) WNL(3), WNLLINE(3F), WNLLONG(3F)

004– 2165– 002 75

RNLSKIP ( 3F ) RNLSKIP ( 3F )

NAME
RNLSKIP – Takes appropriate action when an undesired NAMELIST group is encountered

SYNOPSIS
CALL RNLSKIP(mode)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
RNLSKIP determines an appropriate action if the NAMELIST group encountered is not the desired group.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX, all arguments must
be of default kind unless documented otherwise. On UNICOS the default kind is KIND=8 for integer, real,
complex, and logical arguments; on IRIX, the default kind is KIND=4.
mode mode can have one of the following values:
>0 Skips the record and issues a message (default)
=0 Skips the record
<0 Aborts the job or goes to the optional ERR= branch

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLECHO(3F), RNLTYPE(3F), WNL(3), WNLLINE(3F), WNLLONG(3F)

76 004– 2165– 002

RNLTYPE ( 3F ) RNLTYPE ( 3F )

NAME
RNLTYPE – Determines action if type mismatch occurs across equal sign on NAMELIST input record

SYNOPSIS
CALL RNLTYPE(mode)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
RNLTYPE determines an action if a type mismatch occurs.
mode If mode is not equal to 0, converts the constant to the type of the variable (default). If mode=0,
aborts the job or goes to the optional ERR= branch.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX, all arguments must
be of default kind unless documented otherwise. On UNICOS the default kind is KIND=8 for integer, real,
complex, and logical arguments; on IRIX, the default kind is KIND=4.

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLECHO(3F), RNLSKIP(3F), WNL(3F), WNLLINE(3F), WNLLONG(3F)

004– 2165– 002 77

SETSP ( 3F ) SETSP ( 3F )

NAME
SETSP – Enables and disables EOV processing

SYNOPSIS
CALL SETSP(unit, iflag, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SETSP enables and disables end-of-volume (EOV) processing.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
iflag Enable or disable flag; iflag has the following arguments:
=0 Disables EOV processing
≠0 Enables EOV processing
istat Result of SETSP; istat can have one of the following values:
=0 No error
≠0 Error occurred

NOTES
The following preconditions must exist:
• The file must be an opened tape or ER90 file and must use the FFIO tape layer. ER90 files are not
supported on Cray T3E systems.
• EOV processing must be disabled for you to enable it.
• EOV processing must be enabled for you to disable it.
SEE ALSO
CHECKTP(3F), CLOSEV(3F), ENDSP(3F), STARTSP(3F)
Tape Subsystem User’s Guide

78 004– 2165– 002

SETTP ( 3F ) SETTP ( 3F )

NAME
SETTP – Positions a tape file at a tape block and/or a tape volume

SYNOPSIS
CALL SETTP(unit, nbs, nb, nvs, nv, ivi, synch, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SETTP lets a program position a tape file at a particular tape block and/or tape volume. Tape volumes and
blocks are numbered sequentially, starting at 1. Volume positioning, if selected, occurs prior to any block
positioning. Volumes can be selected either by number or by volume identifier.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
nbs Block number request sign. This parameter must be set to one of the following Hollerith values:
1H+ Indicates that the nb parameter is the number of blocks to skip forward, relative to the
current position.
1H- Indicates that the nb parameter is the number of blocks to skip backward relative to the
current position.
1H Indicates that the nb parameter is an absolute block number, relative to the last tape
mark or beginning-of-volume. If a nonzero value is specified for the nv parameter,
positioning is absolute with respect to that tape volume. If nv is 0, and the -T
parameter was not present on the tpmnt(1) command, the positioning is absolute with
respect to the current tape volume. If nv is 0, and the -T parameter was present on the
tpmnt command, then positioning is absolute with respect to the last tape mark read or
written. One blank space must follow 1H.
nb Integer block number. Specifies the relative or absolute block number to which the tape file is
to be positioned. A block number of 0 indicates no block positioning should be performed. A
negative block number is not valid.
nvs Volume number request sign. This parameter must be set to one of the following Hollerith
values:

004– 2165– 002 79

SETTP ( 3F ) SETTP ( 3F )

1H+ Indicates that the nv parameter is the number of volumes to skip forward, relative to the
current position.
1H– Indicates that the nv parameter is the number of volumes to skip backward relative to
the current position.
1H Indicates that the nv parameter is an absolute volume number, relative to the beginning
of the volume identifier list (specified on the tpmnt(1) command). One blank space
must follow 1H.
nv Integer volume number. Specifies the relative or absolute volume to which the tape file is to be
positioned. A volume number of 0 indicates no volume positioning is to be performed. A
negative volume number is invalid.
ivi Name of volume identifier to be mounted. The name must be left-justified and zero-filled. A
nonzero ivi parameter is not valid if nbs is 1H+ or 1H-, or if nvs is 1H+ or 1H-, or if nv is
nonzero. Specifying the volume identifier currently mounted causes it to be rewound.
synch Parameter to allow compatibility with the COS operating system; not supported under the
UNICOS operating system. The tape file is always synchronized (that is, all pending I/O is
allowed to complete) before any positioning.
istat Integer return status. On exit, this parameter contains a value indicating the status of the
positioning request.
=0 Indicates that the file was successfully positioned.
≠0 Indicates that an error was encountered trying to position the tape file, or an argument that
was not valid was passed to SETTP (for example, nb<0).

NOTES
The file must be a tape or ER90 file and must use the FFIO tape layer. ER90 files are not supported on
Cray T3E systems.
The er90 layer is not available on Cray T3E systems. See the assign(1) man page and the Tape
Subsystem User’s Guide for more information about the er90 FFIO layer.

SEE ALSO
GETTP(3F)
tpmnt(1) in the UNICOS User Commands Reference Manual

80 004– 2165– 002

SKIPBAD ( 3F ) SKIPBAD ( 3F )

NAME
SKIPBAD – Skips bad data

SYNOPSIS
CALL SKIPBAD(unit, blocks, termcnd)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SKIPBAD lets you skip bad data so that bad data is not sent to the user-specified buffer.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of arguments for this routine.
unit An integer variable or array element containing the Fortran unit number; unit may contain
Hollerith data of not more than 7 characters.
blocks On exit, this is the number of physical tape blocks skipped.
termcnd On exit, termcnd can have one of the following values:
<0 Not positioned at end-of-block
=0 Positioned at end-of-block
=1 Positioned at end-of-file

004– 2165– 002 81

SKIPBAD ( 3F ) SKIPBAD ( 3F )

EXAMPLES

PRO GRAM EXA MPLE1

IMP LICIT INTEGE R(A-Z)
PARAME TER(NB YTES=4000 0,N DIM=NB YTE S/8,DN=99 )
DIM ENSION BUF FER(1: NDIM)
DIMENS ION UDA (1:2*NDIM )

2000 CONTIN UE
NWORDS = NDI M
CALL READ(D N,B UFFER, NWORDS ,STATU S)
IF((ST ATUS.E Q.2) .OR . (ST ATU S.EQ.3)) THE N ! EOF or EOD
STOP ’COMPL ETE ’
ELSE IF (ST ATU S .EQ. 4) THE N ! Parity err or
CALL SKIPBA D(DN, BLOCKS , TERMCN D)
IF (TE RMCND .LT. 0) THEN
PRI NT *,’ERR OR WHE N SKIPPI NG BAD DATA = ’,TERM CND
STOP ’ER ROR ’

ELS EIF (TE RMCND.EQ. 0)THEN

PRINT *,’SKIPPE D ’,BLOC KS, ’ BAD BLOCKS ’
ELSE ! EOF
PRINT *,’SKIPPE D ’,B LOC KS, ’ BAD BLO CKS’
STO P ’CO MPLETE ’
ENDIF
GOT O 200 0
END IF
C ...
C Pro ces s dat a
C ...
GOT O 200 0 ! Con tinue rea ding
END

SEE ALSO
ACPTBAD(3F)

82 004– 2165– 002

SKIPF ( 3F ) SKIPF ( 3F )

NAME
SKIPF – Skips files

SYNOPSIS
CALL SKIPF(iunit, [ifile, istat, [retstat]])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SKIPF directs the system to skip a specified number of files from the current position.
When using the CF90 compiler on UNICOS and UNICOS/mk systems, all arguments must be of default
kind unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer,
real, complex, and logical arguments.
The following is a list of valid arguments for this routine.
iunit An integer variable or array element containing the Fortran unit number. Name of the file or
unit number to be positioned.
ifile Integer number. This parameter specifies the number of files to be skipped. If ifile is negative,
SKIPF positions backwards. If iunit is positioned midfile, the partial file skipped counts as one
file.
istat A 2-element integer array that returns the number of files skipped in the second element. istat is
an optional argument.
retstat Integer number. retstat is an optional argument. If present, retstat contains a value indicating
the status of the SKIPF request on return from the SKIPF subroutine. If this argument is not
present and a fatal error occurs while positioning, the program is aborted. retstat can have one
of the following values:
=0 Indicates that positioning was successful
≠0 Indicates that an error occurred

NOTES
SKIPF does not skip past end-of-data (EOD) or beginning-of-data (BOD). If BOD is encountered before
ifile files have been skipped when skipping backward, the file is positioned after the BOD. When skipping
forward, the file is positioned before the EOD of the current file. SKIPF is currently supported only for
online tape or ER90 files that use the FFIO tape layer.

004– 2165– 002 83

SKIPF ( 3F ) SKIPF ( 3F )

SKIPF can be used for positioning by user tape mark for tapes (see the -T option on the tpmnt(1)
command). SKIPF may not be used to position to different files within a multifile volume (see the -q
option of the tpmnt(1) command).

SEE ALSO
tpmnt(1) in the UNICOS User Commands Reference Manual

84 004– 2165– 002

STARTSP ( 3F ) STARTSP ( 3F )

NAME
STARTSP – Enables special tape processing

SYNOPSIS
CALL STARTSP(unit, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
STARTSP enables special end of volume (EOV) tape processing.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
istat Result of STARTSP; istat can have one of the following values:
=0 Special processing initiated
≠0 Special processing not initiated

NOTES
The following preconditions must exist:
• The file must be an opened tape or ER90 file and must use the FFIO tape layer. ER90 files are not
supported on Cray T3E systems.
• EOV processing must be enabled.
• Special processing must be disabled.
STARTSP creates an alternative path to or from a tape. Tape blocks in the pipeline are held aside.
Subsequent write operations will go directly to tape; subsequent read operations will come directly from tape
(if data is available) or from the blocks in the pipeline. Both read and write operations are performed in
first-in-first-out (FIFO) order. After you have read from the blocks in the pipeline, they are unavailable for
writing after the ENDSP(3F) routine.

SEE ALSO
CHECKTP(3F), CLOSEV(3F), ENDSP(3F), SETSP(3F)
Tape Subsystem User’s Guide

004– 2165– 002 85

STINDX ( 3F ) STINDX ( 3F )

NAME
STINDX, STINDR – Allows an index to be used as the current index by creating a subindex

SYNOPSIS
CALL STINDX(filename, index, length, it [,ierr])
CALL STINDR(filename, index, length, it [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
STINDX/STINDR reduces the amount of memory needed by a file containing a large number of records. It
also maintains a file containing records logically related to each other. Records in the file, rather than
records in the master index area, hold secondary pointers to records in the file.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
filename An integer variable, expression, or constant that has a maximum of 8 characters. The name of
the file as a Hollerith constant. Alternatively, filename can be a positive integer that identifies
the file as fort.n, where n = filename. If an integer value is passed in filename, it must be in
the range 0 < n < 100.
index The user-supplied array used for the subindex or new current index. Specify a type integer
array. If index is a subindex, it must be a storage area that does not overlap the area used in
OPENMS/OPENDR(3) to store the master index.
length The length of the index array. Specify a type integer variable, expression, or constant. The
length of index depends on the number of records in the file or to be written to the file using the
master index and on the type of master index. If it=1, length must be at least twice the number
of records in the file or to be written to the file using index. If it=0, length must be at least the
number of records on or to be written to the file using index.
it A flag to indicate the type of index. Specify a type integer variable, expression, or constant.
When it=0, the records are referenced with a number between 1 and length. When it=1, the
records are referenced with an alphanumeric name of 8 or fewer characters. For a named index,
odd-numbered elements of the index array contain the record name and even-numbered elements
of the index array contain pointers to the location of the record within the file. For a numbered
index, a given index array element contains pointers to the location of the corresponding record
within the file. The index type defined by STINDX/STINDR must be the same as that used by
OPENMS/OPENDR.

86 004– 2165– 002

STINDX ( 3F ) STINDX ( 3F )

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
STINDX/STINDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned, and the message is added to the stderr
file.
On return from STINDX/STINDR, ierr has one of the following values:
=0 No errors detected.
<0 Error detected. ierr contains one of the error codes described in the following table:
-1 The file name or unit number is not valid.
-15 OPENMS/OPENDR was not called on this file.
-16 A STINDX/STINDR call cannot change the index type.
STINDX/STINDR allows more than one index to manipulate the file. Generally, STINDX/STINDR toggle
the index between the master index (maintained by OPENMS/OPENDR and CLOSMS/CLOSDR(3)) and a
subindex (supplied and maintained by you).
You must maintain and update subindex records stored in the file. You can access and change records in the
file only by using the current index.
After a STINDX/STINDR call, subsequent calls to READMS/READDR(3) and WRITMS/WRITDR(3) use and
alter the current index array specified in the STINDX/STINDR call. You can save the subindex by calling
STINDX/STINDR with the master index array, then writing the subindex array to the file using
WRITMS/WRITDR. Retrieve the subindex by calling READMS/READDR on the record containing the
subindex information. Thus, STINDX/STINDR allows logically infinite index trees into the file and reduces
the amount of memory needed for a random-access file containing many records.

CAUTIONS
When generating a new subindex (for example, building a database), set the array or memory area used for
the subindex to 0. If the subindex storage is not set to 0, unpredictable results occur.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), READMS(3F), SYNCMS(3F),
WAITMS(3F), WRITMS(3F)

004– 2165– 002 87

SYNCMS ( 3F ) SYNCMS ( 3F )

NAME
SYNCMS, SYNCDR – Sets I/O mode for random-access routines to synchronous

SYNOPSIS
CALL SYNCMS(dn [,ierr])
CALL SYNCDR(dn [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SYNCMS and SYNCDR set the I/O mode for random-access routines.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
ierr Error control and code. Specifies an integer variable. If you supply ierr on the call to
SYNCMS/SYNCDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned, and the message is added to the stderr
file.
On return from SYNCMS/SYNCDR, ierr has one of the following values:
=0 No errors detected.
<0 Error detected. ierr contains one of the following error codes:
-1 The file name or unit number is invalid.
-15 OPENMS/OPENDR was not called on this file.
All I/O operations wait for completion.

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking and if you are multitasking your I/O calls.

88 004– 2165– 002

SYNCMS ( 3F ) SYNCMS ( 3F )

It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), READMS(3F), STINDX(3F),
WAITMS(3F), WRITMS(3F)

004– 2165– 002 89

TSYNC ( 3F ) TSYNC ( 3F )

NAME
TSYNC – Requests tape synchronization

SYNOPSIS
CALL TYSNC(unit, istat)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TSYNC synchronizes a tape or ER90 file. This request is ignored if the last operation was a read. If the last
operation was a write, the tape file is synchronized (that is, buffered data is written to the tape). This routine
will return an error if the user has specified any FFIO layers other than the tape layer, the er90 layer, or
the bufa layer (see assign(1)).
It is not valid to call TSYNC in the following circumstance: when end-of-volume (EOV) processing is
enabled, and when the user has reached the EOV but has not started special processing.
If TSYNC is called when EOV processing is enabled, it may cause the user to reach EOV. In this case,
TSYNC will return without error, but the tape may not be synchronized. When EOV processing is enabled,
the user should check to see if EOV was reached by calling CHECKTP(3F) after calling TSYNC.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine:
unit An integer variable or array element containing the Fortran unit number or Hollerith data of not
more than 7 characters.
istat If istat=0, no error occurred. If istat is nonzero, an error or warning occurred.

NOTES
The file must be a tape or ER90 file. ER90 files and the er90 layer are not supported on Cray T3E
systems.

SEE ALSO
CHECKTP(3F)
assign(1)

90 004– 2165– 002

WAITMS ( 3F ) WAITMS ( 3F )

NAME
WAITMS, WAITDR – Waits for completion of an asynchronous I/O operation

SYNOPSIS
CALL WAITMS(dn, istat [,ierr])
CALL WAITDR(dn, istat [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WAITMS and WAITDR wait for completion of an asynchronous I/O operation.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn Integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
istat File error flag. Specify a type integer variable; istat can have one of the following values:
0 No error occurred during the asynchronous I/O operation
1 Error occurred during the asynchronous I/O operation
ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
WAITMS/WAITDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned, and the message is added to the stderr
file.
On return from WAITMS/WAITDR, ierr has one of the following values:
=0 No errors detected.
<0 Error detected. ierr contains one of the following error codes:
–1 The file name or unit number if not valid.
-15 OPENMS/OPENDR was not called on this file.

NOTES
The random-access I/O routines cannot be used in multitasking unless you provide your own locks. If you
are Autotasking or if you are not multitasking at all, you will not be affected. You will need locks only if
you are doing your own macrotasking or microtasking and if you are multitasking your I/O calls.

004– 2165– 002 91

WAITMS ( 3F ) WAITMS ( 3F )

It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

SEE ALSO
ASYNCMS(3F), CHECKMS(3F), CLOSMS(3F), FINDMS(3F), OPENMS(3F), READMS(3F), SYNCMS(3F),
STINDX(3F) WRITMS(3F)

92 004– 2165– 002

WCLOSE ( 3F ) WCLOSE ( 3F )

NAME
WCLOSE – Finalizes changes and closes word-addressable, random-access file

SYNOPSIS
CALL WCLOSE(dn [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WCLOSE finalizes the additions and changes to the word-addressable, random-access file and closes the file.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
ierr Error control and code. Specify an integer variable, expression, or constant. If you supply ierr
on the call to WCLOSE, ierr returns any error codes to you. If ierr is not supplied, an error
aborts the program.
On output from WCLOSE, ierr has one of the following values:
0 No errors detected
-1 Invalid unit number
-6 Invalid file name

NOTES
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to stderr.
It is not valid to mix calls to word-addressable routines with standard Fortran I/O statements that use the
same unit number.

SEE ALSO
GETWA(3F), PUTWA(3F), WOPEN(3F)

004– 2165– 002 93

WNL ( 3F ) WNL ( 3F )

NAME
WNLFLAG, WNLDELM, WNLSEP, WNLREP – Provides user control of NAMELIST output format

SYNOPSIS
CALL WNLFLAG(char)
CALL WNLDELM(char)
CALL WNLSEP(char)
CALL WNLREP(char)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
These routines provide user control of output formatting.
char For WNLFLAG, the first ASCII character of the first line. Default is a blank.
For WNLDELM, a NAMELIST delimiter. Default is &.
For WNLSEP, a NAMELIST separator. Default is a comma (,).
For WNLREP, a NAMELIST replacement character. Default is =.
WNLFLAG changes the character written in column 1 of the first line from blank to char. Typically, char is
used for carriage control if the output is to be listed, or for forcing echoing if the output is to be used as
input for NAMELIST reads.
WNLDELM changes the character preceding the group name and END from & to char.
WNLSEP changes the separator character immediately following each value from , to char.
WNLREP changes the replacement operator that comes between name and value from = to char.
In each of these subroutines, char is a character variable that contains any ASCII character. Except on the
Cray T90 series, char may also be a Hollerith character, specified by 1Lx or 1Rx.
These routines support the Cray Research FORTRAN 77 (CF77) namelist extension. The ANSI Fortran 90
standard introduced a standardized version of namelist I/O. The facilities provided by these routines are not
used by namelist I/O in a Fortran program compiled with Cray Research Fortran 90 (CF90) unless the -f77
option is supplied on the assign(1) command for a file or unit.

94 004– 2165– 002

WNL ( 3F ) WNL ( 3F )

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLECHO(3F), RNLSKIP(3F), RNLTYPE(3F), WNLLINE(3F), WNLLONG(3F)

004– 2165– 002 95

WNLLINE ( 3F ) WNLLINE ( 3F )

NAME
WNLLINE – Allows each NAMELIST variable to begin on a new line

SYNOPSIS
CALL WNLLINE(value)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
WNLLINE allows each NAMELIST variable to begin on a new line.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX, all arguments must
be of default kind unless documented otherwise. On UNICOS the default kind is KIND=8 for integer, real,
complex, and logical arguments; on IRIX, the default kind is KIND=4.
value The following values are possible for the value argument:
0 No new line
1 New line for each variable

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLECHO(3F), RNLSKIP(3F), RNLTYPE(3F), WNL(3), WNLLONG(3F)

96 004– 2165– 002

WNLLONG ( 3F ) WNLLONG ( 3F )

NAME
WNLLONG – Selects NAMELIST output line length

SYNOPSIS
CALL WNLLONG(length)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is valid only when compiling programs with the MIPSpro 7 Fortran 90
compiler or when compiling programs with the -craylibs option to the MIPSpro F77 compiler. See the
"BUGS" subsection for further details.
WNLLONG specifies the output line length of the NAMELIST variable.
length The maximum output line length for NAMELIST writes, in the range 8 < length < 267. A length
of -1 has the effect of setting the output length to the initial, default value (133 for NAMELIST
output).
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS the default kind is KIND=8 for integer, real, complex, and logical
arguments.

NOTES
WNLLONG is overridden by the RECL parameter on the OPEN statement. Where possible, RECL should be
used in place of WNLLONG to select the NAMELIST output line length.

BUGS
On IRIX systems, the implementation of these routines has not been thoroughly tested.

SEE ALSO
RNL(3), RNLECHO(3F), RNLSKIP(3F), RNLTYPE(3F), WNL(3), WNLLINE(3F)

004– 2165– 002 97

WOPEN ( 3F ) WOPEN ( 3F )

NAME
WOPEN – Opens a word-addressable, random-access file

SYNOPSIS
CALL WOPEN(dn, blocks, istats [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WOPEN opens a file and specifies it as a word-addressable, random-access file that can be accessed or
changed with the word-addressable I/O routines. The WOPEN call is optional.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
dn An integer variable, expression, or constant with a maximum of 8 characters. dn can be a unit
number or the name of the file as a Hollerith constant.
blocks The maximum number of 512-word blocks that the word-addressable package can use for a
buffer. Specify a type integer variable, expression, or constant.
istats Specify a type integer variable, expression, or constant. If istats is nonzero, statistics about the
changes and accesses to the file filename are collected. (See the following table for information
about the statistics that are collected.) Statistics are written to stderr.
ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
WOPEN, ierr returns any error codes to you. If ierr is not supplied, an error aborts the job.
On output from WOPEN, ierr has one of the following values:
0 No errors detected
-1 Invalid unit number
-2 Number of files has exceeded memory size availability
-6 Invalid file name

NOTES
A file opened using WOPEN should be closed only by WCLOSE(3F). If you close the file in some other way,
the subsequent behavior of the program and the validity of the file are unpredictable.

98 004– 2165– 002

WOPEN ( 3F ) WOPEN ( 3F )

If you bypass WCLOSE, the internal tables maintained by the word-addressable I/O package are not updated,
leaving dangling pointers in future computation.
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to stderr.
It is not valid to mix calls to word-addressable routines with standard Fortran I/O statements that use the
same unit number.

MESSAGES

Message Description

BUFFERS USED = Number of 512-word buffers used by this file.

TOTAL ACCESSES = Number of accesses. This is the sum of the GETWA(3F) and
PUTWA(3F) calls.
GETS = Number of times the user called GETWA.
PUTS = Number of times the user called PUTWA.
FINDS = Number of times the user called SEEK(3F).
HITS = Number of times word addresses desired were resident in memory.
MISSES = Number of times no word addresses desired were resident in memory.
PARTIAL HITS = Number of times that some but not all of the word addresses desired
were in memory.
DISK READS = Number of physical disk reads done.
DISK WRITES = Number of times a physical disk was written to.
BUFFER FLUSHES = Number of times buffers were flushed.
WORDS READ = Number of words moved from buffers to user.
WORDS WRITTEN = Number of words moved from user to buffer.
TOTAL WORDS = Sum of WORDS READ and WORDS WRITTEN.
TOTAL ACCESS TIME = Real time spent in disk transfers.
AVER ACCESS TIME = TOTAL ACCESS TIME divided by the sum of DISK READS and
DISK WRITES.
EOD BLOCK NUMBER = Number of the last block of the file.
DISK WORDS READ = Count of number of words moved from disk to buffers.
DISK WDS WRITTEN = Count of number of words moved from buffers to disk.
TOTAL DISK XFERS = Sum of DISK WORDS READ and DISK WORDS WRITTEN.
BUFFER BONUS % = TOTAL WORDS divided by value TOTAL DISK XFERS multiplied
by 100.

SEE ALSO
GETWA(3F), PUTWA(3F), WCLOSE(3F)

004– 2165– 002 99

WRITE ( 3F ) WRITE ( 3F )

NAME
WRITE, WRITEP – Writes words, full or partial record mode

SYNOPSIS
CALL WRITE(unit, word, count, ubc, status)
CALL WRITEP(unit, word, count, ubc, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WRITE and WRITEP write words in full or partial record mode.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable, expression, or constant. unit can be a unit number or file name as a
Hollerith in 7 characters or less (’MYFILE’L).
word Data area containing words; this may not be a Fortran character variable.
count An integer variable. Word count. For WRITE, a value of 0 causes an end-of-record (EOR)
record control word to be written.
ubc An integer variable. Optional unused bit count. Number of unused bits contained in the last
word of the record.
status An integer variable. Optional status. If present, status has one of the following values on exit:
=0 No error.
≠0 Error. If it is a system error, a definition may be found in <errno.h>. See the
explain(1) command for complete details. See intro(2) in UNICOS System Calls
Reference Manual, for a description of the system error names and numbers.
In routines in which words are written, the number of words specified by the count are transmitted from the
area beginning at the first word address and are written in the I/O buffer.

NOTES
If foreign record translation is enabled for the specified unit, the bits from the user are delivered to the
foreign logical records without data conversion.

100 004– 2165– 002

WRITE ( 3F ) WRITE ( 3F )

SEE ALSO
ACPTBAD(3F), READ(3F), READC(3F), READIBM(3F), SKIPBAD(3F), WRITEC(3F), WRITIBM(3F)
explain(1) in the UNICOS User Commands Reference Manual

004– 2165– 002 101

WRITEC ( 3F ) WRITEC ( 3F )

NAME
WRITEC, WRITECP – Writes characters, full or partial record mode

SYNOPSIS
CALL WRITEC(unit, char, count, status)
CALL WRITECP(unit, char, count, status)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WRITEC and WRITECP write characters in full or partial record mode.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
unit An integer variable, expression, or constant. unit can be a unit number or file name as a
Hollerith constant in 7 characters or less (’MYFILE’L).
char Data area containing characters; this may not be a Fortran character variable.
count Type integer variable. Character count.
status Type integer variable. Optional status. If present, status has one of the following values on
exit:
=0 No error.
≠0 Error. If it is a system error, a definition may be found in <errno.h>. See intro(2)
in UNICOS System Calls Reference Manual, for a description of the system error names
and numbers.
WRITEC and WRITECP routines pack characters into the I/O buffer for the file. The count specifies the
number of characters packed. These characters originate from the user area defined at the first word address,
which is 1 character per source word (right-justified).

NOTES
If foreign record translation is enabled for the specified unit, the bits from the user are delivered to the
foreign logical records after character conversion is specified with the assign(1) command.

102 004– 2165– 002

WRITEC ( 3F ) WRITEC ( 3F )

SEE ALSO
ACPTBAD(3F), READ(3F), READC(3F), READIBM(3F), SKIPBAD(3F), WRITE(3F), WRITIBM(3F)
assign(1)

004– 2165– 002 103

WRITIBM ( 3F ) WRITIBM ( 3F )

NAME
WRITIBM – Writes two IBM 32-bit floating-point words from each Cray 64-bit word

SYNOPSIS
CALL WRITIBM(unit, fwa, value, increment)

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION

WRITIBM writes two IBM 32-bit floating-point words from each Cray 64-bit word.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
unit File name or unit number
fwa First word address (FWA) of the user data area
value Number of values to be written
increment Increment of the source (Cray) words written

NOTES
On exit, IBM 32-bit words are written to the unit.

SEE ALSO
ACPTBAD(3F), READ(3F), READC(3F), READIBM(3F), SKIPBAD(3F), WRITE(3F), WRITEC(3F)

104 004– 2165– 002

WRITMS ( 3F ) WRITMS ( 3F )

NAME
WRITMS, WRITDR – Writes to a random-access file on disk

SYNOPSIS
CALL WRITMS(dn, ubuff, n, irec, rrflag, s [,ierr])
CALL WRITDR(dn, ubuff, n, irec, rrflag, s [,ierr])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
WRITMS and WRITDR write data from user memory to a record in a random-access file on disk and update
the current index.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of arguments for this routine.
dn Type integer variable, expression, or constant with a maximum of 8 characters. dn is a unit
number or the name of the file as a Hollerith constant.
ubuff The location of the first word in the user program to be written to the record. User-specified
type. May not be a Fortran character variable.
n The number of words to be written to the record. Specify a type integer variable, expression, or
constant. n contiguous words from memory, beginning at ubuff, are written to the file record.
Because UNICOS unblocked-file I/O is in multiples of 512 words, it is recommended that n be a
multiple of 512 words when speed is important. However, the random access file I/O routines
support record lengths other than multiples of 512 words. WRITDR rounds n up to the next
multiple of 512 words, if necessary.
64
The maximum record size is 4,194,303 words for WRITMS and 2 /S words for WRITDR, where
S is the size of the DRIO file in words. There are 2 exceptions to this maximum record size for
WRITDR; the maximum record size is 4,193,792 words in the following cases:
• when STINDR has been used to select a non-default index array
• when the datafile being accessed was created by a program linked with CrayLibs releases
prior to CrayLibs 3.0
irec The record number or record name of the record to be written. Specify a type integer variable,
expression, or constant. A record name is limited to a maximum of 8 characters. For a
numbered index, irec must be between 1 and the length of the index declared in the
OPENMS/OPENDR(3) call. For a named index, irec is any 64-bit entity you specify.

004– 2165– 002 105

WRITMS ( 3F ) WRITMS ( 3F )

rrflag A flag indicating record rewrite control. Specify a type integer variable, expression, or constant.
rrflag can be one of the following codes:
0 Write the record at end-of-data (EOD).
1 If the record already exists, and the new record length is less than or equal to the old
record length, rewrite the record over the old record. If the new record length is greater
than the old, abort the program or return the error code in ierr. If the record does not
exist, the program aborts or the error code is returned in ierr.
-1 If the record exists, and its new length does not exceed the old length, write the record
over the old record; otherwise, write the record at EOD.
s A subindex flag. Specify a type integer variable, expression, or constant. (The implementation
of this parameter has been deferred.)
ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to
WRITMS/WRITDR, ierr returns any error codes to you. If ierr>0, no error messages are put into
the stderr file; otherwise, an error code is returned and the message is added to the stderr
file.
On return from WRITMS/WRITDR, ierr has one of the following values:
0 No errors or warnings detected.
<0 Error or warning condition detected. ierr contains one of the following error or warning
codes:
Error codes:
-1 The file name or unit number is not valid.
-6 The user-supplied named index is not valid.
-7 The named record index array is full.
-8 The index number is greater than the maximum on the file.
-9 Rewrite record exceeds the original.
-15 OPENMS/OPENDR was not called on this file.
-17 The index entry is less than or equal to 0 in the user’s index array.
-18 The user-supplied word count is less than or equal to 0.
-19 The user-supplied index number is less than or equal to 0.
-26 The user-requested record length exceeds the maximum allowed.
-27 The user-requested record length exceeds the maximum allowed for a file of this size.
Warning codes:
-21 The record size exceeds the buffer size for an asynchronous WRITMS request. The
WRITMS operation operated synchronously.

106 004– 2165– 002

WRITMS ( 3F ) WRITMS ( 3F )

NOTES
Most routines in the run-time libraries are reentrant or have internal locks to ensure that they are single
threaded. Some library routines, however, must be locked at the user level if they are used by more than
one task.
WRITMS and WRITDR are not internally locked. You must lock each call to these routines if they are called
from more than one task.
You cannot use the word-addressable I/O package on tape. An attempt to use a tape file causes an error
message to be written to stderr.
It is not valid to mix calls to MS/DR routines with standard Fortran I/O statements that use the same unit
number.

EXAMPLES
The following examples show some of the features and uses of random-access file routines.
Example 1: In the SORT program, a sequence of records is read in and then printed out as a sorted sequence
of records.
PRO GRA M SOR T
INT EGER IAR RAY (512)
INT EGE R IND EX (51 2), KEY S (100)
CALL OPE NMS (’SORT ’L,IND EX,255 ,1)
N=50
C READ IN RANDOM ACC ESS REC ORDS FRO M UNIT "SO RT"
DO 21 I=1 ,N
REA D(5,10 00) (IA RRAY(J ),J=1,512 )
NAM E=I ARR AY( 1)
KEY S(I )=I ARRAY( 1)
CALL WRI TMS (’SORT’L,IAR RAY,51 2,NAME ,0)
21 CON TIN UE
C SOR T KEY S ALPHAB ETICALLY IN ASCEND ING ORD ER USI NG
C EXC HANGE SOR T
DO 23 I=1,N- 1
MIN =I
J=I +1
DO 22 K=J ,N
IF (KEYS( K). LT.KEY S(MIN)) MIN=K
22 CON TIN UE
IB= KEYS(I )
KEY S(I)=K EYS(MI N)
KEY S(MIN) =IB
23 CON TIN UE
C WRI TE OUT RAN DOM ACC ESS REC ORDS IN ASCENDING
C ALP HABETI CAL ORD ER

004– 2165– 002 107

WRITMS ( 3F ) WRITMS ( 3F )

DO 24 I=1 ,N
NAM E=K EYS(I)
CALL READMS (’S ORT’L, IARRAY ,51 2,NAME )
WRI TE(6,5 120 ) (IA RRA Y(J),J =1, 512 )
24 CONTIN UE
1000 FORMAT (". ....." )
5120 FORMAT (1X ,".... .." )
CAL L CLO SMS (’SORT ’L)
STO P
END

In this example, the random-access file is initialized as shown in line 4. Lines 6 through 11 show that a
record is read from unit 5 into array IARRAY and then written as a record to the random-access file SORT.
The first word of each record is assumed to contain an 8-character name to be used as the name of the
record.
Lines 12 through 21 sort the names of the records in array KEYS. Lines 22 through 26 read in and then
print the records in alphabetical order.
Example 2: Programs INITIAL and UPDATE show how the random-access file might be updated without
the usual search and positioning of a sequential access file.
Program INITIAL:
PROGRA M INI TIAL
INT EGER IARRAY (512)
INT EGE R INDEX (51 2)
C
C OPE N RAN DOM ACC ESS DATASE T
C THIS INITIA LIZES THE REC ORD KEY "INDEX "
C
CALL OPE NMS (’MAST ER’ L,I NDE X,1 01,1)
C
C READ IN REC ORDS FROM UNI T 6 AND
C WRI TE THE M TO THE DATASE T "MA STE R"
C
DO 10 I=1,50
REA D(6 ,600) (IARRA Y(J ),J =1, 512)
NAM E=IARR AY(1)
CAL L WRI TMS (’MAST ER’ L,I ARR AY,512 ,NAME,0,0 )
CONTIN UE
C
C CLOSE "MA STER" AND SAV E REC ORDS FOR UPD ATI NG
C
10 CALL CLOSMS (’M AST ER’ L)
600 FOR MAT (1X,’. ... .’)

108 004– 2165– 002

WRITMS ( 3F ) WRITMS ( 3F )

STO P
END

Program UPDATE:
PROGRA M UPD ATE
INT EGE R INE WRCD(5 12)
INTEGE R IND X (51 2)
C
C OPE N RANDOM ACC ESS DAT ASET CREATE D IN THE
C PRE VIO US PRO GRAM "INITI AL"
C
C INDX WILL BE WRI TTE N OVE R THE OLD RECORD KEY
C
CAL L OPE NMS (’M AST ER’L,I NDX ,10 1,1)
C
C REA D IN NUMBER OF REC ORDS TO BE UPDATE D
C
5 REA D (6, 610) N
C
C REA D IN NEW RECORD S FRO M UNIT 6 AND
C WRITE THEM IN PLA CE OF THE OLD RECORD THAT HAS
C THAT NAME
C
DO 10 I=1 ,N
REA D(6,60 0) (IN EWR CD( J),J=1 ,51 2)
NAME=I NEWRCD (1)
CALL WRITMS (’M AST ER’ L,I NEWRCD ,51 2,NAME,1, 0)
10 CONTIN UE
C
C CLOSE "MASTE R" AND SAV E NEW LY UPD ATED REC ORDS
C FOR FUR THE R UPD ATING
C
CALL CLOSMS (’M AST ER’L)
600 FORMAT (1X ,"......" )
610 FORMAT (1X ,".... .." )
STOP
END

In the preceding example, program INITIAL creates a random-access file on unit MASTER; program
UPDATE then replaces particular records of this file without changing the remainder of the records.

004– 2165– 002 109

WRITMS ( 3F ) WRITMS ( 3F )

Line 10 shows that the call to CLOSMS(3F) at the end of INITIAL caused the contents of INDEX to be
written to the random-access file.
Line 4 shows that the call to OPENMS(3F) at the beginning of UPDATE has caused the record key of the
random-access file to be written to INDX. The random-access file and INDX are now the same as the
random-access file and INDEX at the end of INITIAL.
Lines 6 through 10 show that certain records are replaced.
Example 3: The program SNDYMS is an example of the use of the secondary index capability, using
STINDX(3F). In this example, dummy information is written to the random-access file.
PRO GRA M SNDYMS
IMP LICIT INTEGE R (A- Y)
DIMENS ION PINDEX (20 ),S IND EX(30) ,ZB UFF R(5 0)
DAT A PLE N,SLEN ,RL EN /20,30 ,50 /
C OPEN THE FIL E.
CALL OPENMS (1, PINDEX,PL EN, 0,E RR)
IF (ERR.N E.0) THEN
PRINT* ,’ Err or on OPE NMS, err=’, ERR
STOP 1
END IF
C LOOP OVER THE 20 PRI MARY INDICE S. EACH TIME
C A SECOND ARY IND EX IS FUL L, WRI TE THE
C SECOND ARY IND EX ARRAY TO THE DAT ASE T.
DO 40 K=1 ,PL EN
C ZER O OUT THE SEC OND ARY IND EX ARR AY.
DO 10 I=1 ,SLEN
10 SIN DEX(I) =0
C CALL STINDX TO CHANGE IND EX TO SINDEX .
CAL L STI NDX (1,SIN DEX,SL EN, 0,E RR)
IF (ER R.NE.0 ) THE N
PRINT* ,’ Err or on STI NDX, err=’, ERR
STOP 2
END IF
C WRI TE SLE N REC ORDS.
DO 30 J=1 ,SLEN
C GENERA TE A REC ORD LEN GTH BETWEE N 1 AND RLE N.
TRL EN= MAX0(I FIX(RA NF( 0)* FLO AT(RLE N)) ,1)
C FIL L THE "DA TA" ARR AY WIT H RAN DOM FLOATI NG POI NT
C NUM BERS.
DO 20 I=1 ,TR LEN
20 ZBU FFR (I)=(J +SIN(F LOA T(I ))) **(1.+ RAN F(0))
CAL L WRITMS (1,ZBU FFR ,TR LEN ,J,-1, DUM MY,ERR )
IF (ER R.N E.0) THEN
PRI NT*,’ Error on WRI TMS , err =’,ERR

110 004– 2165– 002

WRITMS ( 3F ) WRITMS ( 3F )

STO P 3
END IF
30 CON TIN UE
C "TO GGL E" THE IND EX BACK TO THE MAS TER AND
C WRITE THE SEC OND ARY INDEX TO THE DAT ASET.
CALL STINDX (1, PIN DEX ,PL EN, 0)
C NOT E THE ABO VE STI NDX CAL L DOE S NOT USE THE
C OPT ION AL ERR OR PAR AME TER , AND WIL L ABO RT
C IF STI NDX DETECT S AN ERR OR.
CALL WRITMS (1, SIN DEX ,SLEN, K,- 1,DUMM Y,ERR)
IF (ERR.N E.0) THE N
PRI NT*,’ Err or on STINDX , err =’, ERR
STO P 4
ENDIF
40 CONTIN UE
C CLO SE THE DATASE T.
CAL L CLO SMS (1,ERR)
IF (ER R.NE.0 ) THE N
PRI NT*,’ Err or on CLOSMS , err =’, ERR
STO P 5
ENDIF
STOP ’Norma l’
END

SEE ALSO
CLOSMS(3F), OPENMS(3F), STINDX(3F)

004– 2165– 002 111

112 004– 2165– 002
INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

NAME
INTRO_FFIO – Describes performance options available with the FFIO layers

IMPLEMENTATION
See individual man pages for implementation details.

DESCRIPTION
The Flexible File I/O (FFIO) system lets the user specify a comma-separated list of layers through which I/O
data is to be passed. This is done by providing a value for the spec argument to the -F option on the
assign(1) command. This specifies a class of processing to be done on the data.
The following C routines are used with FFIO:
• fffcntl(3C): performs functions on files opened using FFIO
• fflistio(3C): initiates a list of I/O requests using FFIO
• ffiolock(3C): locks and unlocks function calls
• ffopen(3C): opens or closes a file using FFIO
• ffpos(3C): positions files opened using FFIO
• ffread(3C): reads from a file using FFIO
• ffreada(3C): provides asynchronous read using FFIO
• ffseek(3C): repositions a FFIO file
• ffwritea(3C): provides asynchronous write using FFIO
• ffsetsp(3C): initiates EOV processing for files opened using FFIO
• ffwrite(3C): writes to a file using FFIO
FFIO on IRIX systems
The default layer for direct access on IRIX systems is the cache layer and it does not have the coherency
to handle multiple processes doing I/O to the same file. The user must assign the direct access file to either
the system or global layer for programs to work as expected with more than one process.
On IRIX systems, the FFIO library calls aio_sgi_init the first time it issues an asynchronous I/O call.
It passes the following parameters to aio_sgi_init:
aio _nu musers =MAX(6 4,s ysconf (_SC_NPRO C_C ONF))
aio_th reads= 5
aio_lo cks=3

If a program is using multiple threads and asychronous I/O, it is important that the value of
aio_numusers be at least as large as the number of sprocs and pthreads that the application contains. For
more information, see the aio_sgi_init man page on IRIX systems.

004– 2165– 002 113

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

Users can change these values by setting the following environment variables to the desired value:
• change FF_IO_AIO_THREADS to modify aio_threads
• change FF_IO_AIO_LOCKS to modify aio_locks
• change FF_IO_AIO_NUMUSERS to modify aio_numusers
The following example causes aio_threads to be set to 8 when the FFIO routines call aio_sgi_init:
setenv FF_ IO_AIO _TH READS 8

Users can also supersede the FFIO library’s call to aio_sgi_init by calling it themselves, before the first
I/O statement in their program.
The following layers can issue asynchronous I/O calls on IRIX systems:
• cos: see the later description on this man page for a description of how the cos layer uses asynchronous
I/O.
• cachea and bufa: users should assume that these layers may issue asynchronous I/O calls.
• system or syscall: these layers may issue asynchronous I/O calls if called from a BUFFER IN or
BUFFER OUT statement, or from the cos or cachea layer. The system and syscall layer may
also issue asynchronous I/O calls if called via ffreada(3C), ffwritea(3C), or fflistio(3C) (all
deferred on IRIX systems).
Specifying FFIO Layers
The spec argument of the -F option of the assign(1) command comprises a list of layers or filters that are
used to manipulate the data file as it is being read or written. The available layers include performance
options (such as memory-resident and SDS-resident files) and the capability to read and write files in a
variety of different vendors’ blocking formats. Each layer spec is of the general form:
class[.type[.subtype]][:num1]:[num2]:[num3]]
Many of the layers also allow you to specify the numeric parameters with a keyword. On UNICOS and
UNICOS/mk systems, this requires that your application be linked with Cray Research’s CrayLibs 3.0 or
later releases. The format for these specifications is given in the description of each layer where the
specification is available.
Selected layers are available on IRIX systems. The available platforms are detailed in each layer’s
description.
For more information about FFIO, see the Application Programmer’s I/O Guide.
The spec argument can have the following values:
Class Explanation
blankx or blx
Blank compression filter. This layer is used as a filter to compress or decompress blanks in
character data.
Not available on IRIX systems.

114 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

type can be one of the following:

cos COS-style blank compression (blxchr=27 or Ox10)
ctss CTSS-style blank compression (blxchr=48 or 0x30)
c205 CYBER 205-style blank compression (blxchr=48 or 0x30)
num1 is the decimal value of the ASCII character used as the escape code to control the
blank compression (usually ESC or 27). num2 is the decimal value of the ASCII character
that is the object of the compression (usually BLANK or 32).
You can specify the numeric parameters with this alternate keyword syntax:
blx[.type][.blxchr=num1][.blnk=num2]
blankx[.type][.blxchr=num1][.blnk=num2]
bmx Tape I/O. Each logical record requested is a physical tape block.
Deferred implementation on IRIX systems.
The num1 field represents the size of each buffer, in 4096-byte blocks. The num2 field
represents the number of buffers.
On UNICOS systems, files on ER90 volumes that have been mounted in blocked mode may
use this layer (see the Tape Subsystem User’s Guide, for information about restrictions on
record sizes when using ER90 block mode).
You can specify the numeric parameters with this alternate keyword syntax:
bmx[.bufsize=num1][.num_buffers=num2]
bufa Asynchronous buffering layer.
Available on IRIX systems.
The bufa layer provides asynchronous buffering. It allows efficient sequential-access I/O.
The num1 field represents the size in 4096-byte blocks of each buffer. The maximum value
for num1 on IRIX systems is 32,767. The maximum allowed value on UNICOS and
UNICOS/mk systems is 1,073,741,823 (you may not be able to use a value of this size
because that amount of memory may not be available).
The num2 field selects the number of buffers to be used.
You can specify the numeric parameters with this alternate keyword syntax:
bufa[.bufsize=num1][.num_buffers=num2]
c205 CDC CYBER 205/ETA records.
Not available on IRIX systems.

004– 2165– 002 115

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

The CYBER 205-type W record can be selected by specifying c205.w. The num1 field is
not permitted. The num2 field represents the size of the working buffer, in bytes, used in
record blocking. If any logical records written exceed this size, a major performance
penalty can result.
The type field should be specified as w. The best performance is currently obtained when
num2 is greater than the largest record to be processed plus 16 bytes.
You can specify the numeric parameters with this alternate keyword syntax:
c205[.w][.bufsize=num2]
cache Cached file. The cache layer allows efficient random-access I/O, even when file access is
clustered in several regions of a file.
Available on IRIX systems.
During reads and writes to the layer, cache buffers frequently must be preempted. The
buffer chosen for preemption is always the least recently accessed buffer at the time of
preemption.
The options available are .mem, which specifies that buffers reside in memory or .sds,
which specifies that buffers reside in the SDS. (.sds is not supported on Cray T3E
systems or IRIX systems). Memory-resident buffers are the default.
The numeric fields are as follows:
• num1 is the size in 4096-byte blocks of each cache page. The maximum value for num1
on IRIX systems is 32,767. The maximum allowed value on UNICOS and UNICOS/mk
systems is 1,073,741,823 (you may not be able to use a value of this size because that
amount of memory may not be available).
• num2 selects the number of cache pages to be used.
• num3 is the size in 4096-byte blocks at which the cache layer attempts to bypass
cache layer buffering. If a user’s I/O request is larger than num3, the request might
not be copied to a cache page. The default on IRIX systems is num3=num1. The
default on UNICOS and UNICOS/mk systems is num3=num1*num2.
You can specify the numeric parameters with this alternate keyword syntax:
cache[.type][.page_size=num1][.num_pages=num2]
[.bypass_size=num3]
cachea Asynchronously cached file.
Available on IRIX systems.
This type of processing usually performs well whenever the cache layer might be used.
In addition, any sequential forward and sequential backward access through the file is
detected. When sequential access patterns are detected while reading, asynchronous
read-ahead is performed provided that the numbers of pages to read ahead has been
specified. When writing, selective asynchronous write-behind is performed.

116 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

The values for type are .mem, which specifies that buffers reside in memory, or .sds,
which specifies that buffers reside in the SDS (.sds is not supported on Cray T3E systems
or on IRIX systems). Memory-resident buffers are the default.
The numeric fields are as follows:
• num1 is the size in 4096-byte blocks of each cache page. The maximum value for num1
on IRIX systems is 32,767. The maximum allowed value on UNICOS and UNICOS/mk
systems is 1,073,741,823 (you may not be able to use a value of this size because that
amount of memory may not be available).
• num2 selects the number of cache pages to be used.
• num3 selects the number of pages to read ahead asynchronously. The default is 0.
• num4 selects a shared cache number in the range of 1 to 15. If num4 is 0, a private
cache is indicated.
You can specify the numeric parameters with this alternate keyword syntax:
cachea[.type][.page_size=num1][.num_pages=num2]
[.max_lead=num3][.shared_cache=num4]
On IRIX systems, stacked shared cachea layers are not supported.
On UNICOS and UNICOS/mk systems, stacked shared cachea layers are supported, but
in multitasked programs, different files must not mix the order of the shared caches.
Examples:
The following specifications cannot both be used by a multitasked program:
• assign -F cachea::::1,cachea::::2 u:1
• assign -F cachea::::2,cachea::::1 u:2
The following specifications can both be used by a multitasked program on a UNICOS
system:
• assign -F cachea::::1,cachea::::2 u:1
• assign -F cachea::::1,cachea::::2 u:2
cdc CDC 60-bit format type.
Not available on IRIX systems.
No numeric fields are accepted.
The supported values for type are as follows:
type Format
iw I-type blocks, W-type records
cw C-type blocks, W-type records

004– 2165– 002 117

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

cs C-type blocks, S-type records

cz C-type blocks, Z-type records
The subtype field accepts one of the following values that indicate the presence of block
trailers and other low-level characteristics:
subtype Value
disk Disk type structure, for use with station transfers of CYBER datasets
i NOS internal tape format
si System internal or SCOPE internal tape format
cos or blocked
COS blocking.
Available on IRIX systems.
If specified, type must be one of the following:
type Action
sync Uses a single buffer in the blocking and deblocking process. I/O is done
strictly synchronously.
async Divides the buffer into two parts and uses asynchronous I/O to transfer the
blocked data between the buffer(s) and the logical device. When reading,
asynchronous read-ahead is performed, and when writing, asynchronous
write-behind is performed. To effectively use async, the buffer size should
be at least twice the record length.
auto Default (if type is not specified). Chooses either synchronous or asynchronous
behavior depending on the buffer size. If the buffer size is less than 64
blocks, synchronous behavior is selected. If it is greater than or equal to 64
blocks, asynchronous behavior is selected.
For num1, enter the desired buffer size in 4096-byte blocks (for example, -F cos:42
requests COS blocking and a 42-block buffer). The num1 value also determines the record
size for underlying layers which perform record blocking. The underlying record size is
num1 blocks if in synchronous mode and num1/2 or num1/2+1 blocks if in asynchronous
mode. For an underlying tape layer, the record size is the tape block size.
MIPSpro 7.3/PE 3.3 release: If not specified, the default buffer size is the larger of the
following: the large I/O size (UNICOS and UNICOS/mk systems only), the preferred I/O
block size (see the stat(2) man page), or 48 blocks. Furthermore, if type is auto (the
default), then the default buffer size is doubled if asynchronous mode is used (the cos
layer automatically switches to asynchronous mode).
You can specify the numeric parameters with this alternate keyword syntax:
cos[.type][.bufsize=num1]

118 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

er90 ER90 I/O.

Not available on IRIX systems or on Cray T3E systems.
Each I/O operation results in a corresponding system call. Adjacent records are not
delimited from one another. No subfields are accepted. The byte-stream mode of the
device must be used. See tpmnt(1).
event I/O layer monitoring.
Available on IRIX systems.
The event layer monitors I/O occurring between two layers on a per-file basis. This layer
generates statistics in an ASCII log file; users can specify what type of report is generated.
The event layer is enabled by default. Users do not have to relink their programs to
study I/O performance. To generate information, rerun the program with the event layer
specified on the assign command.
Statistics are reported to stderr by default. The FF_IO_LOGFILE environment variable
can be used to name a file to which statistics are written by the event layer. The default
action is to overwrite the existing file. To append information to an existing file, specify a
plus sign (+) before the file name.
The event layer reports counts for read, read, write, and writea. These counts
represent the number of calls made to to an FFIO layer entry point. In some cases, the
system layer may actually use a different I/O system call, or multiple system calls. For
example, the reada system call does not exist on IRIX systems, and the system layer
reada entry point will use aio_read().
On IRIX systems, the report that is generated may include mention of the "lock" layer, even
though the lock layer may not have been specified by the user.
On Cray T3E systems, if more than one process is using the event layer, and you set the
FF_IO_LOGFILE environment variable, you must use the plus sign (+) before the file
name to prevent process a from overwriting the information written by process b. Using
the plus sign also means that the information will be appended to an existing file.
On Cray T3E systems you can also use the FF_IO_LOGFILEPE environment variable to
name a file to which statistics are written. The file name will be x.n, where x is the name
specified by the environment variable and n is the number of the PE which wrote the file.
The default action is to overwrite the existing file. To append information to the existing
file, specify a plus sign (+) before the file name.
Enter one of the following for type:
value Information reported
nostat No statistical information is reported.
summary Information on event types that occur at least once are reported.
brief A one-line summary for layer activities is reported.

004– 2165– 002 119

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

f77 FORTRAN 77/UNIX Fortran record blocking. This is the common blocking format used
by most FORTRAN 77 compilers on UNIX systems.
Available on IRIX systems.
Enter one of the following for type:
type Format
nonvax Default. Control words in a format common to machines such as the
MC68000.
vax VAX format (byte-swapped) control words. Not available on IRIX systems.
The specification of vax or nonvax is not relevant to data conversion.
For num1, enter the maximum record size in bytes. For num2, enter the working buffer
size, in bytes.
You can specify the numeric parameters with this alternate keyword syntax:
f77[.type][.recsize=num1][.bufsize=num2]
fd Connect to a specific file descriptor.
Available on IRIX systems.
Field num1 is the decimal value of the file descriptor. Classes named stdin, stdout,
and stderr exist as alternate names for fd:0, fd:1, and fd:2.
You can specify the numeric parameters with this alternate keyword syntax:
fd[.file_descriptor=num1]
global File global to all processes.
Available on IRIX systems.
This is a caching layer which distributes the cache across multiple SHMEM or MPI
processes. Open and close operations are collective (require participation by all processes
which access the file). All other operations are independently performed by one or more
processes. The library allows multiple processes to concurrently access the file while
maintaining coherency of buffered data.
Specify one of the following options for type:
type Description
privpos Default. The file position is private to a process. All processes may seek
to independent locations in the file.
globpos (Deferred). The file position is global to all processes. A seek or I/O
operation by any process will affect the position for all processes.
The numeric fields are as follows:
num1 The size in 4096-byte blocks of each cache page.

120 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

num2 Selects the number of cache pages to be used on each process. If there are n
processes, then n . num2 cache pages are used.
num2 buffer pages are allocated on every process which shares access to a global file. File
pages are direct-mapped onto processes such that page n of the file will always be cached
on process (n mod NPES), where NPES is the total number of processes sharing access to
the global file. Once the process is identified where caching of the file page will occur, a
least-recently-used method is used to assign the file page to a cache page within the caching
process.
You can specify the numeric parameters with this alternate keyword syntax:
global[.type][.page_size=num1][.num_pages=num2]
ibm Record blocking for common record types on IBM operating systems.
Deferred implementation on IRIX systems.
Specify one of the following record formats for type:
type Format
f Fixed-length record format. For num1, enter the logical record size in 8-bit bytes.
For num2, enter the maximum physical block size in 8-bit bytes; if specified, num2
must be equal to num1.
fb Fixed-length, blocked record format. For num1, enter the logical record size in
8-bit bytes. For num2, enter the maximum physical block size in 8-bit bytes; num2
must be an exact multiple of num1.
u Undefined record format. For num1, enter the maximum record size, in 8-bit bytes.
v Variable length record format. For num1, enter the maximum logical record size in
8-bit bytes. For num2, enter the maximum physical block size in 8-bit bytes.
vb Variable length blocked record format. For num1, enter the maximum logical
record size in 8-bit bytes. For num2, enter the maximum physical block size in
8-bit bytes.
vbs Variable length blocked, spanned record format. For num1, enter the maximum
logical record size in 8-bit bytes. For num2, enter the maximum physical block
size in 8-bit bytes.
No subtype is accepted for the ibm class record formats. num1 does not need to be smaller
than num2.
You can specify the numeric parameters with this alternate keyword syntax:
ibm[.type][.recsize=num1][.mbs=num2]
mr or sds Memory-resident and SDS-resident files. mr is a deferred implementation on IRIX systems.
sds is not available on Cray T3E systems or on IRIX systems.

004– 2165– 002 121

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

The mr and sds layers let you declare a byte-stream file, but the given file should reside in
the specified medium as much as possible; this can improve performance.
Enter one of the following for type:
type Load Specification
save Default. Loads the file into the specified medium when the file is opened and
writes the data back out when closed.
scr Scratch file. Does not attempt to load at open and discards data on close.
Enter one of the following for subtype:
subtype Overflow Specification
ovfl Default. Writes excess data that does not fit in the specified medium to the
next lower layer.
novfl If data does not fit in the specified medium, subsequent write(1) operations
fail.
The mr and sds layers accept numeric fields. Generally, the numeric field specification
represents best-efforts values. They are used for tuning purposes and usually do not cause
errors if they are not satisfied precisely as specified. The fields are as follows:
Field Value
num1 Initial size of the memory or SDS allocation. Specified in 4096-byte blocks.
Default is 0.
num2 Maximum size of the memory or SDS allocation. Specified in 4096-byte blocks.
46
Default is s -1.
num3 Increment size of the memory or SDS allocation. Specified in 4096-byte blocks.
This value is used when allocating additional memory or SDS space. The
default is 256 for SDS files and 32 for memory resident files.
For example, if the SDS limit for a process is 1000 blocks, and sds.scr:1500 is
specified, an initial SDS allocation of 1000 blocks is used.
Similarly, if sds:500:10000:1000 was specified, the first request for SDS space would
result in the allocation of 500 blocks. If possible, this is allocated contiguously, but it is
not guaranteed. If a file size exceeds 500 blocks, an attempt is made to increase the file by
an increment of 1000 blocks. If this attempt fails, whatever can be allocated is given to the
file. Assuming no other SDS use, this is 500 blocks. At this point, the file assumes an
overflow status.

122 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

When using memory-resident files, you must ensure that not too much data is written to the
file without limiting its size. Unrestrained and unmanaged growth of such a file can cause
heap fragmentation and program abort. If this growth has used all available memory, the
error message processor may be unable to issue a message. Therefore, such an abort may
be difficult to diagnose and correct. It is recommended that the maximum memory size
field be specified in all cases. (For example, mr.scr::10000 would limit such a file to
approximately 5 Mwords of main memory.)
You can specify the numeric parameters with this alternate keyword syntax:
mr[.type[.subtype]][.start_size=num1] [.max_size=num2]
[.inc_size=num3]
sds[.type[.subtype]][.start_size=num1] [.max_size=num2]
[.inc_size=num3]
null Syntactic no-op.
Available on IRIX systems.
No optional fields are accepted. null may be specified where syntax demands a value, but
no function is desired. This does not perform the same function as /dev/null.
nosve CDC NOS/VE record formats.
Not available on IRIX systems.
The following values are allowed for the type and num fields:
type Value
d ANSI D format (variable-length) records. For num1, enter the maximum logical
record size in 8-bit bytes. For num2, enter the maximum physical block size in
8-bit bytes.
f ANSI F fixed-length records. For num1, enter the logical record size in 8-bit
bytes. For num2, enter the maximum physical block size in 8-bit bytes; num2
must be an exact multiple of num1.
s ANSI S format (segmented) records. For num1, enter the maximum logical
record size. For num2, enter the maximum physical block size used in the
lower-level layers.
u Undefined records. For num1, enter the maximum logical record size, in 8-bit
bytes. For num2, enter the maximum physical block size in 8-bit bytes.
v NOS/VE V format records. The num1 field is not permitted. For num2, specify
the size of the working buffer used in record blocking; if any logical records that
are written exceed this size, a major performance penalty can result.
You can specify the numeric parameters with this alternate keyword syntax (as noted
previously, .recsize may not be permitted for some types):

004– 2165– 002 123

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

nosve[.type][.recsize=num1][.mbs=num2]
site Site layer. This option lets a site add custom I/O handlers for specific needs at load time.
See the Application Programmer’s I/O Guide, for details.
Available on IRIX systems.
stdin, stdout, or stderr
Connects to specific file descriptors 0, 1, and 2, respectively. (See the fd class.)
system Generic system I/O layer. Selects bmx, er90, or syscall as appropriate.
Available on IRIX systems.
syscall System I/O call. Each I/O operation results in a corresponding system call.
Available on IRIX systems.
This layer does not accept any options on UNICOS or UNICOS/mk systems. On IRIX
systems, it has one optional parameter as follows:
syscall[.cboption]
The cbption can be one of the following values:
aiocb The syscall layer is notified, via a signal, when the asynchronous I/O
completes.
noaiocb The syscall layer polls the completion status word to determine
asynchronous I/O completion. This is the default value.
tape Tape I/O. Each logical record requested is a physical tape block. This is the same as bmx.
Deferred implementation on IRIX systems. For information about the tmf layer on IRIX
systems, see the IRIX TMF User’s Guide, 007-3969-001.
The num1 field represents the size of each buffer, in 4096-byte blocks. The num2 field
represents the number of buffers.
You can specify the numeric parameters with this alternate keyword syntax:
tape[.bufsize=num1][.num_buffers=num2]
text Special character terminated records.
Available on IRIX systems.
Enter one of the following for type:
type Format
nl Newline-separated records
eof Newline-separated records and the special character sequence ~e on a line by
itself delimiting EOF
205 CYBER 205-style text file

124 004– 2165– 002

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

ctss CTSS-style text format

This class accepts num specifications. If specified, num1 represents the decimal value of the
ASCII character to use to delimit records; the default varies depending on the type. For
num2, enter the requested working buffer size in bytes.
You can specify the numeric parameters with this alternate keyword syntax:
text[.type][.newline=num1][.bufsize=num2]
user User layer. This option allows a user to add custom I/O handlers for specific needs at load
time. See the Application Programmer’s I/O Guide, for details.
Available on IRIX systems.
vms Provides record blocking for common record types on VMS/MS operating systems.
For type, enter one of the following record formats:
type Format
f Fixed-length records
v Variable length records
s Segmented variable records
Each type accepts the following subtypes to specify the blocking format within the record
type:
subtype Format
tape ANSI standard record format. This subtype should be used with labeled
VAX/VMS tapes.
bb Binary blocked format. This subtype should be used with files that are to be
fetched or disposed with a BB or TB format, or with unlabeled magnetic tapes.
This subtype requires an enclosing blocking; for example, vms.s.bb,bmx or
vms.s.bb,cos.
tr Transparent format. This subtype should be used with files that are transferred
between the VAX/VMS system by using fetch or dispose
(UNICOS/UNICOS/mk commands) and the TR format. Any other method that
precisely transfers the disk image, including all VMS control words, will also
work. Note that ftp does not correctly transfer nontext, variable-length record
files.
This class accepts num1 and num2 fields; they have a similar meaning to ibm class. For
type s, num1 is ignored. For type f, num2 need not be a multiple of num1.
You can specify the numeric parameters with this alternate keyword syntax:
vms[.type][.subtype][.recsize=num1][.mbs=num2]

004– 2165– 002 125

INTRO_FFIO ( 3F ) INTRO_FFIO ( 3F )

EXAMPLES
The following are example FFIO specifications.
Example 1: The following example specifies FORTRAN 77/UNICOS Fortran blocking with a working
buffer of 128,000 bytes to allow efficient creation of logical records up to 127,992 bytes:
f77::1 28000

Example 2: The following example specifies IBM VBS records with a block size of 16,384 bytes:
ibm .vbs:: 16384

Example 3: The following example specifies a memory-resident layer with an initial memory size of 100
4096-byte blocks:
mr:100

Example 4: The following example specifies VMS V records with a maximum record size of 1000 bytes:
vms.v. tr:100 0

Example 5: The following example specifies the SS-resident layer that loads from disk on open and saves to
disk on close, does not allow overflow, has an initial size of 10 4096-byte blocks in SDS, grows to a
maximum size of 559 blocks in minimum increments of 37 blocks:
sds.sa ve.nov fl:10: 559:37

See the Application Programmer’s I/O Guide, for more detailed information about FFIO specifications.

NOTES
Some FFIO specification requirements are not obvious. For example, CYBER 205 R-type records must be
requested with blx.ctss,text.205.
The Fortran I/O library checks for conflicting attributes when file name and unit attributes are both present
during OPEN processing for a Fortran unit. The existence of an assign attribute for both the file and the unit
results in an error condition.

SEE ALSO
Application Programmer’s I/O Guide
acptbad(3F), assign(3F), ffopen(3C), openms(3F), opendr (see openms(3F)), skipbad(3F)
df(1), ln(1), setf(1), tpmnt(1), write(1)
asgcmd(1), assign(1)
ialloc(2), open(2)
SDSALLOC(3F)

126 004– 2165– 002

FFASSIGN ( 3C ) FFASSIGN ( 3C )

NAME
ffassign – Provides library interface to assign processing

SYNOPSIS
#include <ffio.h>
int ffassign(char *cmd);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
This routine is supported on IRIX systems for programs compiled with the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
ffassign provides an interface to assign processing from C.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk
systems, the default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems, the
default kind is KIND=4.
This routine has one argument:
cmd A string containing a complete assign(1) command in the format also acceptable to system(3C).
The -V option cannot be processed by the ffassign routine.

RETURN VALUES
Zero is returned on success, and -1 is returned when an error is detected. errno is set to the error number
when an error condition occurs.

EXAMPLES
The following is equivalent to assign -s unblocked f:file:
ret = ffa ssi gn("as sign -s unb loc ked f:f ile");

SEE ALSO
assign(1)
INTRO_FFIO(3F)

004– 2165– 002 127

FFFCNTL ( 3C ) FFFCNTL ( 3C )

NAME
fffcntl – Performs functions on files opened using flexible file I/O

SYNOPSIS
#include <ffio.h>
UNICOS and UNICOS/mk systems:
int fffcntl (int fd, int cmd, [,long *arg, struct ffsw *stat]);
IRIX systems:
int fffcntl (int fd, int cmd, void *arg, struct ffsw *stat);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The fffcntl function performs a variety of functions on files opened by ffopen or ffopens, using
flexible file I/O (FFIO). Arguments are as follows:
fd Number returned by function ffopen or ffopens.
cmd Specifies values defined in header file ffio.h. See under the next heading, VALUES FOR cmd
ARGUMENT.
arg The type and value of arg is cmd specific. See preceding descriptions.
stat Pointer to the status return structure.
Values for cmd Argument
The following values can be used for the cmd argument introduced above:
FC_ACPTBAD
Accepts bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90
files on UNICOS systems.) arg is a pointer to structure ffc_baddata_s, defined in header file
ffio.h. This cmd is valid with the tape FFIO layer. The fields of this structure have the
following meaning:
ffc_bytes Number of bytes of bad data transferred is returned in this field.
ffc_maxflag Set this value to 1 if a maximum value is specified in field ffc_maxwords. Set
this value to 0 if no maximum value is specified.
ffc_maxwords Maximum number of words of bad data to transfer to user’s data area. If the
number of words of bad data in the block exceed this value, the excess is
discarded.

128 004– 2165– 002

FFFCNTL ( 3C ) FFFCNTL ( 3C )

ffc_termcnd Position after accepting bad data is shown in this field, as follows: 0 indicates
end of block; 1 indicates EOF; 2 indicates EOD; and a value less than 0 indicates
that an error occurred. The absolute value is the error number.
ffc_uda User data area to receive bad data.
FC_ASPOLL
Checks for completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of
type struct ffsw, which had previously been passed to an asynchronous FFIO request. The
purpose of this call is to pass control to the underlying layers to do intermediate processing or
cleanup on the request. If the request is complete, fields in the status return structure are set as
described under function ffreada(3C).
FC_CHECKTP
Checks tape position. This value is valid only for online tape files on UNICOS and UNICOS/mk
systems and ER90 files on UNICOS systems. arg is a pointer to structure ffc_chktp_s, defined
in header file ffio.h. This command is valid with the tape FFIO layer. The fields of this
structure have the following meaning:
stat The status of the tape, as follows:
– 1 = No status
0 = At EOV
1 = Tape off reel
2 = Tape mark detected
3 = Blank tape detected
The remaining fields are unused.
FC_ENDSP
Ends special processing. This value is valid only for online tape files on UNICOS and UNICOS/mk
systems and ER90 files on UNICOS systems. arg is unused. This function removes the alternate
path to tape created by FC_STARTSP. Tape blocks that were held aside are written to tape. This
cmd is valid with the tape FFIO layer.
FC_CLOSEV
Closes volume and mounts next volume in the Volume Identifier list. arg is unused. This value is
valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS
systems. The er90 layer is not supported on Cray T3E systems. This cmd is valid with the
following FFIO layers: tape, er90, bufa.
FC_GETTP
Retrieves information about an opened tape file (valid only for online tape files on UNICOS and
UNICOS/mk systems and ER90 files on UNICOS systems. arg is a pointer to structure
ffc_gettp_s, defined in header file ffio.h.
The er90 layer does not guarantee that records correspond to physical tape blocks. See the
assign(1) man page and the Tape Subsystem User’s Guide for more information about the er90
FFIO layer.

004– 2165– 002 129

FFFCNTL ( 3C ) FFFCNTL ( 3C )

The fields of this structure have the following meaning:

ffc_glen Number of words to copy to the array pointed to by field ffc_pa.
ffc_synch Synchronization value, as follows: a value of 1 indicates to synchronize the dataset
before obtaining position information; a value of 0 means do not synchronize the
dataset. This field is ignored if the last operation was a read. It is also invalid to
specify this value if end-of-volume (EOV) processing is enabled, and the user has
reached EOV but has not started special processing.
ffc_pa Address of array that will contain information returned by this function. The values
returned in this array are as follows:
ffc_pa[0] Current volume identifier.
ffc_pa[1] – ffc_pa[6]
Characters 1– 48 of the path name of the file opened to this tape.
ffc_pa[7] Integer file section number.
ffc_pa[8] Integer file sequence number.
ffc_pa[9] Integer block number relative to tape mark specified in ffc_pa[22].
ffc_pa[10] Integer number of blocks in the library buffer. If additional processing layers have
been specified with assign(1) or asgcmd(1), those layers may also hold buffered
data, but they will not be included in this field.
ffc_pa[11] Integer number of blocks in the IOP or system buffer.
ffc_pa[12] Integer device ID or unit number.
ffc_pa[13] Device identifier or name.
ffc_pa[14] Generic device name.
ffc_pa[15] Last device function.
ffc_pa[16] Last device status.
ffc_pa[17] Data transfer count in bytes.
ffc_pa[18] Buffer memory sector count.
ffc_pa[19] Partial block bytes in buffer memory.
ffc_pa[20] Outstanding sector count.
ffc_pa[21] Outstanding block count.
ffc_pa[22] User tape mark number, including tape marks embedded in the data.
ffc_pa[23] Direction from tape mark in previous word: 0 = after tape mark; 1 = before tape
mark.
ffc_pa[24] Today’s year modulus 100.

130 004– 2165– 002

FFFCNTL ( 3C ) FFFCNTL ( 3C )

ffc_pa[25] Today’s Julian day.

ffc_pa[26] File identifier, up to the first 8 characters.
ffc_pa[27] Record format name.
ffc_pa[28] Tape density: 1 = 1600 bpi; 2 = 6250 bpi.
ffc_pa[29] Maximum block size.
ffc_pa[30] Record length.
ffc_pa[31] File status: 1 = new; 2 = old; 3 = append.
ffc_pa[32] Label type: 1 = no label; 2 = ANSI label; 3 = IBM standard label; 4 = bypass label.
ffc_pa[33] Integer file sequence number of first file on volume.
ffc_pa[34] Ring status: 0 = ring out; 1 = ring in.
ffc_pa[35] Expiration year modulus 100.
ffc_pa[36] Expiration Julian day.
ffc_pa[37] First volume identifier of file.
ffc_pa[38] User end-of-volume status: 0 = EOV processing off; 1 = EOV processing on.
ffc_pa[39] User end-of-volume processing status: 0 = not in active EOV processing; 1 = in
active EOV processing.
ffc_pa[40] User read/write tape mark status: 0 = user read/write tape mark not allowed;
1 = user read/write tape mark is allowed.
ffc_pa[41] Block attribute: ’B’ = blocked records; ’S’ = spanned records, if the record format
is ’V’, or standard records, if the record format is ’F’; ’R’ = blocked and spanned
records, if the record format is ’V’, blocked and standard records, if the record
format is ’F’; ’0’ = none of the previous values.
ffc_pa[42] – ffc_pa[47]
File identifier.
FC_GETINFO
Gets information about the layers connected to this open file. arg is a pointer to structure
ffc_info_s. The information returned in this structure is as follows:
ffc_flags
Flag word containing attributes of the file/connection. These bit masks are defined in header
file ffio.h and are set if true, as follows:
FFC_STRM Can handle stream I/O.
FFC_REC Can handle records.
FFC_WEOF Can represent EOF.
FFC_WEOD Can represent EOD (always set).

004– 2165– 002 131

FFFCNTL ( 3C ) FFFCNTL ( 3C )

FFC_BKSP Can handle backspace.

FFC_BKFIL Can handle backfile.
FFC_SEEKA Can seek absolute.
FFC_SEEKR Can seek relative.
FFC_SEEKE Can seek to end.
FFC_POSREC Can position by record number.
FFC_POSFIL Can position by EOF mark.
FFC_RWND Can rewind by seek(x,0,0).
FFC_FIXD Can do fixed-length records.
FFC_VAR Can do variable-length records.
FFC_BINARY Can do binary data.
FFC_CODED Can do formatted (character) data.
FFC_RDM Can do random I/O (no truncation).
FFC_SEQ Can do sequential I/O.
FFC_ASYNC Can do asynchronous I/O. (All layers have asynchronous entry points, but
this bit tells whether the behavior is actually async.)
FFC_WRTRUNC Write implies truncation.
FFC_NOTRN Does no transformation on data; no control words are added or subtracted.
Data is not changed.
ffc_gran
Minimum granularity. This is the smallest size in bits of a valid data transfer. For example,
the system call layer has an ffc_gran of 8, as it can handle a byte as its smallest unit of
data transfer. Some CDC record formats have a granularity of 60.
ffc_reclen
Valid only for fixed length records. This is the record length in bits.
ffc_fd
Lowest level file descriptor for the layer that makes system calls. This is not always
available, or may not be meaningful for some layers or combinations of layers. This is - 1 if
no descriptor is available.
FC_GETLK
Performs an fcntl call with cmd F_GETLK. arg is a pointer to structure flock (defined in
sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and
system layers, and not for tapes or ER90 devices.

132 004– 2165– 002

FFFCNTL ( 3C ) FFFCNTL ( 3C )

FC_GETLKW
Performs an fcntl call with cmd F_GETLKW. arg is a pointer to structure flock (defined in
sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and
system layers, and not for tapes or ER90 devices.
FC_IALLOC
Performs an ialloc system call. Supported only on UNICOS and UNICOS/mk architectures and
only by the syscall and system layers. Not supported for tapes or ER90 devices. arg is a
pointer to structure ff_ialloc_struct, defined in the ffio.h file. The ialloc call is made
using the following parameters:
• The ia_nb element of the structure is the second argument
• The ia_flag element of the structure is the third argument
• The ia_part element of the structure is the fourth argument
• The ia_avl element of the structure is the fifth argument
FC_RECALL
Awaits completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of
type struct ffsw, which is the status return structure of the asynchronous request. Function
fffcntl waits for completion of the asynchronous request, if necessary. Fields in the status return
structure are set as described under function ffreada(3C).
FC_SCRATCH
Specifies that a file is to be deleted at close time. The arg argument is a pointer to int. On exit,
*arg is set to contain zero or more of the following result bits:
SCR_NOFLUSH Set if ffclose processing has been optimized to suppress buffer flushing.
SCR_SINGLELINK Set if the file is not a pipe or a tty, has a link count equal to one, and is not a
symbolicly linked file.
SCR_UNLINKED Set if this fffcntl call has successfully unlinked the file.
FC_SETLK
Performs an fcntl call with cmd F_SETLK. arg is a pointer to structure flock (defined in
sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and
system layers, and not for tapes or ER90 devices.
FC_SKIPBAD
Skips bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files
on UNICOS systems. arg is a pointer to structure ffc_baddata_s, defined in header file
ffio.h. This cmd is valid with the tape FFIO layer. The fields of this structure used by
FC_SKIPBAD are as follows; all other fields are unused:
ffc_blocks The number of blocks skipped is returned in this field.

004– 2165– 002 133

FFFCNTL ( 3C ) FFFCNTL ( 3C )

ffc_termcnd Position after skipping bad data is returned in this field, as follows: 0 indicates end
of block; 1 indicates EOF or EOD; and a value less than 0 indicates that an error
occurred. The absolute value is the error number.
FC_STAT
Returns a structure much like the one returned by the fstat (see stat(2)) system call. arg is a
pointer to a ffc_stat_s structure (from ffio.h). Fields in this structure are filled in as
appropriate by the layers. For the system call layer, all fields are simply retrieved by doing an
fstat call. For other layers, such as mr, the size field in the stat structure is modified to reflect
the buffered data. Other layers can make similar changes to the basic information from the system
for similar reasons. The result is a stat structure that can be used in the same way and for the
same purposes as the fstat system call.
FC_SETSP
Disables special EOV processing. This value is valid only for online tape files on UNICOS and
UNICOS/mk systems and ER90 files on UNICOS systems. arg is an integer value that should be set
to 0. See ffsetsp(3C) for a description of how to enable special EOV processing. This cmd is
valid with the tape FFIO layers.
FC_STARTSP
Starts special EOV processing. This value is valid only for online tape files on UNICOS and
UNICOS/mk systems and ER90 files on UNICOS systems. arg is unused. EOV processing must be
enabled prior to starting special EOV processing. This function creates an alternative path to or from
a tape. Tape blocks in the pipeline are held aside. Subsequent write operations will go directly to
tape; subsequent read operations will come directly from tape (if data is available) or from the blocks
in the pipeline. Both read and write operations are performed in FIFO order. After you have read
from the blocks in the pipeline, they are unavailable for writing. This cmd is valid with the
following tape FFIO layer.
FC_TPC_SDBSZ
Changes the data block size on an ER90 device. This is valid only when using the tape layer. arg
is the requested new block size. This cmd has no effect when it is used with an IBM-compatible
tape.
Not supported on IRIX systems.
FC_TSYNC
(Valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS
systems. It requests that the tape file be synchronized. This command is ignored if the last operation
was a read. It is also invalid to request synchronization if the end-of-volume (EOV) processing is
enabled, and the user has reached EOV but has not started special processing. If the end-of-volume
processing is enabled, the user should check to see if EOV was reached after requesting FC_TSYNC
(see the description for FC_CHECKTP). In this case, the fffcntl returns without error, but the tape
may not be synchronized (that is, data may remain buffered). This cmd is valid with the following
FFIO layers: tape, er90, bufa.
The er90 layer is not supported on Cray T3E systems.

134 004– 2165– 002

FFFCNTL ( 3C ) FFFCNTL ( 3C )

RETURN VALUES
The fffcntl function returns 0 on success. Otherwise, it returns -1 and the sw_error field of the stat
structure contains the error number.

SEE ALSO
fflistio(3C) ffopen(3C), ffreada(3C), ffsetsp(3C), ffwritea(3C)
assign(1), asgcmd(1)
Tape Subsystem User’s Guide, for more information about the er90 FFIO layer

004– 2165– 002 135

FFIOLOCK ( 3C ) FFIOLOCK ( 3C )

NAME
ffiolock, ffiounlock – Provide locking for FFIO functions

SYNOPSIS
#include <ffio.h>
int ffiolock (int fd, struct ffsw *stat);
int ffiounlock (int fd [, struct ffsw *stat]);

IMPLEMENTATION
UNICOS systems

DESCRIPTION
The ffiolock and ffiounlock functions provide a way of locking a group of Flexible File I/O (FFIO)
function calls that use the same fd. The ffiolock function sets a lock; any other task that issues an FFIO
call with the same fd will wait until the lock is released. Function ffiounlock releases the lock.
The following arguments are available for this routine:
fd Integer returned by ffopen or ffopens
stat Status structure

RETURN VALUES
In case of error, both functions return -1 and the ffsw.sw_error field contains the error value.
Otherwise, 0 is returned.

136 004– 2165– 002

FFLISTIO ( 3C ) FFLISTIO ( 3C )

NAME
fflistio – Initiates a list of I/O requests using flexible file I/O

SYNOPSIS
#include <sys/types.h>
#include <sys/iosw.h>
#include <sys/listio.h>
#include <ffio.h>
int fflistio (int cmd, struct fflistreq *list, int nent
[,struct ffstat *stat]);

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The fflistio function provides a way to initiate a list of distinct I/O requests and, optionally, waits for
all of them to complete. Each I/O request in the list provides for maximum control over the desired I/O
characteristics. As much as possible, the operation of this function is the same as the listio system call.
The purpose of this function is to provide the functionality of listio(2) combined with the facilities
provided by flexible file I/O (FFIO).
The arguments are as follows:
cmd Any of the following commands:
LC_START Initiates the I/O requests and returns control as soon as possible
LC_WAIT Initiates the I/O requests and returns when all requests have completed
list Pointer to an array of fflistreq structures.
nent The number of requests in the list to process.
The fflistreq structure includes the following members:
int li_opcode Operation code for the request: LO_READ for read and LO_WRITE for
write.
unsigned li_drvr:32 Driver dependent; not used.
unsigned li_flags:32 Special request flags: LF_LSEEK to set initial file offset to
li_offset.
long li_offset Initial file byte offset, if LF_LSEEK is set in flags.
int li_fildes fdinfo pointer, obtained from ffopen(3C) or ffopens(3C).
char *li_buf Pointer to an I/O data buffer in memory.

004– 2165– 002 137

FFLISTIO ( 3C ) FFLISTIO ( 3C )

unsigned li_nbyte Number of bytes to read or write for each stride.

struct ffsw *li_status Pointer to an I/O status structure where the FFIO functions will put
completion status for this request. See fffcntl(3C).
int li_signo This value must be zero. Signals are not supported.
int li_nstride Number of strides; defaults to 1.
long li_filstride File stride in bytes; default is for contiguous data flow to/from the file.
long li_memstride Memory stride in bytes; default is for contiguous data flow to/from the
memory buffer.
When reading or writing an n-dimensional array on a disk, the desired data I/O occurs at regular intervals,
but it may not be contiguous. The last three variables in the fflistreq structure can be used to specify a
compound request, causing multiple sections of data to be transferred. The distance from the start of one
section of data on disk to the start of the next section is called the file stride. There is an analogous stride
through memory.
The operation of the stride parameters are the same as listio(2). See listio(2) for more information
on the details of operation.
When a particular request is complete, the associated ffsw structure is filled in whenever an fffcntl
function is given an opportunity with an FC_RECALL or FC_ASPOLL function code. In the ffsw
structure, sw_stat is set to a non-zero value upon completion, sw_error may contain a system or library error
number, and sw_count contains the number of bytes actually moved. For a successful compound request,
sw_count would be li_nstride * li_nbyte.
If one or more of the I/O requests are ill-formed and cannot be started, an LC_WAIT type command returns
immediately.

RETURN VALUES
If fflistio completes successfully, a nonnegative integer is returned, indicating the number of requests
that were successfully started. Otherwise, a value of -1 is returned, and errno is set to indicate the error.

ERRORS
The fflistio system call fails on a variety of conditions including the set of errors returned by
listio(2) and those returned by the FFIO functions.

EXAMPLES
The following example shows how to use the fflistio system call to initiate a list of input requests. The
fflistio request reads every tenth block (that is, blocks 1, 11, 21, 31, and so on) from file datafile.
fffcntl(3C) is used to determine when the request is complete.

138 004– 2165– 002

FFLISTIO ( 3C ) FFLISTIO ( 3C )

The request is initiated asynchronously (LC_START), and the data is stored in the buffer buf contiguously.
Since input is performed asynchronously, the program can complete other work in parallel with the request.
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <sys/types.h>
#include <signal.h>
#include <sys/iosw.h>
#include <sys/listio.h>
#include <ffio>

#define BLK_SIZ 4096

struct blk {
char blk_data[BLK_SIZ];
};

main()
{
struct fflistreq request;
struct ffsw reqstat, dumstat;
struct blk buf[10];
int fd;

if ((fd = ffopen("datafile", O_RDONLY)) == -1) {

perror("open (datafile) failed");
exit(1);
}
memset (&reqstat, 0, sizeof(reqstat));
memset (&request, 0, sizeof (request));

/* Set up the I/O request */

request.li_opcode = LO_READ; /*request read*/
request.li_fildes = fd; /*file descriptor*/
request.li_buf = (char *) buf; /*store input data here*/
request.li_nbyte = BLK_SIZ; /*each stride = 1 block*/
request.li_status = &reqstat; /*status for this request*/
request.li_signo = 0; /*do not send signal upon completion*/
request.li_nstride = 10; /*read 10 strides*/
request.li_memstride = 0; /*default (contiguous) memstride*/
request.li_filstride = 10 * BLK_SIZ; /*file stride=10 blocks*/

if (fflistio(LC_START, &request, 1) != 1) {
perror("fflistio failed");
exit(1);
}

/* other work can be performed here while fflistio request completes */

fffcntl(fd, FC_RECALL, &reqstat, &dumstat); /* waits for I/O completion */

printf("Number of bytes read = %d\n\n", reqstat.sw_count);

}

004– 2165– 002 139

FFLISTIO ( 3C ) FFLISTIO ( 3C )

SEE ALSO
fffcntl(3C), ffopen(3C)
listio(2) in the UNICOS System Calls Reference Manual

140 004– 2165– 002

FFOPEN ( 3C ) FFOPEN ( 3C )

NAME
ffopen, ffopens, ffclose, ffopenf, ffclosef – Opens or closes a file using flexible file I/O

SYNOPSIS
#include <fcntl.h>
#include <ffio.h>
UNICOS and UNICOS/mk systems:
int ffopen (const char *name, int oflag [, int mode
[, long cbits [, struct ffsw *stat]]]);
int ffopens (const char *name, int oflag, int mode,
long cbits, [int cblks,] struct ffsw *stat, const char *str);
ffclose (int fd [, struct ffsw *stat]);
IRIX systems:
int ffopen (const char *name, int oflag [,mode_t mode]);
int ffopens (const char *name, int oflag, mode_t mode,
long cbits, int cblks, struct ffsw *stat, const char *str);
int ffclose (int fd);
All systems:
ffclosef (int fd, struct ffsw *stat);
int ffopenf (const char *name, int oflag , mode_t mode, long cbits, int
cblks, struct ffsw *stat);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The ffopen and ffopens functions open a file using flexible file I/O (FFIO). These functions are
modeled after the open(2) system call. The file associated with name is opened, and appropriate structures
are built to do special handling on the file. For ffopen, the processing layers to be used are as requested
with the asgcmd(1) or assign(1) commands. For ffopens, the layers are specified by the string at str.
The ffopen function returns an integer. Although it is not a file descriptor, it is used in much the same
way when passed to the other functions such as ffread, ffwrite, or ffclose.
The oflag, mode, and cbits parameters are exactly as in open(2).

004– 2165– 002 141

FFOPEN ( 3C ) FFOPEN ( 3C )

On IRIX systems, the cbits and cblks parameters are ignored.

The stat parameter is a pointer to a status return structure containing a flag, an error indication, a transfer
count, and an indication of the condition that terminated the request.
The ffclose and ffclosef functions close the file associated with fd. It does any necessary flushing
and termination for that file. Files opened using ffopen(3C) are not guaranteed to be flushed at program
termination; call ffclose or ffclosef to ensure this.

NOTES
On IRIX systems, the FFIO routines are stored in libffio.so, and are available in the N32 and N64
ABIs.

RETURN VALUES
Upon successful completion, a non-negative integer is returned; this integer is currently a pointer to a control
block. Otherwise, -1 is returned, and, if the stat parameter is passed, the error value is found in
stat.sw_error. If the stat parameter is not provided, the error code is found in errno. The stat
parameter is required for ffopens() and ffclosef.

EXAMPLES
To write a C program that will read the records of a COS blocked file named indata and copy the data
from the file (without blocking information) to stdout, compile the following program:

142 004– 2165– 002

FFOPEN ( 3C ) FFOPEN ( 3C )

#inclu de <stdio .h>

#inclu de <fcntl .h>
#inclu de <ffio. h>

#define BSZ 100 00

main()
{
int fd, ret;
cha r buf [BSZ];
str uct ffsw stat;
int ubc = 0;

fd = ffopen ("i nda ta", O_RDON LY) ;

do
{
ret = ffread f(f d, buf , BSZ , &st at, PARTIA L, &ubc);
fwr ite (buf, 1, ret, std out );
} whi le (FF STAT(s tat ) != FFE OD) ;
ret = ffc lose(f d);
}

Use the following commands to compile, link, and run this program on UNICOS and UNICOS/mk systems:
$ cc cpy.c
$ FIL ENV =\$ EVAR ; exp ort FIL ENV
$ eva l ` ass ign -F cos ind ata ` # dec lar e "in dat a" is COS blocke d
$ a.o ut

Use the following commands to compile, link, and run this program on IRIX systems:
$ cc cpy .c -lf fio
$ eva l ` ass ign -F cos ind ata ` # dec lar e "in data" is COS blocke d
$ a.o ut

The same example program could be written to use the ffopens entry point. The layers to use in decoding
the blocking information are specified in the call, and not in the shell command asgcmd(1), as follows:
#in clude <st dio.h>
#in clude <fc ntl.h>
#in clude <ff io.h>

#defin e BSZ 10000

mai n()
{

004– 2165– 002 143

FFOPEN ( 3C ) FFOPEN ( 3C )

int fd, ret ;

cha r buf [BSZ];
cha r *st r;
str uct ffsw stat;
int ubc = 0;

/* Set up to proces s COS blo cked file. */

str = "co s";
fd = ffo pens(" indata ", O_R DON LY, 0, 0L, 0, &stat, str );
do
{
ret = ffr ead f(f d, buf , BSZ , &st at, PARTIA L, &ub c);
fwr ite (buf, 1, ret, stdout );
} whi le (FF STAT(s tat ) != FFE OD) ;
ret = ffc lose(f d);
}

Use the following commands on UNICOS and UNICOS/mk systems to compile, link, and run this program:
$ cc cpy .c
$ a.out

Use the following commands on IRIX systems to compile, link, and run this program:
$ cc cpy.c -lf fio

SEE ALSO
ffread(3C), ffseek(3C)
asgcmd(1)
open(2) in the UNICOS System Calls Reference Manual
Application Programmer’s I/O Guide

144 004– 2165– 002

FFPOS ( 3C ) FFPOS ( 3C )

NAME
ffpos – Positions files opened using flexible file I/O

SYNOPSIS
#include <ffio.h>
UNICOS and UNICOS/mk systems:
int ffpos (int fd, int cmd, long *arg , int len, struct ffsw *stat);
IRIX systems:
off_t ffpos (int fd, int cmd, void *arg , int len, struct ffsw *stat);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The ffpos function provides a way of positioning files opened by ffopen or ffopens (see
ffopen(3C)), using flexible file I/O (FFIO). The arguments are as follows:
fd Value returned by ffopen or ffopens.
cmd Specifies a value defined in header file ffio.h. See the following subsection, VALUES FOR cmd
ARGUMENT.
arg The type and value of this argument is cmd specific. See preceding descriptions.
len If cmd = FP_GETPOS or FP_SETPOS, len specifies the number of Cray words in arg. This
parameter is ignored for other values of cmd.
stat Pointer to the status return structure.
Values for cmd Argument
The following values can be used for the cmd argument introduced above.
FP_BSEEK
Sets the current file position as specified by *arg and *(arg+1). Not supported on IRIX systems.
*arg contains the bit position requested; this must be a byte boundary. *(arg+1) specifies one of
the following values, defined in header file stdio.h:
0 or SEEK_SET
Sets the pointer to the value of *arg, which must be a non-negative integer.
1 or SEEK_CUR
Sets the pointer to the current position, plus or minus *arg. This is supported only in the
following layers that are not record-oriented; these layers are specified to assign -F as follows:
syscall, sds, mr (memory resident), cache, cachea, bufa, er90.

004– 2165– 002 145

FFPOS ( 3C ) FFPOS ( 3C )

2 or SEEK_END
Sets the pointer to the end of the file, minus *arg. *arg must be a non-negative integer. Not all
layers support this option.
FP_GABS
Returns information about the current position in arg, which can later be used by a call to ffpos with
cmd = FP_SABS. arg is a pointer to structure fp_abs (defined in header file ffio.h).
This call is useful only for online tape and ER90 files. It may be used with the tape, er90, or bufa
layers on UNICOS systems. It may be used with the tape layer on Cray T3E systems. ER90 files are
not supported on Cray T3E systems. For some devices, some of the fields in fp_abs may be unused.
When this request is made after a write function, the library and tape driver flush all remaining data
from the write behind to the tape before attempting to get the position. When this request is made after
a read request, an approximate address is returned, since there may be data buffered in the controller,
system buffers, or library buffers. FP_GABS does not return information about the volume serial
number (VSN) currently in use.
FP_GETPOS
Returns information about the current position in arg, which can later be used by a call to ffpos with
cmd 0=FP_SETPOS. For online tape files, 2 Cray words are returned in arg. For files assigned with
assign -F er90, 4 Cray words are returned in arg. For files assigned with -F cos,er90, 6 Cray
words are returned in arg. For all other file types, 1 Cray word is returned in arg. For ER90 files, the
information returned does not include the VSN. When using the information returned in a call to
ffpos with cmd=FP_SETPOS, you must ensure that you are positioned on the correct volume. This
command is unsupported for ER90 files that use the FFIO tape layer. Available on UNICOS and
UNICOS/mk systems. ER90 files and the er90 layer are not supported on Cray T3E systems.
FP_SABS
Sets the position as specified in arg. The information in arg should have been obtained by a previous
call to ffpos with cmd = FP_GABS. arg is a pointer to structure fp_abs. This call is useful only
for online tape and ER90 files. FP_SABS assumes that you are currently positioned on the correct
VSN. You must have permission to set the position to the specified address when using absolute track
address positioning. Tape manager permission is required for IBM-compatible tapes. For ER90 files,
tape manager permission is required to position outside the current partition. Bypass-label permission
or tape manager permission is required to position outside the current file, or past a user tape mark.
Available on UNICOS and UNICOS/mk systems. ER90 files and the er90 layer are not supported on
Cray T3E systems.
FP_SETPOS
Sets the position as specified by the information in arg. The information in arg should have been
obtained by a previous call to ffpos with cmd = FP_GETPOS.
Not available on IRIX systems.

146 004– 2165– 002

FFPOS ( 3C ) FFPOS ( 3C )

FP_SKIPF
This value is valid only for online tape files on UNICOS systems and on Cray T3E systems and for
ER90 files on UNICOS systems. It directs the system to skip a specified number of files from the
current position. The file will not be positioned beyond BOD or EOD. This is used for positioning by
user tapemark (see the -T option on the tpmnt(1) command). It may not be used to position to
different files within a multifile volume (see the -q option of the tpmnt(1) command. arg is a pointer
to structure ffp_skipf_s (also defined in header file ffio.h). This cmd is valid with the following
FFIO layers: tape. The fields of this structure have the following meaning:
ffp_nfil On input, specifies the number of files to skip. If the value is negative, the file is
positioned backward. On output, contains the number of files skipped.
ffp_nrec Currently unused.
FP_SKIPTPMK
This value is valid only for online tape files on UNICOS systems and on Cray T3E systems. It directs
the system to skip a specified number of tape marks from the current position. The file will not be
positioned beyond BOD or EOD. This is used for positioning by user tapemark (see the -T option on
the tpmnt(1) command). arg is a pointer to structure ffp_skiptpmk_s (defined in <ffio.h>).
The fields in this structure have the following meaning:
ffp_ntpmk On input, specifies the number of tape marks to skip. If the value is negative, the file is
positioned backwards. On output, this field contains the number of tape marks left to
position.
unused1 This field is reserved.
The FP_SKIPTPMK cmd functions differently from FP_SKIPF. Except in the case where you request
positioning past EOD, FP_SKIPF will position you at the beginning of a file; that is, FP_SKIPF will
position you either at BOD, immediately after a user tape mark, or at EOD. FP_SKIPTPMK functions
like the ioctl TR_PTMS described in the Tape Subsystem User’s Guide. It skips the specified number of
tape marks. If skipping forward, it will position you directly after a user tape mark or at EOD. If
skipping backwards, it will position you directly before a user tape mark or at BOD. This cmd is valid
with the following FFIO layers: tape.
FP_SETTP
arg is a pointer to structure ffp_settp_s (also defined in header file ffio.h). This cmd is valid
with the following FFIO layers: tape.
The er90 layer is not supported on Cray T3E systems.
On input, the fields of ffp_settp_s have the following meaning:
ffp_nb
Number of blocks to position; should always be a positive number.
ffp_nbs_p
Indicates the direction of block positioning. The following values are defined in header
<ffio.h>:

004– 2165– 002 147

FFPOS ( 3C ) FFPOS ( 3C )

FP_TPOS_BACK
Indicates that the ffp_nb field is the number of blocks to skip backward, relative to the
current position.
FP_TPOS_FORW
Indicates that the ffp_nb field is the number of blocks to skip forward, relative to the
current position.
FP_TPOS_ABS
Indicates that the ffp_nb field is an absolute block number, relative to the last tape mark
number or beginning of the volume. If a nonzero value is specified for the ffp_nv field,
positioning is absolute with respect to that tape volume. If ffp_nv is 0, and the -T option
was not present on the tpmnt(1) command, the position is absolute with respect to the
current tape volume. If ffp_nv is 0, and the -T option was present on the tpmnt
command, then positioning is absolute with respect to the last tape mark read or written.
ffp_nv
Number of volumes to position; should always be a positive number. A volume number of 0
indicates no volume positioning is to be performed.
ffp_nvs_p
Indicates the direction of volume positioning. The following values are defined in header file
ffio.h:
FP_TPOS_FORW The number of volumes to skip forward, relative to the current position.
FP_TPOS_BACK The number of volumes to skip backward, relative to the current position.
FP_TPOS_ABS Specifies an absolute volume number, relative to the beginning of the volume
identifier list (specified on the tpmnt(1) command.)
ffp_vi
Name of volume identifier to be mounted. A nonzero ffp_vi field is invalid if ffp_nbs_p is
FP_TPOS_FORW or FP_TPOS_BACK or if ffp_nvs is FP_TPOS_FORW or FP_TPOS_BACK
and ffp_nv is nonzero.

RETURN VALUES
If cmd is FP_BSEEK, ffpos returns the new bit position of the file on success. For other values of cmd,
the ffpos function returns 0 on success. On failure, it returns -1 and the sw_error field of the stat
structure contains the error number.

SEE ALSO
ffopen(3C)
tpmnt(1) in the UNICOS User Commands Reference Manual
Tape Subsystem User’s Guide

148 004– 2165– 002

FFREAD ( 3C ) FFREAD ( 3C )

NAME
ffread, ffwrite, ffweof, ffweod, ffreadf, ffwritef, ffweodf, ffweoff, ffflush –
Provides flexible file I/O

SYNOPSIS
#include <ffio.h>
UNICOS and UNICOS/mk systems:
int ffread (int fd, void *buf, size_t nb [, struct ffsw *stat [, int
fulp [, int *ubc]]]);
int ffwrite (int fd, const void *buf, size_t nb [, struct ffsw *stat
[, int fulp [, int *ubc]]]);
int ffweof (int fd [, struct ffsw *stat]);
int ffweod (int fd [, struct ffsw *stat]);
int ffflush (int fd [, struct ffsw *stat]);
IRIX systems:
ssize_t ffread (int fd, void *buf, size_t nb);
ssize_t ffwrite (int fd, const void *buf, size_t nb);
int ffweof (int fd);
int ffweod (int fd);
int ffflush (int fd);
All systems:
size_t ffreadf (int fd, void *buf, size_t nb , struct ffsw *stat, int
fulp, int *ubc);
size_t ffwritef (int fd, const void *buf, size_t nb , struct ffsw
*stat, int fulp, int *ubc);
int ffweoff (int fd, struct ffsw *stat);
int ffweodf (int fd, struct ffsw *stat);
int ffflush (int fd, struct ffsw *stat);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

004– 2165– 002 149

FFREAD ( 3C ) FFREAD ( 3C )

DESCRIPTION
The ffread and ffwrite functions provide flexible file I/O (FFIO) to record-oriented or byte
stream-oriented data in an application-transparent manner.
Function ffweof writes an end-of-file (EOF) if the function is supported for the layer in use.
Function ffweod writes an end-of-data (EOD). If the FFIO specification is stream oriented, this requests
truncation of the file at the current position.
Function ffflush instructs the layer to flush as much data to the file as is convenient. For some layers,
and layers which do no buffering (for example, the syscall layer), this operation does nothing. For record
layers, the ffflush function will not terminate any partially-written records. This function is intended for
use on files which are being written. It is undefined for files which are being read.
The arguments are as follows:
fd Number returned by ffopen(3C).
buf Pointer to the user data buffer.
nb Requested number of bytes to be read or written.
stat Pointer to the returned status structure.
fulp Either FULL or PARTIAL (defined in header file ffio.h); indicates whether I/O should be
performed in full or partial record mode.
ubc Unused bit count. The word pointed to by this pointer is in the range of 0 through 7; it is used to
specify how many bits in the last byte are not valid data.
The nb and ubc arguments are used together to determine an exact number of bits to be transferred. nb
always indicates the number of bytes affected by the data transfer, even if only one bit is transferred in that
byte.
If argument ubc is omitted, it is assumed to be 0.
If ubc is specified, it functions as both an input and output argument. It is passed to ffread or ffwrite
as a request to omit processing the specified number of bits in the last byte of the request. For example, to
read 2 bits from a file, you should set nb to 1, set the word at ubc to 6, and call ffread. On completion of
the ffread request, the word pointed to by ubc is set by ffread to indicate the number of unused bits in
the last byte read. As in the preceding example, if only one bit were available to be read, then the word at
ubc would be set to 7 by ffread.
For ffwrite, ubc is an input argument specifying the number of bits in the last byte transferred that should
not be written to the file. Function ffwrite normally will not change the value of the word at ubc,
because, if the specified number of bits is not written, an error is returned.

150 004– 2165– 002

FFREAD ( 3C ) FFREAD ( 3C )

RETURN VALUES
Upon successful completion, a non-negative value is returned. Otherwise, -1 is returned and, if the stat
argument is passed, the error value is found in stat.sw_error. If the stat parameter is not provided, the
error code is found in errno.
If the stat parameter is passed, the sw_stat field is set to one of the following values, indicating the
condition that terminated the operation:
Value Description
FFERR An error was encountered.
FFEOR An end-of-record (EOR) was encountered.
FFEOF An end-of-file (EOF) was encountered.
FFEOD An end-of-data (EOD) was encountered.
FFCNT For layers without record handling, some data was read before an EOF or EOD was encountered.
For layers with record handling, the count was satisfied before an EOR was encountered. If the
count was satisfied simultaneously with encountering an EOR, the FFEOR status is returned.
The FFSTAT macro, defined in ffio.h, can be used to obtain the value of the sw_stat field.

SEE ALSO
ffopen(3C), ffseek(3C)
asgcmd(1)
Application Programmer’s I/O Guide

004– 2165– 002 151

FFREADA ( 3C ) FFREADA ( 3C )

NAME
ffreada – Provides asynchronous read using flexible file I/O

SYNOPSIS
#include <ffio.h>
int ffreada (int fd, char *buf, unsigned nbyte, struct ffsw *status [, int
fulp [, int *ubc)]];

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The ffreada function is modeled after the reada system call, and the parameters are the same as
ffread(3C). The difference between ffread and ffreada is that ffreada performs its work
asynchronously whenever possible.
Arguments to ffreada are as follows:
fd Value returned from an ffopen, or ffopens call.
buf Pointer to the buffer in which the data is stored.
nbyte Number of bytes to be written.
status Address of the ffsw status return structure, which is described in the following paragraphs.
fulp Either the value FULL or PARTIAL as defined in header ffio.h. Specifying FULL requests
that the file position should be advanced to a point immediately after the next EOR in the file
after transferring the requested data. Specifying PARTIAL requests that the file position should
be maintained at the bit immediately following the last one transferred. This is an optional
argument. If it is not specified, FULL is assumed.
ubc Number of unused bits in the last byte; for example, a single bit can be read by requesting one
byte and a ubc of 7. This is an optional argument. If it is not specified, 0 is assumed.
The ffreada function tries to read nbyte bytes from the FFIO file associated with fd (opened with ffopens
or ffopen). Data is read into the buffer pointed to by buf (see ffread(3C)). The function returns control to
the user as soon as possible, even when the data cannot be delivered until later. The stat parameter is used
to notify the caller when the request has completed. The status structure has several fields used to determine
the status of a given request. The following is a partial description of the status structure:

152 004– 2165– 002

FFREADA ( 3C ) FFREADA ( 3C )

struct ffsw {
uin t sw_ fla g :1,
sw_ err or :31,
sw_ cou nt :32,
sw_ sta t :16;
};

A call to ffreada initiates an asynchronous read of the requested data. You must check for completion of
each asynchronous request by using fffcntl with the command codes FC_RECALL or FC_ASPOLL. If
such a call to fffcntl detects that the request is complete, the status structure is filled in. The sw_flag is
always set on completion, sw_error may contain a system call or library error number and sw_count contains
the number of bytes actually moved. Some FFIO layers with less than byte granularity also return a value in
ubc that contains the number of bits in the last byte returned that are not valid.
The file position for reading or writing is always the file position at the time of the ffreada or
ffwritea(3C) call. The file’s position is incremented at that time by nbyte bytes, or the number of bytes
remaining in the file, whichever is less. In this way, calls to the ffreada, ffwritea, and ffseek(3C)
library functions can be interspersed, and the file position is incremented naturally.
To use asynchronous I/O effectively, all outstanding I/O requests must have their own status structures.
Each request must also be checked with an fffcntl(3C) call with a command code of FC_RECALL or
FC_ASPOLL. Use code FC_RECALL if the caller does not want control returned until the I/O request is
complete. Code FC_ASPOLL returns control immediately, regardless of the status of the request. This
allows the user to check on the completion of a given request without waiting.

RETURN VALUES
If ffreada completes successfully, a nonnegative integer is returned. Otherwise, a value of -1 is returned,
and status.sw_error is set to indicate the error.

ERRORS
The ffreada function fails for a variety of reasons, including library and system errors.

EXAMPLES
The following example illustrates a way to use function ffreada to perform a read operation in parallel
with other work in a user’s process.
#inclu de <stdli b.h >
#inclu de <stdio .h>
#inclu de <fcntl .h>
#inclu de <ffio. h>

str uct ffsw rdstat , wrs tat , dum stat;

004– 2165– 002 153

FFREADA ( 3C ) FFREADA ( 3C )

main()
{
cha r buf [4096* 8], buf 2[4 096 *8];
int fd;

if ((f d = ffo pen ("datafil e", O_RDON LY) ) == -1) {

perror ("open (da tafile ) failed ");
exit(1 );
}
/*
* Ass ume the fil e is lar ge. Read in first 8 sectors, and
* sim ult aneous ly wri te out the follow ing 8 sec tors.
*/
ffread a(f d, buf, 409 6*8, &rdstat, FULL);
ffw ritea( fd, buf2, 4096*8 , &wrsta t, FULL);

/* per for m oth er wor k her e in par allel wit h I/O completion */

/*
* See if eit her ope rat ion is com plete wit h fffcntl(F C_ASPOLL).
* Che ck sw_ sta t to det ermine com pletio n.
*/
fff cnt l(fd, FC_ASP OLL , &rd stat, &du mstat) ; /* don’t wai t */
fff cntl(f d, FC_ ASP OLL , &wr stat, &du mstat); /* don’t wait */

if (FFSTA T(r dstat) == 0) reada_is_ not _done();

if (FF STAT(w rst at) == 0) wri tea_is_not_d one();
/*
* wai t for read and write to comple te. fffcntl(3 ) may have to be
* cal led more than onc e. Check sw_stat to ensure completion.
*/
whi le( FFSTAT (rdsta t) == 0)
fff cnt l(f d, FC_ RECALL , &rdsta t, &dumstat);

if (FFSTA T(rdst at) == FFE RR)

printf ("Read fai led, errno=%d" , rdstat.sw _error);

/* wai t for write */

while( FFSTAT (wr sta t) == 0)
fff cnt l(fd, FC_ REC ALL, &wrstat, &dumstat);

if (FF STAT(w rst at) == FFERR)

printf ("Read failed , err no= %d", wrs tat.sw_error );

154 004– 2165– 002

FFREADA ( 3C ) FFREADA ( 3C )

/* input dat a from ffreada now availa ble in buf fer buf */
}

SEE ALSO
errno.h(3C), fffcntl(3C), ffopen(3C), ffread(3C), ffseek(3C), ffwritea(3C), intro(3C)

004– 2165– 002 155

FFSEEK ( 3C ) FFSEEK ( 3C )

NAME
ffseek, ffbksp, ffseekf, ffbkspf – Repositions a flexible file I/O file

SYNOPSIS
#include <ffio.h>
#include <unistd.h>
UNICOS and UNICOS/mk systems:
int ffseek (int fd, off_t pos, int whence [, struct ffsw *stat]);
int ffbksp (int fd [, struct ffsw *stat]);
IRIX systems:
off_t ffseek (int fd, off_t pos, int whence);
int ffbksp (int fd);
All systems:
off_t ffseekf (int fd, off_t pos, int whence, struct ffsw *stat);
int ffbkspf (int fd, struct ffsw *stat);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The ffseek function provides flexible file I/O (FFIO) positioning capability similar to that of lseek(2).
In addition to the functionality of lseek, ffseek provides access to limited positioning on blocked files
and record-oriented files. Specifying ffseek(fd, 0, 0) always rewinds a file to its initial point,
regardless of whether the file is stream, blocked, or tape. When using the syscall layer, this function
cannot be used to position a tape.
This function allows programs to be written so that their I/O can be controlled by the asgcmd(1) or
assign(1) command. Both native and foreign record-oriented I/O, multifile datasets, and
performance-oriented layers (such as SDS resident layers and memory-resident layers) are available with this
mechanism.
Function ffbksp allows you to perform a backspace operation on those FFIO layers that support it.
Currently, this is limited to cos, tape, f77, and text.
Arguments are as follows:
fd Number returned by ffopen(3C).
pos Byte position requested.
whence Specifies one of the following values (defined in header file stdio.h):

156 004– 2165– 002

FFSEEK ( 3C ) FFSEEK ( 3C )

0 or SEEK_SET Sets the pointer to the value of pos. pos must be a non-negative integer.
(Special case: ffseek(fd, 0, 0) = rewind)
1 or SEEK_CUR Sets the pointer to the current position, plus or minus *arg. This is
supported only in layers that are not record-oriented; layers are specified
to assign -F as follows: syscall, sds, mr (memory resident),
cache, cachea, bufa, er90.
2 or SEEK_END Sets the pointer to the end of the file, minus pos. pos must be a
non-negative integer. Not all layers support this option. (Special case:
ffseek(fd, 0, 2) = position just in front of the EOD.)
stat Pointer to the ffsw status return structure.

RETURN VALUES
The return value is the current position in the file after the seek. Upon successful completion, a
non-negative value is returned. Otherwise, -1 is returned, and, if the stat parameter is passed, the error value
is found in stat.sw_error. If the stat parameter is not provided, the error code is found in errno.

EXAMPLES

#inclu de <stdli b.h >

#inclu de <fcntl .h>
#inclu de <stdio .h>
#inclu de <ffio. h>

main()
{
siz e_t ret ;
int fd, i, j;
off _t fre t;

fd = ffo pen("d ata ", O_R DWR | O_CREA T, 066 6);

for (i = 0 ; i < 1000 ; i++ )

{
ret = ffw rite(f d, &i, siz eof (i));
if (ret < 0) abo rt( );
}

for (i = 0 ; i < 10 ; i++ )

{
fre t = ffseek (fd , i * siz eof (j) * 100, SEE K_SET) ;
if (fr et < 0) abort( );
ret = ffr ead (fd, &j, siz eof(j) );

004– 2165– 002 157

FFSEEK ( 3C ) FFSEEK ( 3C )

if (ret < 0) abo rt( );

pri ntf("V alu e is %d at wor d %d\ n", j, i*1 00) ;
}
}

Output from the previous program is as follows:

Value is 0 at wor d 0
Val ue is 100 at word 100
Val ue is 200 at word 200
Val ue is 300 at word 300
Val ue is 400 at word 400
Val ue is 500 at word 500
Val ue is 600 at word 600
Val ue is 700 at word 700
Val ue is 800 at word 800
Val ue is 900 at word 900

SEE ALSO
errno.h(3C), ffclose(3C), ffopen(3C), ffread(3C), ffwrite(3C)

158 004– 2165– 002

FFSETSP ( 3C ) FFSETSP ( 3C )

NAME
ffsetsp – Initiates EOV processing for files opened using flexible file I/O

SYNOPSIS
#include <ffio.h>
int ffsetsp (int fd[, struct ffsw *stat]);

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The ffsetsp function initiates special end-of-volume (EOV) processing for online tape files opened by
ffopen or ffopens (see ffopen(3C)), using flexible file I/O (FFIO). Arguments are as follows:
fd Number returned by ffopen or ffopens.
stat Pointer to the status return structure.
This function is valid only for online tape and ER90 files that use the FFIO tape layer on UNICOS and
UNICOS/mk systems. ER90 files are not supported on Cray T3E systems.

RETURN VALUES
Function ffsetsp returns 0 if successful. Otherwise, a value of -1 is returned, and, if the stat parameter is
passed, the error value is found in stat.sw_error. If the stat parameter is not provided, the error code
is found in errno.

SEE ALSO
fffcntl(3C), ffopen(3C)

004– 2165– 002 159

FFSTRERROR ( 3C ) FFSTRERROR ( 3C )

NAME
FFSTRERROR – Get FFIO error message string

SYNOPSIS
#include <ffio.h>
char *ffstrerror(int errnum);

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The FFSTRERROR function maps an FFIO error number in errnum to an error message string, and returns a
pointer to that string. The returned string should not be overwritten.

SEE ALSO
strerror(3C)

160 004– 2165– 002

FFWRITEA ( 3C ) FFWRITEA ( 3C )

NAME
ffwritea – Provides asynchronous write using flexible file I/O

SYNOPSIS
#include <ffio.h>
int ffwritea (int fd, char *buf, unsigned nbyte, struct ffsw *status [,int
fulp[, int *ubc]]);

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The ffwritea function is modeled after the writea system call and the parameters are the same as
ffwrite(3C). The difference between ffwrite and ffwritea is that ffwritea performs its work
asynchronously when possible.
Arguments to ffwritea are as follows:
fd Value returned from an ffopen, or ffopens call.
buf Pointer to the buffer in which the data is stored.
nbyte Number of bytes to be written.
status Pointer to the ffsw status return structure, described in detail in ffreada(3C).
fulp Either the value FULL or PARTIAL as defined in header ffio.h. FULL requests that an EOR
mark be written immediately after the requested data. PARTIAL requests that no such mark be
written.
This is an optional argument. If it is not specified, FULL is assumed.
ubc Number of unused bits in the last byte; for example, a single bit can be written by requesting 1
byte and a ubc of 7.
This is an optional argument. If it is not specified, 0 is assumed.
The description of handling asynchronous FFIO is given under ffreada and fflistio.

ERRORS
Function ffwritea fails and the file pointer remains unchanged if any one of a number of conditions
occurs. These include many system errors and library errors that result from the operations performed by the
FFIO layers performing the I/O.

004– 2165– 002 161

FFWRITEA ( 3C ) FFWRITEA ( 3C )

RETURN VALUES
If ffwritea completes successfully, a nonnegative integer is returned. Otherwise, a value of -1 is
returned, and status.sw_error is set to indicate the error.

EXAMPLES
An example program using ffwritea is shown with ffreada(3C).

SEE ALSO
errno.h(3C), fffcntl(3C), fflistio(3C), ffopen(3C), ffreada(3C)
write(2) in the UNICOS System Calls Reference Manual

162 004– 2165– 002

GLIO_GROUP ( 3F ) GLIO_GROUP ( 3F )

NAME
glio_group_mpi, glio_group_shmem – Defines a group of processes to be associated with a global
file.

SYNOPSIS
C or C++:
#include <ffio.h>
#include <mpi.h>
void glio_group_mpi(MPI_Comm comm)
#include <mpp/shmem.h>
void glio_group_shmem(int handle);
Fortran:
include "mpif.h"
INTEGER comm
CALL GLIO_GROUP_MPI(comm)
include "mpp/shmem.fh"
INTEGER handle
CALL GLIO_GROUP_SHMEM(handle);

IMPLEMENTATION
UNICOS/mk and IRIX systems

DESCRIPTION
These subroutines identify the group of processes which will share access to any FFIO files opened with the
global FFIO layer. These files, termed global files, must be opened and closed collectively by all
processes that share access to them.
The following is a list of valid arguments for these routines:
comm An MPI communicator. The group of processes associated with this communicator will access
the global file. This process group must be executing within a single host machine.
handle A SHMEM process group handle returned from the shmem_group_create_strided()
function.
The glio_group_mpi and glio_group_shmem functions are collective across the set of processes
identified by comm or handle.
If glio_group_mpi or glio_group_shmem are not called prior to an open of a global file, all MPI
or SHMEM processes in the application must collectively open and close the file.

004– 2165– 002 163

GLIO_GROUP ( 3F ) GLIO_GROUP ( 3F )

EXAMPLES
The following Fortran program opens global file globfile for access from SHMEM processes (PEs) 0 and
1. PEs 2 and higher will not access the file.
pro gram global _subse t
inc lude "mpp/s hmem.f h"
int eger racom, handle
common /racom / racom( SHMEM_ GROUP_ COM _SIZE)

cal l sta rt_pes (0)

rac om = 0

c Def ine a SHMEM group and then open glo bfile acr oss thi s gro up

if (my _pe(). le.1) the n

cal l ass ign("a ssign -F glo bal u:2 0",ier)
han dle = shm em_gro up_cre ate_st rided( 0, 1, 2, rac om, shmem_ null)
call glio_g roup_shme m(hand le)
ope n (20 ,file= "globf ile",a ccess= "direc t",rec l=64)
endif

end

SEE ALSO
shmem_group_create_strided(3)

164 004– 2165– 002

INTRO_PXF ( 3F ) INTRO_PXF ( 3F )

NAME
INTRO_PXF – Introduction to PXF POSIX library

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION
The POSIX FORTRAN 77 Language Interfaces Standard IEEE Std 1003.9-1992 (POSIX.a) defines a
standardized interface for accessing the system services of IEEE Std 1003.1-1990 (POSIX.1), and supports
routines to access constructs not directly accessible with FORTRAN 77.
Only a subset of the routines described in this standard are currently available on Cray Research systems.
For some routines, only a portion of the functionality described by the standard is currently implemented.
Many of the service interfaces defined in POSIX.1 require the use of aggregate data types (for example,
structures) that do not map to FORTRAN 77 entities. POSIX.9 solves this problem by the use of data
abstraction; by using additional subroutines to access and manipulate the aggregate data, the underlying data
structures are hidden from the user. It is the responsibility of the Fortran programmer to maintain variables
corresponding to the individual components of the actual implementation of the aggregate data, but the
programmer does not need to know the details of the actual implementation of the aggregate. The basic
model of this data abstraction is as follows:
1. The programmer calls the PXFSTRUCTCREATE subroutine to "create" an instance of the desired
aggregate data type; this subroutine returns a handle that the programmer subsequently uses in order to
reference and/or manipulate the data.
2. The programmer uses additional subroutines to load values into, or extract values out of, the aggregate
data. These subroutines are passed the handle of the desired aggregate and the name of the specific
component that is to be accessed. The programmer has direct control over only one component at a
time.
3. If an application passes information to the system, the PXFtypeSET subroutine is called once for each
member before calling the system procedure. Currently, only PXFINTSET and PXFSTRSET are
implemented.
4. If an application needs to get information from the system, the PXFtypeGET subroutine is called once
for each member after calling the system procedure. Currently, only PXFINTGET and PXFINTSET are
implemented.
5. When an instance of an aggregate is no longer required, a subroutine (PXFSTRUCTFREE) can be called
to release it.
6. When calling the actual system procedure, the calling sequence is equivalent to the C binding as shown
in POSIX.1, except that a handle is used in place of the POSIX.1 structure (pointer) argument.

004– 2165– 002 165

INTRO_PXF ( 3F ) INTRO_PXF ( 3F )

Classification of routines
The POSIX routines can be divided into several general groups as described below.
Process primitives
• Routines that create, execute, or terminate a process
1. PXFFORK - Creates a process
2. PXFEXECV, PXFEXECVE, PXFEXECVP - Executes a new process
3. PXFWAIT, PXFWAITPID - Obtains information about a calling process’ child process
4. PXFFASTEXIT - Terminates a Fortran program
5. PXFWIFEXITED - Determines if child process exited with exit
6. PXFWIFSIGNALED - Determines if the child process terminated because of a signal
7. PXFWIFSTOPPED - Determines if a child process has stopped
• Signal routines
8. PXFKILL - Sends a signal to a process or group of processes
9. PXFSIGADDSET - Adds an individual signal to the specified signal set
10. PXFSIGDELSET - Deletes an individual signal in the specified signal set
11. PXFSIGEMPTYSET - Initializes signal set such that all signals defined in POSIX standard are excluded
12. PXFSIGFILLSET - Initializes signal set such that all signals defined in POSIX standard are included
13. PXFSIGISMEMBER - Determines if the specified signal is a member of the specified signal set
14. PXFSIGPENDING - Examines pending signals
15. PXFSIGPROCMASK - Examines and changes blocked signals
16. PXFSIGSUSPEND - Waits for a signal
17. PXFALARM - Schedule alarm signal
18. PXFPAUSE - Suspends process execution until signal
19. PXFSLEEP - Delays process execution
Process environment routines
• Process identification routines
1. PXFGETPID - Gets the process ID
2. PXFGETPPID - Gets the parent process ID
• User identification routines
3. PXFGETEGID - Gets the effective group ID
4. PXFGETEUID - Gets effective user ID

166 004– 2165– 002

INTRO_PXF ( 3F ) INTRO_PXF ( 3F )

5. PXFGETGID - Gets the real group ID

6. PXFGETGROUPS - Gets supplementary group IDs
7. PXFGETLOGIN - Gets user name
8. PXFGETUID - Gets the real user ID
9. PXFSETGID - Sets group ID
10. PXFSETUID - Sets user ID
• Process groups routines
11. PXFSETPGID - Set process group ID
12. PXFSETSID - Creates a new session for a calling process
• System identification routines
13. PXFUNAME - Retrieves the operating system name
• Time routines
14. PXFTIME - Gets system time
15. PXFTIMES - Gets process times
• Environment variable processing routines
16. PXFCLEARENV - Clears all environment variables
17. PXFGETENV - Returns a value for the environment name
18. PXFSETENV - Sets environment variable pair
• Terminal identification routines
19. PXFCTERMID - Generates terminal pathname
20. PXFISATTY - Determines if file descriptor corresponds
• Configurable system values
21. PXFSYSCONF - Retrieves the value of configurable system variables
File and directory routines
1. PXFACCESS - Checks the accessibility of a named file
2. PXFCHDIR - Changes the current directory to a specified directory
3. PXFCHMOD - Sets file modes for a named file
4. PXFCHOWN - Changes the owner and group of a file
5. PXFCHROOT - Changes the root directory to a specified directory
6. PXFCREAT - Creates a new file or rewrites an existing file
7. PXFDIRECTORY - Performs directory operations

004– 2165– 002 167

INTRO_PXF ( 3F ) INTRO_PXF ( 3F )

8. PXFGETCWD - Gets the pathname of the working directory

9. PXFISBLK - Tests for block special file
10. PXFISCHR - Tests for character special file
11. PXFISDIR - Tests for directory file
12. PXFISFIFO - Tests for pipe or a FIFO special file
13. PXFISREG - Tests for regular file
14. PXFLINK - Creates a link to a file
15. PXFOPEN - Provides a Fortran interface to the open(2) system call
16. PXFRENAME - Renames a file
17. PXFRMDIR - Removes a directory entry
18. PXFSTAT - Retrieves the file status
19. PXFUMASK - Sets the file creation mask
20. PXFUNLINK - Removes a directory entry
21. PXFUTIME - Sets access and modification times of a file
Input and output primitives
1. PXFFCNTL - Provides a subset of fcntl(2) functionality, except the third argument is always an
integer
Device and class-specific procedures (not available)
Fortran intrinsics
1. PXFCONST, PXFISCONST, IPXFCONST - Returns the value associated with symbolic constants
2. PXFESTRGET - Accesses a single string element of a structure component that is an array
3. PXFFILENO - Returns the file descriptor for a specified unit
4. PXFGETARG - Returns a command-line argument
5. PXFINTGET - Allows values stored in individual components of a structure to be extracted and used
6. PXFINTSET - Allows components of a structure to be set or modified
7. PXFLOCALTIME - Converts to local time
8. PXFSTRGET - Allows values stored in individual components of a structure to be extracted and used
9. PXFSTRSET - Allows values stored in individual components of a structure to be set
10. PXFSTRUCTCOPY - Copies structure
11. PXFSTRUCTCREATE - Creates an instance of the desired structure and returns a nonzero handle in the
argument jhandle

168 004– 2165– 002

INTRO_PXF ( 3F ) INTRO_PXF ( 3F )

12. PXFSTRUCTFREE - Deletes the instance of the structure referenced by jhandle

13. PXFUCOMPARE - Compares unsigned integers
System Databases
1. PXFGETGRGID - Gets group information using the group ID
2. PXFGETGRNAM - Gets group information using the group name
3. PXFGETPWNAM - Gets password information about login name
4. PXFGETPGRP -Gets the process group ID
5. PXFGETPWUID - Gets password information by using user ID
See the individual man pages for complete details.

004– 2165– 002 169

IPXFARGC ( 3F ) IPXFARGC ( 3F )

NAME
IPXFARGC – Returns the number of command-line arguments excluding the command name

SYNOPSIS
INTEGER FUNCTION IPXFARGC()

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when you compile
programs with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs
option to the MIPSpro F77 compiler.
The IPXFARGC function returns the number of command-line arguments in the command used to invoke the
executing program. The command name is not included in the number returned. A return value of 0
indicates that there are no command-line arguments other than the command name itself.

170 004– 2165– 002

IPXFWEXITSTATUS ( 3F ) IPXFWEXITSTATUS ( 3F )

NAME
IPXFWEXITSTATUS – Returns the lower bits of exit argument

SYNOPSIS
INTEGER FUNCTION IPXFWEXITSTATUS(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The IPXFWEXITSTATUS integer function returns part of the lower bits from the exit argument x. The
PXFWIFEXITED logical function returns TRUE when exit() was used to return from the child process.
IPXFWEXITSTATUS should only be used when PXFWIFEXITED returns TRUE.
The following is a list of arguments for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

004– 2165– 002 171

IPXFWEXITSTATUS ( 3F ) IPXFWEXITSTATUS ( 3F )

program pxftes t
intege r ist at, iretpi d, ipi d, ier ror , i, j
intege r iwe xit status , IPX FWEXIT STA TUS
logical lwifex ite d, PXF WIF EXI TED

CALL PXF FORK(i pid ,ierro r)

if (ie rror .ne. 0) the n
pri nt *,’FAI LED : PXFFOR K cal l fai led with err or = ’,i error
els e
if (ip id .eq . 0) then
j = 0
do i=1,10 000 0
j = j + i
end do
sto p
els e

CAL L PXF WAIT(i stat,i ret pid ,ierro r)

if (ierro r .eq . 0) the n
pri nt *,’PAS SED: PXF WAI T normal tes t’
lwifex ite d = PXF WIF EXITED (istat )
if (lw ifexited .eq v. .TR UE.) then ! exi t normal ly
iwe xitstatus = IPX FWE XITSTA TUS (istat )
if (iw exi tstatu s .ne . 0) the n ! exi t(0) ret urned
pri nt *,’ PXFWIF EXITED ret urn ed TRUE’
print *,’exp ect ed IPX FWEXITSTA TUS (istat) = 0’
pri nt *,’ IPX FWEXIT STA TUS(is tat ) = ’,iwexits tatus
else
pri nt *,’ PXF WIFEXI TED test PAS SED’
pri nt *,’ IPXFWE XIT STATUS tes t PASSED ’
end if
els e
pri nt *,’ PXFWIF EXI TED ret urned FALSE’
pri nt *,’PXF WAI T istat = ’, ist at
pri nt *,’IPX FWE XIT STA TUS can not be cal led .’
endif
else
pri nt *,’ FAI LED : PXF WAIT cal l with err or = ’,i error
end if
endif
end if
end

172 004– 2165– 002

IPXFWEXITSTATUS ( 3F ) IPXFWEXITSTATUS ( 3F )

SEE ALSO
PXFWAIT(3F), PXFWIFEXITED(3F)

004– 2165– 002 173

IPXFWSTOPSIG ( 3F ) IPXFWSTOPSIG ( 3F )

NAME
IPXFWSTOPSIG – Returns part of the lower bits of signal number that terminates child process

SYNOPSIS
INTEGER FUNCTION IPXFWSTOPSIG(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The IPXFWSTOPSIG integer function returns part of the lower bits of the signal number that caused the
child process to stop. The PXFWIFSTOPPED logical function returns TRUE to indicate that the child
process has stopped. IPXFWSTOPSIG should only be used if PXFWIFSTOPPED returns TRUE.
The following argument is used for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

pro gra m pxf test

int eger istat, iretpi d, ipi d, ier ror, i, j
int eger iwstop sig , IPXFWS TOP SIG
log ical lwi fstopp ed, PXFWIF STOPPE D
CALL PXFFOR K(ipid ,ierror)
if (ie rro r .ne . 0) the n
pri nt *,’ FAILED : PXFFOR K call fai led wit h error = ’,ierr or
else

174 004– 2165– 002

IPXFWSTOPSIG ( 3F ) IPXFWSTOPSIG ( 3F )

print *,’PAS SED: PXF FOR K cal l’

if (ip id .eq . 0) the n
j = 0
do i=1 ,10 0000
j = j + i
end do
cal l PXF GET PID (ichld id, ier ror )
if (ierro r .ne . 0) the n
print *, ’PX FGE TPI D FAI LED , ier ror=’, ier ror
print *, ’ic hld id=’, ich ldi d
els e
print *, ’PX FGE TPID PASSED ’
end if
cal l PXFCON ST( "SI GST OP" ,isig, ier ror )

print *, ’PX FCO NST FAI LED , ier ror=’, ier ror
print *, ’is ig= ’, isi g
els e
pri nt *, ’PX FCO NST PASSED ’
endif
cal l PXF KIL L(ichl did,is ig, ier ror )
if (ie rror .ne . 0) the n
pri nt *, ’PX FKI LL FAILED ier ror=’, ier ror
pri nt *, ’ic hld id=’, ich ldi d
pri nt *, ’is ig= ’, isi g
else
pri nt *, ’PXFKILL PAS SED ’
endif
sto p "CH ILD "
els e
call PXF CONST( "WUNTR ACE D", iopts, ier ror )
if (ierro r .ne . 0) the n
print *, ’PXFCO NST FAI LED , ier ror=’, ier ror
print *, ’iopts =’, iopts
els e
pri nt *, ’PXFCO NST PAS SED ’
end if
CAL L PXF WAI TPI D(i pid,is tat ,io pts ,iretp id, ier ror )
if (ie rror .eq . 0) the n
pri nt *,’ PAS SED : PXF WAI T tes t’
lwifst opp ed = PXF WIF STOPPE D(i sta t)
if (lwifs top ped .eq v. .TR UE. ) the n
iwstopsig = IPX FWS TOPSIG (is tat )
if (iw sto psig .ne. 0) the n

004– 2165– 002 175

IPXFWSTOPSIG ( 3F ) IPXFWSTOPSIG ( 3F )

print *,’ PXF WIFSTO PPED test PAS SED ’

print *,’IPX FWS TOP SIG tes t PAS SED ’
cal l PXF CONST( "SI GCO NT" ,isig, ier ror )
if (ierro r .ne . 0) then
pri nt *,’ PXF CON ST FAI LED ,ie rro r=’,ie rro r
pri nt *,’ isig=’ , isi g
els e
print *, ’PX FCO NST PAS SED ’
end if
! continue the chi ld pro cess
call PXF KIL L(i pid,is ig, ier ror )
els e
pri nt *,’ PXF WIFSTO PPE D tes t PAS SED ’
pri nt *,’IPX FWS TOPSIG tes t FAI LED’
pri nt *,’ PXF WIFSTO PPED return ed TRU E’
pri nt *,’IPX FWSTOP SIG (is tat ) = ’,i wstops ig
pri nt *,’ist at = ’, ipi d
pri nt *,’PXF WAIT istat = ’, ist at
pri nt *,’ire tpid= ’, ire tpi d
endif
els e
pri nt *,’ PXFWIF STO PPE D ret urned FALSE’
print *,’istat = ’, ipi d
print *,’PXF WAIT istat = ’, ist at
print *,’ire tpi d= ’, ire tpi d
pri nt *,’ IPXFWS TOP SIG can not be cal led .’
endif
else
print *,’FAILED: PXF WAI T cal l with err or = ’,i err or
print *,’ist at = ’, ipi d
print *,’istat = ’, istat
pri nt *,’ iretpi d = ’, iretpi d
endif
end if
endif
print *,’ test comple te’
end

SEE ALSO
PXFWAIT(3F), PXFWIFSTOPPED(3F)

176 004– 2165– 002

IPXFWTERMSIG ( 3F ) IPXFWTERMSIG ( 3F )

NAME
IPXFWTERMSIG – Returns lower bit of signal that terminates a child process

SYNOPSIS
INTEGER FUNCTION IPXFWTERMSIG(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The IPXFWTERMSIG integer function returns the lower bits of the signal number that caused the child
process to terminate. The PXFWIFSIGNALED logical function returns TRUE when the child process has
terminated because of a signal. IPXFWTERMSIG should be used only when PXFWIFSIGNALED returns
TRUE.
The following argument is used for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

pro gram pxf test

int ege r ist at, ire tpid, ipid, ierror , ichldi d
int ege r iwt erm sig, IPX FWTERM SIG
log ical lwi fsigna led, PXF WIFSIG NALED

CAL L PXF FOR K(ipid ,ierror)

if (ie rror .ne . 0) the n
pri nt *,’FAI LED: PXFFOR K call fai led with err or = ’,i error
els e

004– 2165– 002 177

IPXFWTERMSIG ( 3F ) IPXFWTERMSIG ( 3F )

print *,’PAS SED: PXF FOR K cal l’

if (ipid .eq . 0) the n
cal l PXF GET PID(ichld id, ier ror )
if( ierror .ne . 0) the n
print *, ’PX FGE TPI D FAI LED , ier ror=’, ier ror
print *,’ ich ldi d=’,ic hld id
els e
print *, ’PX FGE TPID PASSED ’
end if
cal l PXFCON ST("SI GKI LL" ,isig, ier ror )
if( ierror .ne. 0) then
pri nt *, ’PXFCO NST FAILED , ier ror =’, ier ror
pri nt *,’ isig=’ ,is ig
els e
pri nt *, ’PXFCO NST PASSED ’
end if
cal l PXFKIL L(ichl did ,is ig,ier ror )
if( ierror .ne. 0) then
pri nt *, ’PXFKI LL FAI LED , ier ror=’, ier ror
pri nt *,’ ichldi d=’ ,ic hld id
pri nt *,’ isig=’ ,is ig
els e
print *, ’PX FKI LL PASSED ’
endif
els e

178 004– 2165– 002

IPXFWTERMSIG ( 3F ) IPXFWTERMSIG ( 3F )

CALL PXFWAI T(i sta t,i ret pid,ie rro r)

if (ie rror .eq . 0) the n
pri nt *,’PAS SED : PXF WAI T tes t’
lwi fsi gnaled = PXF WIF SIGNAL ED( ist at)
if (lwifs ign ale d .eq v. .TR UE. ) the n ! exi t nor mal ly
iwt ermsig = IPX FWT ERMSIG (is tat )
if (iwter msi g .ne . 0) the n ! exit(0 ) return ed
pri nt *,’ PXFWIF SIG NAL ED tes t PASSED ’
print *,’ IPX FWT ERMSIG tes t PAS SED’
els e
pri nt *,’ PXFWIF SIG NAL ED tes t PASSED ’
print *,’ IPX FWT ERMSIG tes t FAI LED’
pri nt *,’ PXF WIF SIG NALED ret urn ed FALSE’
pri nt *,’ IPX FWTERM SIG (is tat ) = ’,i wte rmsig
pri nt *,’ ist at = ’,ista t
end if
else
pri nt *,’ PXF WIF SIGNAL ED tes t FAI LED ’
pri nt *,’ PXFWIF SIG NAL ED return ed FAL SE’
pri nt *,’ PXFWAI T ist at = ’, ist at
pri nt *,’ IPXFWE XIT STA TUS can not be cal led .’
end if
els e
print *,’ FAI LED : PXF WAI T cal l ier ror = ’,i err or
print *,’ ist at = ’, ist at
pri nt *,’ ire tpid = ’, ire tpid
end if
endif
end if
pri nt *,’test com plete’
end

SEE ALSO
PXFWAIT(3F), PXFWIFSIGNALED(3F)

004– 2165– 002 179

PXFACCESS ( 3F ) PXFACCESS ( 3F )

NAME
PXFACCESS – Checks the accessibility of a named file

SYNOPSIS
CHARACTER*n path
INTEGER ilen, iamode, ierror
CALL PXFACCESS(path, ilen, iamode, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFACCESS subroutine uses the access(2) system call to check the accessibility of a named file.
The value of iamode indicates specific file permissions. These file permissions are checked against the
current file permissions specified for the file in path. If the iamode permissions are allowed for the file in
path, PXFACCESS returns a zero in ierror. Otherwise, it returns a nonzero value.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
path An input character variable or array element containing the name of a file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling access().
iamode An input integer variable containing the integer value of the symbolic constant for one or more
of the following permissions: R_OK, W_OK, X_OK, or F_OK. An integer value for each of
these symbolic constants is retrieved through the use of PXFCONST or IPXFCONST. The
integer values may be combined through the use of a bitwise inclusive OR function.
ierror An output integer variable that contain zero if the requested access is permitted or nonzero if the
requested access is not permitted.

180 004– 2165– 002

PXFACCESS ( 3F ) PXFACCESS ( 3F )

In addition to the errors returned by the access(2) system call, PXFACCESS may return the following
errors:
EINVAL If ilen is less than 0 or ilen is greater than LEN(path)
ENOMEM If PXFACCESS is unable to obtain memory to copy path.

EXAMPLES

pro gra m tes t

cha rac ter *(12) path
int eger ile n, iam od, ierr
path = ’te stf ile’
iamod = 0
ilen = 0
ierr = 0
call pxfcon st(’R_ OK’ ,ia mod ,ierr)
if (ierr. ne. 0) then
pri nt *,’FAI L: err or fro m pxfcon st R_O K = ’,ierr
els e
pri nt *,’ PAS S: No err or fro m pxf const R_OK = ’
end if
ierr = 0
call pxfacc ess(pa th, ile n,i amod,i err )
if (ierr. ne. 0) then
print *,’FAI L: err or from pxfacc ess = ’,i err
else
print *,’ PAS S: No err or fro m pxf acc ess = ’
endif
end

SEE ALSO
access(2)

004– 2165– 002 181

PXFALARM ( 3F ) PXFALARM ( 3F )

NAME
PXFALARM – Schedule alarm signal

SYNOPSIS
SUBROUTINE PXFALARM(iseconds, isecleft, ierror)
INTEGER iseconds, isecleft, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The PXFALARM subroutine uses the alarm (2) system call to wait iseconds before generating the SIGALRM
signal. If a previous PXFALARM has time remaining, isecleft contains the number of seconds until the
SIGALRM would have been generated.
The following is a list of arguments for this routine:
iseconds Default integer input variable containing the number of real-time seconds to wait before sending
the calling process a SIGALRM signal.
isecleft Default integer output variable containing the number of seconds left until a previous request
would have generated a SIGALRM signal.
ierror Default integer output variable containing the status of zero if PXFALARM was successful.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

NOTES
Replace the subroutine or function reference to alarm() with a subroutine call to PXFALARM.

EXAMPLES

182 004– 2165– 002

PXFALARM ( 3F ) PXFALARM ( 3F )

program pxftes t
intege r ise conds, ise cle ft, ierror

isecon ds = 10
isecle ft = 0
ierror = 0
CALL PXFALA RM( ise conds, ise cleft, ier ror)
if (ie rror .ne. 0) the n
pri nt *,’ FAI LED: PXF ALARM cal l failed wit h error = ’,i error
els e
pri nt *,’PAS SED : PXF ALA RM cal l ret urned no err or’
endif
if (is ecl eft .ne . 0) the n
pri nt *,’ FAI LED: PXF ALARM, ise cleft not zero, =’, ise cleft
end if
end

SEE ALSO
alarm(2)

004– 2165– 002 183

PXFCHDIR ( 3F ) PXFCHDIR ( 3F )

NAME
PXFCHDIR – Changes the current directory to a specified directory

SYNOPSIS
CHARACTER*n path
INTEGER ilen, ierror
CALL PXFCHDIR(path, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCHDIR subroutine uses the chdir(2) system call to change the current working directory to the
specified directory.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
system, all arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk,
default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is
KIND=4.
The following is a list of valid arguments for this subroutine:
path An input character variable or array element containing the new directory.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling chdir().
ierror An output integer variable that contains zero if the current working directory was changed or
nonzero if the change of directories was not made.
In addition to the errors returned by the chdir(2) system call, PXFCHDIR may return the following errors:
EINVAL If ilen is less than 0 or if ilen is greater than LEN(path)
ENOMEM If PXFCHDIR is unable to obtain memory to copy path

184 004– 2165– 002

PXFCHDIR ( 3F ) PXFCHDIR ( 3F )

EXAMPLES

progra m test
cha racter *(1 2) pat h
int eger ile n, ier r
path = ’di r/t estdir ’
ilen = 0
cal l pxf chd ir(pat h,ilen,ie rr)
if (ierr. ne. 0) the n
print *,’ FAIL: error from pxf chdir = ’,ierr
else
print *,’ PASS: No error from pxfchd ir = ’
endif
end

SEE ALSO
chdir(2)

004– 2165– 002 185

PXFCHMOD ( 3F ) PXFCHMOD ( 3F )

NAME
PXFCHMOD – Sets file modes for a named file

SYNOPSIS
CHARACTER*n path
INTEGER ilen, imode, ierror
CALL PXFCHMOD(path, ilen, imode, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCHMOD subroutine uses the chmod(2) function to set file modes for the named file.
The value of imode indicates specific file modes. chmod() changes the current file modes for the named file
in path to the file mode specified in imode.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
system, all arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk,
default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is
KIND=4.
The following is a list of valid arguments for this subroutine:
path Input character variable or array element containing the name of a file.
ilen Input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling chmod().
imode Input integer variable containing the integer value of the symbolic constant for one or more of
the following file modes:
USER READ permissions bit: S_IRUSR
WRITE permissions bit: S_IWUSR
SEARCH/EXECUTE permissions bit: S_IXUSR
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXU

186 004– 2165– 002

PXFCHMOD ( 3F ) PXFCHMOD ( 3F )

GROUP READ permissions bit: S_IRGRP

WRITE permissions bit: S_IWGRP
SEARCH/EXECUTE permissions bit: S_IXGRP
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXG
OTHER READ permissions bit: S_IROTH
WRITE permissions bit: S_IWOTH
SEARCH/EXECUTE permissions bit: S_IXOTH
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXO
SETID Set user ID on execution: S_ISUID
Set group ID on execution: S_ISGID
An integer value for each of these symbolic constants is retrieved through the use of
PXFCONST(3F) or IPXFCONST(3F). The integer values may be combined through
the use of a bitwise inclusive OR function.
ierror Output integer variable that contains zero if the requested file mode bits are set or nonzero if the
requested file mode bits are not set.
In addition to the errors returned by the chmod(2) system call, PXFCHMOD may return the following errors:
EINVAL If ilen < 0 or ilen > LEN(path).
ENOMEM If PXFCHMOD is unable to obtain memory to copy path.

EXAMPLES

progra m tes t
charac ter*(1 2) path
intege r ile n, imod, ierr, imo dr, imo dw
path = ’te stfile ’
imo d = 0
imo dr = 0
imo dw = 0
ilen = 0

004– 2165– 002 187

PXFCHMOD ( 3F ) PXFCHMOD ( 3F )

call pxfcon st(’S_ IRU SR’,im odr ,ie rr)

if (ie rr. ne. 0) the n
pri nt *,’ FAI L: err or fro m pxf con st S_IRUS R = ’,i err
sto p
endif
call pxf con st( ’S_IRO TH’,im odw ,ie rr)
if (ie rr. ne. 0) the n
pri nt *,’ FAI L: err or fro m pxf con st S_IWUS R = ’,i err
sto p
endif
imo d = IOR (imodr ,im odw )
call pxf chm od( path,i len,im od, ier r)
if (ie rr. ne. 0) the n
pri nt *,’FAI L: err or fro m pxf chm od = ’,i err
else
pri nt *,’ PAS S: No error fro m pxf chm od’
endif
end

SEE ALSO
chmod(2)

188 004– 2165– 002

PXFCHOWN ( 3F ) PXFCHOWN ( 3F )

NAME
PXFCHOWN – Changes the owner and group of a file

SYNOPSIS
CHARACTER*n path
INTEGER ilen, iowner, igroup, ierror
CALL PXFCHOWN(path, ilen, iowner, igroup, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCHOWN subroutine uses the chown(2) function to change the owner and group of a file.
The value of iowner and igroup indicates the new values.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
path Input character variable or array element containing the name of a file.
ilen Input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling chown().
iowner Input integer variable containing the integer value for the owner.
igroup Input integer variable containing the integer value for the group.
ierror Output integer variable that contains zero if the group and owner of the file were changed or
nonzero if PXFCHOWN did not change the group and owner.
In addition to the errors returned by the chown(2) system call, PXFCHOWN may return the following errors:
EINVAL If ilen is less than 0 or ilen is greater than LEN(path).
ENOMEM If PXFCHOWN is unable to obtain memory to copy path.

004– 2165– 002 189

PXFCHOWN ( 3F ) PXFCHOWN ( 3F )

EXAMPLES

sub rou tine test (iowne r,igro up)

cha racter *(12) pat h
intege r ile n, iow ner, igr oup , ier r
pat h = ’testf ile’
ile n = 0
call pxfcho wn(pat h,ilen,io wne r,igro up, ierr)
if (ie rr.ne. 0) the n
pri nt *,’ FAIL: error fro m pxfcho wn = ’,i err
els e
pri nt *,’ PASS: No err or fro m pxf chown = ’
end if
end

SEE ALSO
chown(2)

190 004– 2165– 002

PXFCHROOT ( 3F ) PXFCHROOT ( 3F )

NAME
PXFCHROOT – Changes the root directory to a specified directory

SYNOPSIS
CHARACTER*n path
INTEGER ilen, ierror
CALL PXFCHROOT(path, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCHROOT subroutine uses the chroot(2) system call to change the root directory to the specified
directory.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
path Input character variable or array element containing the name of a file.
ilen Input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling chroot().
ierror Output integer variable that contains zero if the root directory was changed to the directory
specified by path or nonzero if the root directory was not changed.
In addition to the errors returned by the chroot(2) system call, PXFCHROOT may return the following
errors:
EINVAL If ilen is less than 0 or if ilen is greater than LEN(path)
ENOMEM If PXFCHROOT is unable to obtain memory to copy path

004– 2165– 002 191

PXFCHROOT ( 3F ) PXFCHROOT ( 3F )

EXAMPLES

pro gram test

charac ter*(1 2) pat h
intege r ile n, ier r
pat h = ’/dir/ test’
ile n = 0
cal l pxf chroot (path, ilen,i err)
if (ierr. ne.0) the n
pri nt *,’ FAIL: error fro m pxf chr oot = ’,i err
els e
pri nt *,’ PASS: No err or fro m pxfchr oot ’
end if
end

SEE ALSO
chroot(2)

192 004– 2165– 002

PXFCLEARENV ( 3F ) PXFCLEARENV ( 3F )

NAME
PXFCLEARENV – Clears all environment variables

SYNOPSIS
SUBROUTINE PXFCLEARENV (ierror)
INTEGER ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The subroutine PXFCLEARENV removes all environment variables for the current process.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following argument is used with this subroutine:
ierror An output integer variable that contains a status of zero if all environment variables were cleared.

EXAMPLES
This example shows how to use the PXFCLEARENV routine to clear the environment variable for the current
process.
pro gra m pxf test
int ege r ier ror
CALL PXF CLE ARENV( ierror )
if (ie rror .eq. 0) the n
pri nt *,’ PASSED: pxf clearenv tes t’
els e
pri nt *,’ FAILED : pxfcleare nv test’
end if
end

004– 2165– 002 193

PXFCLEARENV ( 3F ) PXFCLEARENV ( 3F )

This example may display:

PAS SED: pxfcle arenv tes t

194 004– 2165– 002

PXFCONST ( 3F ) PXFCONST ( 3F )

NAME
PXFCONST, PXFISCONST, IPXFCONST – Returns the value associated with symbolic constants

SYNOPSIS
CHARACTER*(n) constname
INTEGER ival, ierror
LOGICAL PXFISCONST, 1
i = IPXFCONST (constname)
l = PXFISCONST (constname)
CALL PXFCONST (constnam, ival, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
These functions provide a way for the Fortran programmer to get the value of some symbolic constants
defined in system header files.
IPXFCONST() provides an integer return value but no error checking. If the argument passed corresponds to
one of the defined constants shown below, the return value is the integer value associated with the constant;
if the argument is not a defined constant, the return value is meaningless. PXFISCONST() confirms whether
the argument is a valid constant. PXFISCONST() returns .TRUE only if IPXFCONST() would return a
valid value for the same constname.
Upon successful completion, the subroutine PXFCONST() returns in ival the integer value associated with the
constant described by constname.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for these subroutines:
constname An input character variable that represents the name of a constant. constname is case-sensitive,
and trailing blanks in the argument are ignored.
The following are valid values for constname. The second column contains the system header
file where the symbolic constant is defined, or the standard where it is defined.
’F_GETLK’ <fcntl.h>

004– 2165– 002 195

PXFCONST ( 3F ) PXFCONST ( 3F )

’F_SETLK’ <fcntl.h>
’F_SETLKW’ <fcntl.h>
’F_RDLCK’ <fcntl.h>
’F_WRLCK’ <fcntl.h>
’F_UNLCK’ <fcntl.h>
’F_DUPFD’ <fcntl.h>
’F_GETFD’ <fcntl.h>
’F_SETFD’ <fcntl.h>
’F_GETFL’ <fcntl.h>
’F_SETFL’ <fcntl.h>
’F_SETSB’* <fcntl.h>
’F_SETALF’* <fcntl.h>
’F_CLRALF’* <fcntl.h>
’O_RDONLY’ <fcntl.h>
’O_WRONLY’ <fcntl.h>
’O_RDWR’ <fcntl.h>
’O_ACCMODE’ <fcntl.h>
’O_NDELAY’ <fcntl.h>
’O_APPEND’ <fcntl.h>
’O_SYNC’ <fcntl.h>
’O_NONBLOCK’ <fcntl.h>
’O_RAW’* <fcntl.h>
’O_SSD’* <fcntl.h>
’O_CREAT’ <fcntl.h>
’O_TRUNC’ <fcntl.h>
’O_EXCL’ <fcntl.h>
’O_NOCTTY’ <fcntl.h>
’0_BIG’* <fcntl.h>
’O_PLACE’* <fcntl.h>
’O_RESTART’* <fcntl.h>
’O_ASYNC’* <fcntl.h>

196 004– 2165– 002

PXFCONST ( 3F ) PXFCONST ( 3F )

’O_PTYIGN’* <fcntl.h>
’O_SFSXOP’* <fcntl.h>
’O_LDRAW’* <fcntl.h>
’O_WELLFORMED’* <fcntl.h>
’O_SFS_DEFER_TM’* <fcntl.h>

’S_ALF_NOGROW’* <sys/stat.h>
’S_ALF_PARTR’* <sys/stat.h>

’SEEK_SET’ <stdio.h>
’SEEK_CUR’ <stdio.h>
’SEEK_END’ <stdio.h>

’STDIN_FILENO’ POSIX.9
’STDOUT_FILENO’ Posix.9
’STDERR_FILENO’ Posix.9
* = UNICOS and UNICOS/mk systems only
Posix.9 specific errors:
’ENONAME’ liberrno.h
’ENOHANDLE’ liberrno.h
Errnos 1– 98 from <errno.h>, for example: ’EPERM’
Cray implementation errors:
EBADID If the idirid argument is an invalid directory ID
EBADHANDLE If the handle is invalid
Additional values for constname are described in descriptions of other PXF routines such as
PXFACCESS, PXFCHMOD, PXFCREAT, PXFOPEN, and so on.
ival An output integer variable. The value associated with the constant.
ierror An output integer variable. It contains the exit status.

EXIT STATUS
Upon successful completion, the argument ierror is set to 0. If any of the following conditions occur,
PXFCONST() sets ierror to the corresponding value.
ENONAME Invalid constant name
ENOMEM PXFCONST() could not allocate the memory required

004– 2165– 002 197

PXFCONST ( 3F ) PXFCONST ( 3F )

SEE ALSO
PXFACCESS(3F), PXFCHMOD(3F), PXFCREAT(3F)

198 004– 2165– 002

PXFCREAT ( 3F ) PXFCREAT ( 3F )

NAME
PXFCREAT – Creates a new file or rewrites an existing file

SYNOPSIS
CHARACTER*n path
INTEGER ilen, imode, ifildes, ierror
CALL PXFCREAT(path, ilen, imode, ifildes, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCREAT subroutine uses the creat(2) system call to create a new file or rewrite an existing file.
The call is similar to PXFOPEN with an iopenflag argument of O_WRONLY, O_CREAT, and O_TRUNC.
The value of imode indicates specific file modes. If the file exists, imode is ignored. The mode values are
used when path is a new file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
path An input character variable or array element containing the name of a file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling creat().
imode An input integer variable containing the integer value of the symbolic constant for one or more
of the following file modes:
USER READ permissions bit: S_IRUSR
WRITE permissions bit: S_IWUSR
SEARCH/EXECUTE permissions bit: S_IXUSR
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXU

004– 2165– 002 199

PXFCREAT ( 3F ) PXFCREAT ( 3F )

GROUP READ permissions bit: S_IRGRP

WRITE permissions bit: S_IWGRP
SEARCH/EXECUTE permissions bit: S_IXGRP
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXG
OTHER READ permissions bit: S_IROTH
WRITE permissions bit: S_IWOTH
SEARCH/EXECUTE permissions bit: S_IXOTH
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXO
SETID Set user ID on execution: S_ISUID
Set group ID on execution: S_ISGID
An integer value for each of these symbolic constants is retrieved through the use of PXFCONST
or IPXFCONST. The integer values may be combined through the use of a bitwise inclusive OR
function.
ifildes An output integer variable containing the file descriptor returned by creat().
ierror An output integer variable that contains zero if the file is created or rewritten or nonzero if
PXFCREAT is not successful.
In addition to the errors returned by the creat(2) system call, PXFCREAT may return the following errors:
EINVAL If ilen < 0 or ilen > LEN(path)
ENOMEM If PXFCREAT is unable to obtain memory to copy path

EXAMPLES

200 004– 2165– 002

PXFCREAT ( 3F ) PXFCREAT ( 3F )

progra m tes t
charac ter *(12) path
int ege r ilen, imod, ifi lde , ier r
int ege r imo dru , imo dwu , imo dwg, imodrg
int ege r ier r1, ierr2, ierr3, ier r4
pat h = ’testf ile ’
imod = 0
ile n = 0
call pxfcon st(’S_ IRU SR’ ,imodr u,i err 1)
cal l pxf const( ’S_IWU SR’ ,im odw u,ierr 2)
cal l pxf const( ’S_IRG RP’ ,im odr g,ierr 3)
cal l pxf const( ’S_IWG RP’ ,im odw g,ierr 4)
imo d = IOR((I OR( imodru,im odw u)) ,(I OR(imo drg ,imodw g)) )
cal l pxf cre at( path,i len,im od, ifilde ,ierr)
if (ie rr. ne.0) then
pri nt *,’ FAIL: err or from pxfcre at = ’,i err
els e
pri nt *,’ PASS: No err or fro m pxf creat = ’
end if
end

SEE ALSO
creat(2), PXFCONST(3F)

004– 2165– 002 201

PXFCTERMID ( 3F ) PXFCTERMID ( 3F )

NAME
PXFCTERMID – Generates terminal pathname

SYNOPSIS
SUBROUTINE PXFCTERMID (s, ilen, ierror)
CHARACTER*n s
INTEGER ilen, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFCTERMID subroutine uses the ctermid function to generate a string which is the pathname for the
current process’ controlling terminal. If the pathname for the controlling terminal cannot be determined, the
ilen variable is set to zero.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
s An output character array or character element variable for the pathname for the current process’
controlling terminal. The maximum length of s is defined by the L_ctermid constant found in
<stdio.h>.
ilen An output interger variable for the length of s.
ierror An output integer variable for the completion status of PXFCTERMID. ierror may contain zero if
PXFCTERMID was successful or nonzero if PXFCTERMID was not successful.
PXFCTERMID may return the ETRUNC error value if the output variable s cannot contain the pathname for
the current process’ controlling terminal, causing the pathname to be truncated.

202 004– 2165– 002

PXFCTERMID ( 3F ) PXFCTERMID ( 3F )

EXAMPLES

pro gram pxf test

int eger ile n, ier ror
cha racter *20 s

CALL PXFCTE RMI D(s,il en,ier ror)

pri nt *,’ con trolli ng termin al is ’,s
end

SEE ALSO
ctermid(3S) on IRIX systems
ctermid(3C) on UNICOS and UNICOS/mk systems

004– 2165– 002 203

PXFDIRECTORY ( 3F ) PXFDIRECTORY ( 3F )

NAME
PXFOPENDIR, PXFREADDIR, PXFREWINDDIR, PXFCLOSEDIR, – Performs directory operations

SYNOPSIS
SUBROUTINE PXFOPENDIR (dirname, lendirname, iopendirid, ierror)
CHARACTER*n dirname
INTEGER lendirname, iopendir, ierror
SUBROUTINE PXFREADDIR (idirid, jdirent, ierror)
INTEGER idirid, jdirent, ierror
SUBROUTINE PXFREWINDDIR (idirid, ierror)
INTEGER idirid, ierror
SUBROUTINE PXFCLOSEDIR (idirid, ierror)
INTEGER idirid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFOPENDIR subroutine uses the opendir(3C) routine to open a directory stream for the directory
dirname and positions the stream at the first directory entry.
The PXFREADDIR subroutine uses the readdir(3C) function to read a directory stream for the next entry
in the directory stream.
The PXFREWINDDIR subroutine uses the rewinddir(3C) function to reset the position in the directory
stream to the first entry of a directory stream while updating the directory stream to the current state of the
directory, as a call to PXFOPENDIR would do.
The PXFCLOSEDIR subroutine uses the closedir(3C) function to close the directory stream referenced
by idirid. Upon sucessful completion, idirid is undefined and the result of subsequent calls to
PXFCLOSEDIR with idirid is not well defined.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.

204 004– 2165– 002

PXFDIRECTORY ( 3F ) PXFDIRECTORY ( 3F )

The following is a list of valid arguments for these subroutines:

dirname An input character array variable containing the path for the directory to be opened.
lendirname An input integer variable containing the length of dirname.
iopendirid An output integer variable for the unique directory ID.
ierror An output integer variable that contains zero if the operation was successful or nonzero if the
operation was not successful.
The iopendirid argument becomes the unique directory ID (idirid) that is used by PXFREADDIR,
PXFREWINDDIR, and PXFCLOSEDIR.
idirid An input integer variable for the unique directory ID generated by PXFOPENDIR.
jdirent An output structure handle created by PXFSTRUCTCREATE(3F) that contains one directory entry.
• The PXFOPENDIR subroutine may return any of the following error values:
EACCES If a component of dirname denies search permission.
ENAMETOOLONG
If the length of the dirname argument exceeds PATH_MAX found in <limits.h> (IRIX
systems only).
ENOENT If the directory in the dirname argument does not exist.
ENOTDIR If a component of dirname is not a directory.
EINVAL If lendirname < 0 or lendirname > LEN(dirname).
ENOMEM If memory needed by PXFOPENDIR could not be allocated.
EMFILE If too many file descriptors are currently open for the process.
ENFILE If too many file descriptors are currently open for the system (IRIX systems only).
• The PXFREADDIR subroutine may return any of the following error values:
EBADF If, when detected, an invalid, unique directory stream ID was used for idirid.
EEND If the end of the directory stream has been reached.
ENOMEM If data structures need for successful completion of PXFREADIR cannot be allocated.
ENOENT If the current file pointer for the directory stream is not located at a valid directory entry.
EDIRCORRUPTED
If the directory on disk is corrupt (IRIX systems only).
EBADID If idirid is an invalid directory identifier (UNICOS and UNICOS/mk systems only).
EBADHANDLE
If jdirent is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).
• The PXFCLOSEDIR subroutine may return the following error value:

004– 2165– 002 205

PXFDIRECTORY ( 3F ) PXFDIRECTORY ( 3F )

EBADF If, when detected, an invalid, unique directory stream ID was used for idirid.

EXAMPLES
In this example, the /dev/dsk directory is opened, the directory entries are read and printed, the directory
is rewound and the contents are redisplayed, and then the directory is closed.
program pxftes t
integer ierror
integer (KIND=8) jdi rent,idirid

CAL L PXF STR UCTCRE ATE(’d ire nt’,jdire nt, ierror )

CALL PXFOPE NDI R(’/de v/d sk’,0, idirid,ierro r)
call printd ir( idirid ,jd ire nt)
CALL PXFREW IND DIR(id iri d,ierr or)
call printd ir( idirid ,jd ire nt)
CALL PXFCLO SED IR(idi rid ,ierro r)
end

subrou tin e pri ntdir( idi rid,jd irent)

int ege r ier ror, ilen, EEN D
intege r (KI ND= 8) jdi ren t, idi rid
cha racter *30 nam e

CAL L PXF CONST( ’EE ND’,EE ND,ierror )

do whi le ((ierr or .ne. EEND) .an d. (ierror .eq. 0))
CAL L PXF REA DDIR(i dir id, jdirent,i error)
CAL L PXF STRGET (jd irent, ’d_name’,nam e,ilen,ierro r)
if (ierro r .eq . 0) pri nt *,name
end do
end

SEE ALSO
directory(3C)

206 004– 2165– 002

PXFESTRGET ( 3F ) PXFESTRGET ( 3F )

NAME
PXFESTRGET – Accesses a single string element of a structure component that is an array

SYNOPSIS
SUBROUTINE PXFESTRGET (jhandle, compnam, index, value, ilen, ierror)
INTEGER jhandle, index, ilen, ierror
CHARACTER*n compnam, value

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFESTRGET routine returns a string contained in a single element of a structure component that is an
array.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
jhandle An input handle variable created with PXFSTRUCTCREATE(3F).
compnam An input character variable or array element containing the desired structure component name.
index An input integer variable for the desired index in the array.
value An output character variable or array element that will contain the string referenced by
companm, index, and jhandle.
ilen An output integer variable for the length of the returned character string.
ierror An output integer variable that contains zero if PXFESTRGET was successful or nonzero if
PXFESTRGET was not successful.
The PXFESTRGET subroutine may return any of the following error values:
ENONAME If the component name is not defined for this structure.

004– 2165– 002 207

PXFESTRGET ( 3F ) PXFESTRGET ( 3F )

ETRUNC If the declared length of the character argument is insufficient to contain the string to be
returned.
ENOMEM If there is insufficent memory to create data structures needed by the routine.
EBADHANDLE
If jhandle is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES
In this example, PXFGETGRGID(3F) and PXFGETGID(3F) are used to obtain the first user name in the
current process’ group.
pro gra m pxf tes t
int ege r igi d, ier ror , jgr oup , len , ima x, i
cha rac ter *30 log inn ame
CAL L PXF STR UCT CRE ATE (’g rou p’, jgr oup ,ie rro r)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF STR UCT CRE ATE wit h err or = ’,i err or
els e
CAL L PXF GET GID (ig id, ier ror )
CAL L PXF GET GRG ID( igi d,j gro up, ier ror )
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF GET GRG ID wit h err or = ’,i err or
els e
CAL L PXF INT GET (jg rou p,’ gr_ nme m’, ima x,i err or)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF INT GET wit h err or = ’,i err or
els e
if (im ax .gt . 0) the n
do i = 1,i max
CAL L PXF EST RGE T(j gro up, ’gr _me m’, i,l ogi nna me, len ,ie rro r)
pri nt *,l ogi nna me
end do
els e
pri nt *,’ FAI LED : Cou ld not tes t PXF EST RGE T’
end if
end if
end if
end if
end

SEE ALSO
PXFSTRUCTCREATE(3F)

208 004– 2165– 002

PXFEXECV ( 3F ) PXFEXECV ( 3F )

NAME
PXFEXECV, PXFEXECVE, PXFEXECVP – Executes a new process image file

SYNOPSIS
SUBROUTINE PXFEXECV (path, lenpath, argv, lenargv, iargc, ierror)
INTEGER lenpath, lenargv(0:iargc-1), iargc, ierror
CHARACTER*n path, argv(0:iargc-1)
SUBROUTINE PXFEXECVE (path, lenpath, argv, lenargv, iargc, env, lenenv, ienvc, ierror)
INTEGER lenpath, lenargv(0:iargc-1), iargc, lenargv, ienvc, ierror
CHARACTER*n path, argv(0:iargc-1) env(ienvc)
SUBROUTINE PXFEXECVP (file, lenfile, argv, lenargv, iargc, ierror)
INTEGER lenfile, lenargv(0:iargc-1), iargc, ierror
CHARACTER*n file, argv(0:iargc-1)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFEXECV routine uses the execv(2) system call to replace the current process image with a new
process image.
The PXFEXECVE routine uses the execve(2) system call to replace the current process image with a new
process image. The environment variables are not inherited from the calling process image. The
environment variables for the new process image are specified by the env argument.
The PXFEXECVP routine uses the execvp(2) system call to replace the current process image with a new
process image.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for these routines:
path An input character variable or array element containing the pathname of the new process image
file.
lenpath An input integer variable for the length of path. If lenpath is zero, trailing blanks are removed.

004– 2165– 002 209

PXFEXECV ( 3F ) PXFEXECV ( 3F )

file An input character variable or array element containing the file of the new process image file. If
file contains a slash character, file will be used as the pathname for the new process image file.
Otherwise, the directories listed in the PATH environment variable are searched using each
directory in path as a pathname prefix for file.
lenfile An input integer variable for the length of file. If lenfile is zero, trailing blanks are removed.
argv An input array of character strings. argv contains the arguments to be passed to the new process
image.
lenargv An input array of integers. Each element in lenargv contains the length of the corresponding
character string in argv. If an element in lenargv is zero, the corresponding element in argv has
all trailing blanks stripped.
iargc An input integer variable. iargc contains the number of arguments to pass to the new process
image.
env An input array of character strings. env contains the environment variables for the new process
image.
lenenv An input array of integers. Each element in lenenv contains the length of the corresponding
character string in env. If an element in lenenv is zero, the corresponding element in env will
have all trailing blanks stripped.
ienvc An input integer variable. ienvc contains the number of environment variables for the new
process image.
ierror An output integer variable that contains zero if the routine was successful or nonzero if the
routine was not successful.
The following values may be returned:
EACCES If the new process file is not a regular file, the new process image file mode denies execution
permission, or search permission is denied for a directory listed in the new process image
file’s path prefix.
ENOENT If one or more components of the new process image file’s path name do not exist.
ENOEXEC If the new process image file has the appropriate access permission but an invalid magic
number in its header.
ENOMEM If the memory needed to create structures used by the routine could not be allocated.
EINVAL If lenpath < 0 or lenpath > LEN(path) or any element of lenargv is less than zero or greater
than the length of the corresponding element in argv.

UNICOS and UNICOS/mk only errors:

E2BIG If the number of bytes in argv is greater than the system-imposed limit of ARG_MAX found in
<limits.h>.

210 004– 2165– 002

PXFEXECV ( 3F ) PXFEXECV ( 3F )

EDMOFF If the process image file is offline, and the data migration facility is not configured in the
system.
EFAULT If the new process image file is not as long as indicated by the size values in its header.
ENOMEM If the new process requires more memory than is allowed by the system-imposed maximum
MAXMEM.
EOFFLIN If the process image file is offline, and automatic file retrieval is disabled.
EOFLNDD If the file is offline, and the data management daemon is not currently executing.
EOFLNNR If the file is offline, and it is currently unretrievable.

IRIX 6.2 only errors:

E2BIG If the number of bytes in the new process’s argument list is greater than the system-imposed
limit ARG_MAX (see sysconf(2), intro(2), and limits.h). The argument list limit is
the sum of the size of the argument list plus the size of the environment’s exported shell
variables.
E2BIG If the number of bytes in the first line of an interpreter file is greater than 256 bytes.
EAGAIN If there is not enough memory.
ELIBACC If the required shared library does not have execute permission.
ELIBEXEC If path points to a shared library.
ELIBMAX If the required number of shared libraries exceeds the system imposed maximum SHLIB_MAX
(see intro(2)).
ELOOP If too many symbolic links were encountered in translating path.
ENAMETOOLONG
If the length of path exceeds PATH_MAX found in <limits.h>, or the length of a path
component exceeds NAME_MAX found in <limits.h> while POSIX_NO_TRUNC is in
effect.
ENOEXEC If the executable process image file has badly formed header information or the requested
virtual addresses are not available.
ENOMEM If the new process image requires more virtual space than is allowed either by the system-
imposed maximum or the process imposed maximum PROCSIZE_MAX (see getrlimit(2)
and intro(2)).
EPERM If a non-superuser tries to execute a setuid file that belongs to some other user and the file
system in which the file resides has been mounted with the nosuid option (see fstab(4)),
or if a non-superuser attempts to execute a setuid or setgid shell script with a UID or GID that
is different than the user’s effective UID/GID, and the configured value for
no–suid–shells is non-zero (the default) (see intro(2) and lboot(1M)).

004– 2165– 002 211

PXFEXECV ( 3F ) PXFEXECV ( 3F )

EXAMPLES

PXFEXECV example:
In this example, the program forks and the child calls PXFEXECV to execute the /bin/grep process image
file. The parent process waits for the child to finish executing and then forks again. The child from the
second fork also calls PXFEXECV to execute the /bin/grep process image file. The parent then waits for
the child to finish executing.
pro gram test
intege r ipi d, ier ror, len path, len argv(3), iar gc, iretpid
intege r ist at
charac ter*30 path, argv(3 )

pat h = ’/bin/ grep’

len path = 0
iargc = 3
argv(1 ) = ’gr ep’
lenarg v(1) = 0
argv(2 ) = ’ro ot’
lenarg v(2) = 0
arg v(3 ) = ’/etc/ pas swd ’
len arg v(3) = 0

CAL L PXF FORK(i pid ,ierro r)

if (ie rror .ne. 0) the n
print *,’FAI LED : PXFFOR K call wit h error = ’,ierr or
els e
if (ip id .eq . 0) then
print *,’CHI LD1: exe cing gre p’
CALL PXFEXE CV(path, lenpat h, arg v, lenargv, iar gc, ierror)
pri nt *,’ FAI LED: PXF EXEC cal l with err or = ’,i error
sto p
else
print *,’PAR ENT: wai tin g for CHILD1 ’
CAL L PXF WAI T(ista t,i ret pid,ie rro r)
print *,’PAR ENT: CHI LD1 finish ed. Forkin g off CHILD2 ’
CAL L PXF FORK(i pid, ier ror)
if (ipid .eq . 0) the n
pri nt *,’ CHILD2 : exe cin g gre p’
CAL L PXF EXECV(pat h, lenpat h, argv, len arg v, iargc, ier ror)
pri nt *,’ FAI LED PXFEXE C call wit h error = ’,ierr or
sto p
else

212 004– 2165– 002

PXFEXECV ( 3F ) PXFEXECV ( 3F )

print *,’PAR ENT: waitin g for CHI LD2 ’

CALL PXF WAI T(i sta t,i ret pid,ie rro r)
pri nt *,’ PARENT : CHI LD2 fin ished. ’
pri nt *,’ PAS SED : PXF EXECV normal test’
end if
endif
end if
end

PXFEXECVE example:
In this example, the program forks and the child calls PXFEXECVE to execute the /bin/grep process
image file. The parent process waits for the child to finish executing and then forks again. The child from the
second fork also calls PXFEXECVE to execute the /bin/grep process image file. The parent then waits for
the child to finish executing.
intege r ipid, ierror , len pat h, lenarg v(3 ), iargc, ire tpi d
intege r ist at, err orc onditi on, lenenv (3) , ien vc
charac ter *30 path, arg v(3 )
charac ter *30 env(3)

pat h = ’/bin/grep’
len path = 0
iar gc = 3
argv(1) = ’grep’
lenarg v(1) = 0
argv(2 ) = ’root’
len argv(2 ) = 0
arg v(3) = ’/etc/pas swd’
lenarg v(3) = 0
ienvc = 3
env (1) = ’TERM=vt1 00’
lenenv (1) = 0
env (2) = ’SHELL=/bin/ csh ’
lenenv (2) = 0
env (3) = ’DISPLAY= :0. 0’
lenenv (3) = 0

CAL L PXFFORK(ipid,ie rror)

if (ierro r .ne. 0) then
print *,’FAILED: PXFFOR K cal l wit h err or = ’,ierr or
else
if (ipid .eq. 0) then
print *,’CHILD1 : exe cin g gre p’
CAL L PXFEXE CV( path, lenpat h, arg v, lenarg v, iar gc, ier ror )

004– 2165– 002 213

PXFEXECV ( 3F ) PXFEXECV ( 3F )

print *,’FAI LED: PXF EXEC call with error = ’,i err or
stop
els e
pri nt *,’ PARENT : waitin g for CHILD1 ’
CAL L PXFWAIT(istat,i ret pid ,ie rror)
print *,’PAR ENT: CHI LD1 fin ished. For king off CHI LD2 ’
CAL L PXFFOR K(ipid , ierror )
if (ipid .eq. 0) the n
pri nt *,’ CHILD2 : execin g gre p’
CALL PXF EXECV( path, lenpat h, arg v, len argv, iar gc, ier ror )
print *,’FAI LED PXF EXEC call with error = ’,i err or
stop
els e
pri nt *,’PARENT : wai tin g for CHI LD2 ’
CAL L PXFWAI T(ista t,i ret pid,ie rro r)
print *,’PAR ENT: CHI LD2 fin ish ed. ’
print *,’PASSED : PXF EXE CVP nor mal tes t’
endif
end if
end if
end

PXFEXECVP example:
In this example, the program forks and the child calls PXFEXECVP to execute the grep process image file.
The parent process waits for the child to finish executing and then forks again. The child from the second
fork also calls PXFEXECVP to execute the grep process image file. The parent then waits for the child to
finish executing.
pro gra m tes t
int eger ipi d, ier ror, len file, len argv(3 ), iar gc, ire tpi d
integer istat
charac ter *30 file, argv(3 )

file = ’gr ep’

len file = 0
iar gc = 3
arg v(1 ) = ’grep’
lenarg v(1) = 0
arg v(2) = ’root’
len argv(2 ) = 0
argv(3 ) = ’/etc/ passwd ’
lenarg v(3 ) = 0

214 004– 2165– 002

PXFEXECV ( 3F ) PXFEXECV ( 3F )

CAL L PXF FOR K(ipid ,ierro r)

if (ierro r .ne . 0) the n
print *,’ FAI LED: PXFFOR K cal l wit h err or = ’,ierr or
els e
if (ip id .eq. 0) then
pri nt *,’ CHILD1 : execin g gre p’
CAL L PXF EXE CVP(fi le, lenfil e, arg v, lenarg v, iar gc, ierror )
pri nt *,’ FAILED : PXF EXE C cal l wit h err or = ’,i error
sto p
els e
pri nt *,’PAR ENT: wai tin g for CHI LD1 ’
CALL PXF WAIT(i sta t,i ret pid ,ierro r)
pri nt *,’PAR ENT: CHI LD1 fin ish ed. For kin g off CHILD2 ’
CAL L PXF FORK(i pid , ier ror )
if (ipid .eq. 0) the n
pri nt *,’ CHILD2 : exe cin g gre p’
CAL L PXFEXE CVP(fi le, len fil e, argv, lenarg v, iargc, ier ror )
pri nt *,’ FAI LED PXF EXE C cal l wit h err or = ’,i error
sto p
else
pri nt *,’ PAR ENT : wai ting for CHI LD2 ’
CALL PXFWAI T(i sta t,i retpid ,ie rro r)
pri nt *,’ PARENT : CHI LD2 fin ish ed. ’
pri nt *,’PAS SED: PXF EXE CVP nor mal tes t’
endif
end if
endif
end

SEE ALSO
execv(2)

004– 2165– 002 215

PXFFCNTL ( 3F ) PXFFCNTL ( 3F )

NAME
PXFFCNTL – Provides a subset of fcntl(2) functionality, except the third argument is always an integer

SYNOPSIS
INTEGER ifildes, icmd, iargin, iargout, ierror
CALL PXFFCNTL (ifildes, icmd, iargin, iargout, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFFNCTL() subroutine provides a subset of the functionality of fcntl(2), except that the third
argument is always an integer.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The arguments for PXFFNCTL() are:
ifildes An open file descriptor. ifildes is an input integer variable.
icmd An input integer variable. Specifies the action for fcntl to perform, as described on the
fcntl(2) man page. The constant values for use in specifying icmd are available through calls
to PXFCONST(3F). The following values are currently supported for icmd:
F_CLRA LF*
F_DUPF D
F_GETF D
F_GETF L
F_GETL K
F_SETA LF*
F_SETF D
F_SETF L
F_SETS B*
F_SETL K
F_SETL KW

216 004– 2165– 002

PXFFCNTL ( 3F ) PXFFCNTL ( 3F )

* = UNICOS and UNICOS/mk systems only

iargin An input integer variable. As described below, iargin may also be an output variable. iargin
can be a handle for an instance of the flock structure or an integer, depending on the argument
icmd under the conditions defined in POSIX.1.
If icmd is F_GETLK, F_SETLK, or F_SETLKW, then iargin is a handle for an instance of the
flock structure. This handle should be created by a call to the PXFSTRUCTCREATE()
subroutine, with the string flock given as the STRUCTNAME argument. The components are then
accessed with the subroutines PXFINTSET() and PXFINTGET(), as shown following:
Components for flock structure:

Posix.1 component COMPNAM Structure procedures used to access

l_type l_type PXFINTGET, PXFINTSET

l_whence l_whence PXFINTGET, PXFINTSET
l_start l_start PXFINTGET, PXFINTSET
l_len l_len PXFINTGET, PXFINTSET
l_pid l_pid PXFINTGET, PXFINTSET

If icmd is F_GETLK, the retrieved information overwrites the information described in the
handle used as the iargin argument.
iargout An output integer variable. The value returned in iargout depends on the icmd argument. See
fcntl() for more information.
ierror An output integer variable. It contains the exit status.

EXIT STATUS
Upon successful completion of PXFFCNTL(), the argument ierror is set to 0. If any of the following
conditions occur, ierror is set to the corresponding value:
EINVAL icmd is not valid.
EINVAL icmd is F_GETLK, F_SETLK, or F_SETLKW and iargin is not a valid handle.
errno The fcntl(2) system call failed.
EBADHANDLE iargin, when icmd is F_GETLK, F_SETLK, or F_SETLKW, is an invalid handle or has an
incorrect handle type for this routine.

SEE ALSO
PXFCONST(3F), PXFSTRUCTCREATE(3F), PXFINTGET(3F), PXFINTSET(3F)

004– 2165– 002 217

PXFFILENO ( 3F ) PXFFILENO ( 3F )

NAME
PXFFILENO – Returns the file descriptor for a specified unit

SYNOPSIS
INTEGER IUNIT, IFILDES, IERROR
CALL PXFFILENO (iunit, ifildes, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION

This routine is supported on IRIX systems for programs compiled using the MIPSpro 7 Fortran 90 compiler
or compiled with the -craylibs option to the MIPSpro F77 compiler.
The PXFFILENO() subroutine returns in the ifildes argument the file descriptor to which the unit identified
by iunit is connected.
Processing of some Fortran file types includes library buffering or the addition of control words to the data
written. Users should be aware of this when attempting to make use of the file descriptor associated with a
Fortran unit. Some Fortran units may not be connected to a file descriptor. For example, a file assigned the
attributes -F mr.scr.novfl is not connected to a file descriptor.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments to PXFFILENO:
iunit An input integer variable that contains the Fortran unit number.
ifildes An output integer variable containing the file descriptor of the file identified by iunit.
ierror An output integer variable containing the status.

RETURN VALUES
Upon successful completion of PXFFILENO(), ierror is set to 0. If any of the following conditions occur,
ierror is set to the corresponding value:
EINVAL iunit is not an open unit
EBADF iunit is not connected with a file descriptor

218 004– 2165– 002

PXFFORK ( 3F ) PXFFORK ( 3F )

NAME
PXFFORK – Creates a process

SYNOPSIS
SUBROUTINE PXFFORK (ipid, ierror)
INTEGER ipid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFFORK routine uses the fork(2) system call to create a new process. The child process is the same
as the parent process except for the following:
• The child process has a unique, currently unused process ID.
• The child process has a different parent process ID. The child process’s process ID is the parent process,
or calling process, ID.
• The child process has its own copy of the parent’s file descriptors. Each of the child’s file descriptors
shares a common file pointer with the corresponding file descriptor of the parent process.
• Process locks are not inherited by the child process (see plock(2)).
• The utime, stime, cutime, and cstime of the child process are set to 0. The time left until an
alarm clock signal is reset to 0.
• All semadj values are cleared (see semop(2)).
• The parent’s set of pending signals are not inherited by the child.
UNICOS and UNICOS/mk systems only:
• Record locks set by the parent process are not inherited by the child process (see fcntl(2) and
lockf(3C)).
• In a multitasking group, only the process that executed the fork system call is copied.
• Each attached shared memory segment is attached and the value of shm_nattch in the data structure
associated with the shared memory segment is incremented by 1.
IRIX systems only:
• File locks previously set by the parent are not inherited by the child (see fcntl(2)).
• Page locks are not inherited (see mpin(2) on IRIX systems).

004– 2165– 002 219

PXFFORK ( 3F ) PXFFORK ( 3F )

• The time left until an itimer signal is reset to 0.

• The child will not inherit the ability to make graphics calls. The child process may receive a
segmentation fault upon attempting to make a graphics call, unless it initializes itself as a graphics
process via winopen() or ginit(). Currently, if the parent is a graphics process, the child’s attempt
to become a graphics process will fail.
• The share mask is set to 0 (see sproc(2)).
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
ipid An output integer variable. ipid will be zero for the child process and the process ID of the child
for the parent process.
ierror An output integer variable that contains zero if PXFFORK was successful or nonzero if PXFFORK
was not successful.
The PXFFORK routine may return any of the following error values:
EAGAIN If the system-imposed limit on the total number of processes under execution in the whole
system (NPROC) is exceeded or if the system-imposed limit on the total number of processes
under execution by one user (CHILD_MAX) is exceeded.
UNICOS and UNICOS/mk systems only:
EBUSY If you attempt to enable accounting when it is already enabled, or if you issue a restart(2)
attempt when another job or process in the system is using the jid or any pid associated with the
job (or process) to be restarted.
EINTR If an asynchronous signal (such as interrupt or quit), which you have elected to catch, occurred
during a fork system call. When execution resumed after processing the signal, the interrupted
system call returned this error condition.
EMEMLIM If more memory space was requested than is allowed for the processes attached to this lnode.
The maximum value is set by the -c option of the shradmin(8) command. This error appears
only on systems running the fair-share scheduler.
ENOEXEC If a request was made to execute a file that, although it has the appropriate permissions, does not
start with a valid magic number (see a.out(5)).
ENOMEM If during an exec(2) or sbreak(2) system call, a program requested more space than the
system could supply. This is not a temporary condition; the maximum space specification is a
system parameter.

220 004– 2165– 002

PXFFORK ( 3F ) PXFFORK ( 3F )

EPROCLIM
If more processes were requested than are allowed for this lnode. The maximum value is set by
the -p option of the shradmin(8) command. This error appears only on systems running the
fair-share scheduler.
IRIX systems only:
EAGAIN If the amount of system memory required is temorarily unavailable.
ENOSPC If the caller is a member of a share group and the total number of share group members plus
child processes exceeds the maximum number of users specified by the usconfig(3P)
command (8 by default). Any changes made with usconfig (3P) must be done Ibeforethe first
sproc is formed.
ENOLCK There are not enough file locks in the system.

EXAMPLES

progra m pxftes t
int eger ipid, ier ror

CALL PXFFORK(i pid , ier ror )

if (ipid .eq . 0) then
print *,’ child’
els e
print *,’ parent ’
end if
end

SEE ALSO
exec(2), fcntl(2), fork(2), plock(2), restart(2), semop(2), sproc(2), ssbreak(2)
shradmin(8)

004– 2165– 002 221

PXFGETARG ( 3F ) PXFGETARG ( 3F )

NAME
PXFGETARG – Returns a command-line argument

SYNOPSIS
CHARACTER*n buf
INTEGER m, ilen, ierror
CALL PXFGETARG(m, buf, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETARG subroutine examines the command line used to invoke the executing program and returns
the mth command-line argument in buf.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
This routine has the following arguments:
m An input integer variable or array element containing the number of the command-line argument to
return in buf. If m is zero, the command name is returned in buf.
buf An output character variable or array element containing the mth command-line argument.
ilen An output integer variable containing the significant length in characters of the string stored in buf.
If the length of the string is shorter than the length of buf, the shorter length is returned. If the
string is longer, the longer length of the string is returned.
ierror An output integer variable containing 0 if a value is returned in buf or containing the following:
EINVAL If m is out of range
ETRUNC if the declared length of buf is insufficient to contain the string to be returned. The
value of the command-line argument is truncated to fit in buf, and ilen is set to the full
length of the original string.

SEE ALSO
IPXFARGC(3F)

222 004– 2165– 002

PXFGETCWD ( 3F ) PXFGETCWD ( 3F )

NAME
PXFGETCWD – Gets the pathname of the working directory

SYNOPSIS
SUBROUTINE PXFGETCWD (buf, ilen, ierror)
CHARACTER*n buf
INTEGER ilen, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETCWD subroutine uses the getcwd() function to get the current working directory.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this subroutine:
buf An output character variable or array element for the current working directory. The longest
pathname cannot be longer than PATH_MAX for the UNICOS operating system, or
MAXPATHLEN for IRIX systems as defined in <sys/param.h>.
ilen An output integer variable containing the character length of buf.
ierror An output integer variable that contains zero if the working directory path was successfully
copied into buf or nonzero if PXFGETCWD was not successful.
The PXFGETCWD subroutine may return any of the following error values:
ETRUNC If the length of buf is less than the complete path length.
EACCESS If read or search permission for any component of the current working directory path was
denied.

004– 2165– 002 223

PXFGETCWD ( 3F ) PXFGETCWD ( 3F )

EXAMPLES
In this example, PXFGETCWD will be called with a large buffer, which should not cause any errors, and then
with a very small buffer, which should cause an error.
pro gram pxftes t
charac ter*10 24 pat h
charac ter*10 toosma llbuff
intege r pat hlen, ierr

CAL L PXF GETCWD (path, pat hle n, ier r)

print *,’ path = ’,p ath,’ - ier r = ’,i err
CALL PXFGET CWD(to osmallbuf f, pathle n, ierr)
pri nt *,’ too smallb uff = ’,t oos mallbu f,’ - ier r = ’,ierr
end

SEE ALSO
getcwd(3C)

224 004– 2165– 002

PXFGETEGID ( 3F ) PXFGETEGID ( 3F )

NAME
PXFGETEGID – Gets the effective group ID

SYNOPSIS
SUBROUTINE PXFGETEGID (iegid, ierror)
INTEGER iegid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETEGID subroutine uses the getegid() function to get the effective group ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine:
iegid An output integer variable for the effective group ID for the current process.
ierror An output integer variable that contains zero if PXFGETEGID was successful.

EXAMPLES
This example calls PXFGETEGID and prints out the current effective group ID and the returned error.
progra m pxftes t
int eger ieg id, ier r

CALL PXFGET EGI D(iegi d,ierr )

pri nt *,’ieg id = ’,i egi d,’ ierr = ’,i err
end

004– 2165– 002 225

PXFGETENV ( 3F ) PXFGETENV ( 3F )

NAME
PXFGETENV – Returns a value for the environment name

SYNOPSIS
SUBROUTINE PXFGETENV (name, lenname, value, lenval, ierror)
CHARACTER*n name, value
INTEGER lenname, lenval, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETENV subroutine uses the getenv() function to search the environment list for a name in a
string of the form name=value.
If name matches a name in the list, the character representation of value is stored in the value character
argument and the number of characters in value is stored in lenval. If the length of the value to be placed in
value is larger than the declared length of value, the value string is truncated on the right and stored in
value. The nontruncated length is stored in lenval and ierror is set to etrunc. If the length of the value is
shorter than the declared size of value, the value string is stored with left justification and filled with blanks
on the right. lenval is set to the shorter length of the value string.
If name is found but has no value, blanks are stored in value and lenval is set to zero. If name cannot be
found, EINVAL is returned in ierror.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
name An input character variable or array element containing the name of an environment variable.
lenname An input integer variable containing the length of name in characters. If lenname is zero, the
trailing blanks are removed. The declared length of the input name is decremented by the
number of blanks removed. If lenname is zero and name is all blanks, the input name is a null
string.
value An output character variable or array element containing the value of the environment variable
name.

226 004– 2165– 002

PXFGETENV ( 3F ) PXFGETENV ( 3F )

lenval An output integer variable containing the length of value in characters. If name is found but has
no value, lenval is zero and value contains all blanks to indicate a null string. If the value
representation is truncated to be stored in value, lenval contains the nontruncated length of value.
If the value representation is shorter than the length of value, lenval contains the shorter length.
ierror An output integer variable containing the status:
EINVAL If name is not in the environment list.
ETRUNC If the declared length of value is insufficient to contain the string to be returned.
The value of name is truncated to fit in value, and lenval contains the original length
of the value of name before truncation.
Zero getenv is successful (if name is found).

EXAMPLES
In this example, PXFGETENV searches for a string containing SHELL=value.
progra m testpx f
cha rac ter*24 namea, nam eb
int ege r len a, lenb, ier
c set input arg uments
ier = 0
lena=0
lenb=0
namea= ’SH ELL’
nam eb= ’ ’
CAL L PXF GET ENV (na mea, lena, nam eb, lenb, ier)
pri nt *,’TES T result s:’
c pri nt input arg uments
pri nt *,’nam ea=-’, namea, ’-’
pri nt *,’len a=’,le na
c pri nt output argume nts
pri nt *,’nam eb=-’, nameb, ’-’
pri nt *,’len b=’,le nb
pri nt *,’ier =’,ier
end

If the string is found, it may return:

TES T res ult s:
namea= -SH ELL
lena=0
nam eb= -/bin/ csh
len b=8
ier =0

004– 2165– 002 227

PXFGETENV ( 3F ) PXFGETENV ( 3F )

SEE ALSO
getenv(3C)

228 004– 2165– 002

PXFGETEUID ( 3F ) PXFGETEUID ( 3F )

NAME
PXFGETEUID – Gets effective user ID

SYNOPSIS
SUBROUTINE PXFGETEUID (ieuid, ierror)
INTEGER ieuid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETEUID subroutine uses the geteuid() system call to get the effective user ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine:
ieuid An output integer variable for the effective user ID for the current process.
ierror An output integer variable that contains zero if PXFGETEUID was successful.

EXAMPLES
This example calls PXFGETEUID and prints out the current effective user ID and the returned error.
pro gram pxf test
intege r ieu id, ierr

CAL L PXF GET EUID(i euid,ierr )

pri nt *,’ ieu id = ’,ieui d,’ ier r = ’,i err
end

004– 2165– 002 229

PXFGETGID ( 3F ) PXFGETGID ( 3F )

NAME
PXFGETGID – Gets the real group ID

SYNOPSIS
SUBROUTINE PXFGETGID (igid, ierror)
INTEGER igid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETGID subroutine uses the getgid() system call to get the real group ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine:
igid An output integer variable for the real group ID for the current process.
ierror An output integer variable that contains zero if PXFGETGID was successful.

EXAMPLES
This example calls PXFGETGID and prints out the current real group ID and the returned error.
pro gram pxftes t
int eger igid, ier r
CAL L PXF GETGID (ig id,ier r)
print *,’ igid = ’,i gid,’ ierr = ’,i err
end

230 004– 2165– 002

PXFGETGRGID ( 3F ) PXFGETGRGID ( 3F )

NAME
PXFGETGRGID – Gets group information using the group ID

SYNOPSIS
SUBROUTINE PXFGETGRGID (igid, jgroup, ierror)
INTEGER igid, jgroup, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETGRGID routine uses the getgrgid(3C) function to obtain group information using a group
ID.
The following are components of the group structure used by PXFGETGRGID and created by calling
PXFSTRUCTCREATE:
• gr_name: Group name
• gr_gid: Group ID
• gr_nmem: Number of group members contained in gr_mem
• gr_mem: Array of group members’ login names
The gr_name component can be accessed by calling PXFSTRGET(3F). gr_gid and gr_nmem can be
accessed by calling PXFINTGET(3F). PXFESTRGET can be used to access the elements of gr_mem.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
igid An input integer variable containing the group ID, for which group information is requested.
jgroup An output handle of type group created with PXFSTRUCTCREATE(3F).
ierror An output integer variable that contains zero if group information was retrieved or nonzero if
PXFGETGRGID was not successful.

004– 2165– 002 231

PXFGETGRGID ( 3F ) PXFGETGRGID ( 3F )

The PXFGETGRGID routine may also return any of the following error values:
ENOENT If igid contains an non-existant group ID.
ENOMEM If memory needed by PXFGETGRGID could not be allocated.
EBADHANDLE
If jgroup is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES
In this example, PXFGETGRGID is called for information about the group with ID = 0.
program pxftes t
integer jgroup
intege r ier ror ,ilen
charac ter *16 nam e

CALL PXF GETGRGID( 0,j group,ierror )

CALL PXFSTR GET (jgrou p,’ gr_nam e’,name,ilen ,ierror)
pri nt *,’gro up nam e for the group with ID= 0 is ’,n ame

end

232 004– 2165– 002

PXFGETGRNAM ( 3F ) PXFGETGRNAM ( 3F )

NAME
PXFGETGRNAM – Gets group information using the group name

SYNOPSIS
SUBROUTINE PXFGETGRNAM (name, ilen, jgroup, ierror)
CHARACTER*n name
INTEGER ilen, jgroup, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETGRNAM routine uses the getgrnam(3C) function to obtain group information using a group
name.
The following are components of the group structure used by PXFGETGRNAM and created by calling
PXFSTRUCTCREATE:
• gr_name: Group name
• gr_gid: Group ID
• gr_nmem: Number of group members contained in gr_mem
• gr_mem: Array of group members’ login names
The gr_name component can be accessed by calling PXFSTRGET(3F). gr_gid and gr_nmem can be
accessed by calling PXFINTGET(3F). PXFESTRGET can be used to access the elements of gr_mem.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
name An input character character variable or array element containing the group name for which
group information is requested.
ilen An input integer variable containing the length of name. If ilen is zero, trailing blanks are
stripped.

004– 2165– 002 233

PXFGETGRNAM ( 3F ) PXFGETGRNAM ( 3F )

jgroup An output handle of type group created with PXFSTRUCTCREATE(3F).

ierror An output integer variable that contains zero if group information was retrieved or nonzero if
PXFGETGRNAM was not successful.
The PXFGETGRNAM routine may also return any of the following error values:
ENOENT If name contains a non-existant group ID.
ENOMEM If memory needed by PXFGETGRNAM could not be allocated.
EINVAL If ilen < 0 or ilen > LEN(name).
EBADHANDLE
If jgroup is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES
In this example, PXFGETGRNAM is called for information about the group users.
program pxftes t
integer jgroup
integer ierror , igid

CALL PXF GETGRNAM( ’us ers’,0,jgrou p,ierror)

CAL L PXF INT GET(jg roup,’ gr_ gid’,igid ,ie rror)
print *,’ group ID for gro up users is ’,igid

end

SEE ALSO
PXFINTGET(3F), PXFSTRGET(3F)

234 004– 2165– 002

PXFGETGROUPS ( 3F ) PXFGETGROUPS ( 3F )

NAME
PXFGETGROUPS – Gets supplementary group IDs

SYNOPSIS
SUBROUTINE PXFGETGROUPS (igidsetsize, igrouplist, ngroups, ierror)
INTEGER igidsetsize, igrouplist(igidsetsize), ngroups, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETGROUPS subroutine uses the getgroups(2) system call to fill igrouplist with a supplemental
group list for the calling process.
As a special case, when igidsetsize is zero, PXFGETGROUPS will return the number of supplemental group
IDs for the calling process in the ngroups variable, leaving the igrouplist variable unchanged.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
igidsetsize An input integer variable containing the size of the igrouplist integer array.
igrouplist An output integer variable or array element that will contain a set of supplemental group IDs
for the calling process. NGROUPS_MAX, found in <sys/param.h> for the UNICOS
operating system and <unistd.h> for IRIX systems, defines the maximum number of
supplemental group IDs for a process.
ngroups An output integer variable that will contain the number of supplemental group IDs for the
calling process.
ierror An output integer variable that contains zero if the variable was changed or nonzero if
PXFGETGROUPS was not successful.
The PXFGETGROUPS routine may return the EINVAL error value if igidsetsize is not equal to zero and is
less than the number of supplementary group IDs.

004– 2165– 002 235

PXFGETGROUPS ( 3F ) PXFGETGROUPS ( 3F )

EXAMPLES
This example finds the number of supplemental group IDs for its process, prints out the number, and then
retrieves the supplemental group IDs and prints each group ID.
progra m pxf tes t
int eger igi dgroup list, igroup list(6 4), ngroup s, ierror, i

c fin d out the num ber of groups

igi dgroup list = 0
CALL PXFGET GROUPS(ig idgrou pli st, igroup list, ngroup s, ier ror)
pri nt *,’ gro ups for proces s = ’,ngro ups ,’ error = ’,ierr or

c cal l pxf getgro ups

igi dgroup lis t = 64
CALL PXFGET GROUPS(ig idg roupli st, igr ouplis t, ngr oups, ierror )
pri nt *,’ groups for pro ces s = ’,ngroups ,’ error = ’,ierror

c pri nt out all gro ups for the pro cess

do i=1,ng roups
print *,’ gid = ’, igr ouplis t(i )
end do

end

This example may return the following results:

groups for pro ces s = 2 error = 0
gro ups for proces s = 2 error = 0
gid = 101 3
gid = 105 33

SEE ALSO
getgroups(2)

236 004– 2165– 002

PXFGETLOGIN ( 3F ) PXFGETLOGIN ( 3F )

NAME
PXFGETLOGIN – Gets user name

SYNOPSIS
SUBROUTINE PXFGETLOGIN (s, ilen, ierror)
CHARACTER*n s
INTEGER ilen, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETLOGIN routine uses the cuserid(3C) function to fill s with the user login name associated
with the calling process.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
s An output character variable or array element for the user’s login name.
ilen An output integer variable containing the length of s.
ierror An output integer variable that contains zero if the user’s login name was successfully acquired
or nonzero if PXFGETLOGIN was unsuccessful.
The PXFGETLOGIN routine may return the ETRUNC error value if the length of s is smaller than the length
of the user’s login name.

EXAMPLES
In this example, PXFGETLOGIN is called and the returned user login name is printed.

004– 2165– 002 237

PXFGETLOGIN ( 3F ) PXFGETLOGIN ( 3F )

pro gra m pxftes t

cha rac ter *16 s
int ege r ile n, ierror

c fin d the use r nam e ass ociate d wit h thi s pro cess
CAL L PXF GET LOGIN( s, ile n, ierror )
pri nt *,’ user name = ’,s,’ len gth = ’,ilen ,’ error = ’,ierror

end

SEE ALSO
cuserid(3C)

238 004– 2165– 002

PXFGETPGRP ( 3F ) PXFGETPGRP ( 3F )

NAME
PXFGETPGRP – Gets the process group ID

SYNOPSIS
SUBROUTINE PXFGETPGRP (ipgrp, ierror)
INTEGER ipgrp, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETPGRP subroutine uses the getpgrp(2) system call to return the process group ID of the
calling process.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
ipgrp An output integer variable that contain the process group ID for the current process.
ierror An output integer variable that contains a status of zero if the process ID was successfully
acquired.

EXAMPLES
In this example, PXFGETPGRP will return the process group ID for the calling process.

004– 2165– 002 239

PXFGETPGRP ( 3F ) PXFGETPGRP ( 3F )

program pxftes t
intege r ipg rp, ierror
CAL L PXF GETPGR P(ipgr p, ier ror)
if (ie rror .eq. 0) the n
print *,’ pgrp = ’,i pgr p
els e
pri nt *,’ error = ’, ier ror
endif
end

SEE ALSO
getpgrp(2)

240 004– 2165– 002

PXFGETPID ( 3F ) PXFGETPID ( 3F )

NAME
PXFGETPID – Gets the process ID

SYNOPSIS
SUBROUTINE PXFGETPID (ipid, ierror)
INTEGER ipid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETPID subroutine uses the getpid(2) system call to find the current process ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
ipid An output integer variable that contains the process ID of the current process.
ierror An output integer variable that contains a status of zero if the process ID was successfully
acquired.

EXAMPLES
In this example, PXFGETPID returns the current process ID.
pro gram pxf test
intege r ipi d, ier ror
CAL L PXFGET PID (ipid, ierror )
if (ierro r .eq. 0) then
pri nt *,’ pid = ’,i pid
else
print *,’ error = ’,ierr or
end if
end

004– 2165– 002 241

PXFGETPID ( 3F ) PXFGETPID ( 3F )

SEE ALSO
getpid(2)

242 004– 2165– 002

PXFGETPPID ( 3F ) PXFGETPPID ( 3F )

NAME
PXFGETPPID – Gets the parent process ID

SYNOPSIS
SUBROUTINE PXFGETPPID (ipid, ierror)
INTEGER ipid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETPPID subroutine uses the getppid(2) system call to find the parent process ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
ipid An output integer variable that contains the parent process ID of the current process.
ierror An output integer variable that contains a status of zero if the process ID was successfully
acquired.

EXAMPLES
In this example, PXFGETPPID returns the current process’ parent process ID.
pro gra m pxf tes t
int ege r ipi d, ierror
CALL PXFGET PPI D(i pid, ier ror)
if (ierro r .eq. 0) the n
pri nt *,’ pid = ’,i pid
else
print *,’ error = ’,ierr or
end if
end

004– 2165– 002 243

PXFGETPPID ( 3F ) PXFGETPPID ( 3F )

SEE ALSO
getppid(2)

244 004– 2165– 002

PXFGETPWNAM ( 3F ) PXFGETPWNAM ( 3F )

NAME
PXFGETPWNAM – Gets password information about login name

SYNOPSIS
SUBROUTINE PXFGETPWNAM (name, ilen, jpasswd, ierror)
INTEGER ilen, jpasswd, ierror
CHARACTER*n

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETPWNAM routine uses the getpwnam(3C) function to return password information about a login
name. It uses the following components of the passwd structure:
• pw_name: login name
• pw_uid: user ID
• pw_gid: group ID
• pw_dir: default login directory
• pw_shell: default login shell or program
The following components are supported by the UNICOS and IRIX operating systems, but are not part of
the POSIX 1003.9-1992 standard.
• pw_passwd: encrypted password
• pw_age: password age (character string) (unused on IRIX systems)
• pw_comment: comment
• pw_gecos: a comment in the UNICOS operating system; the user’s real name on IRIX systems.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.

004– 2165– 002 245

PXFGETPWNAM ( 3F ) PXFGETPWNAM ( 3F )

The following is a list of valid arguments for this routine:

name An input character variable or array element containing the login name for which password
information is requested.
ilen An input integer variable containing the character length of name. If ilen is zero, trailing blanks
are stripped.
jpasswd An output handle of type passwd created with PXFSTRUCTCREATE(3F).
ierror An output integer variable that contains zero if PXFGETPWNAM was successful or nonzero if
PXFGETPWNAM was not successful.
The PXFGETPWNAM routine may return the following errors:
ENOENT If an entry matching the login name in name was not found.
EBADHANDLE If jpasswd is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES
In this example, the password information will be acquired for the login name root.
pro gra m pxf tes t
int eger ile n, ier ror, val ue
int ege r*8 jpa ssw d
CAL L PXF STR UCTCREATE (’p ass wd’ ,jpass wd, ier ror )
nam e = ’root’
ile n = 4
CAL L PXFGET PWN AM(nam e,ilen ,jp ass wd, ierror )
if (ierro r .eq. 0) the n
print *,’ PASSED: pxfget pwn am cal l’
els e
print *,’ FAILED: pxfget pwn am cal l wit h err or = ’,ierr or
end if
CAL L PXF STR UCTFREE(j pas swd ,ie rror)
end

SEE ALSO
getpwnam(3C), PXFSTRUCTCREATE(3F), PXFSTRUCTFREE(3F)

246 004– 2165– 002

PXFGETPWUID ( 3F ) PXFGETPWUID ( 3F )

NAME
PXFGETPWUID – Gets password information by using user ID

SYNOPSIS
SUBROUTINE PXFGETPWUID (name, iuid, jpasswd, ierror)
INTEGER iuid, jpasswd, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
PXFGETPWUID uses the getpwuid(3C) function to return password information about a user ID. It uses
the following components of the passwd structure:
• pw_name: login name
• pw_uid: user ID
• pw_gid: group ID
• pw_dir: default login directory
• pw_shell: default login shell or program
The following components are supported by the UNICOS and IRIX operating systems, but are not part of
the POSIX 1003.9-1992 standard.
• pw_passwd: encrypted password
• pw_age: password age (character string) (unused on IRIX systems)
• pw_comment: comment
• pw_gecos: a comment in the UNICOS operating system; the user’s real name on IRIX systems.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.

004– 2165– 002 247

PXFGETPWUID ( 3F ) PXFGETPWUID ( 3F )

The following is a list of valid arguments for this routine:

name An input character variable or array element containing the login name for which password
information is requested.
iuid An input integer variable containing the user ID for which password information is requested.
jpasswd An output handle of type passwd created with PXFSTRUCTCREATE(3F).
ierror An output integer variable that contains zero if PXFGETPWUID was successful or nonzero if
PXFGETPWUID was not successful.
The PXFGETPWUID routine may return the following errors:
ENOENT If an entry matching the user ID in iuid was not found.
EBADHANDLE If jpasswd is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES
In this example, the password information will be acquired for the login name root.
pro gra m pxf tes t
int eger iui d, ier ror, val ue
int ege r*8 jpa ssw d

CAL L PXF STR UCTCREATE (’p ass wd’ ,jpass wd, ier ror )
iui d=0
CAL L PXFGET PWU ID(iui d,jpas swd ,ie rro r)
if (ierro r .eq. 0) the n
print *,’ PASSED: pxfget pwu id cal l’
els e
print *,’ FAILED: pxfget pwu id cal l wit h err or = ’,ierr or
end if

CAL L PXF STR UCTFREE(j pas swd ,ie rror)

end

SEE ALSO
getpwnam(3C), PXFSTRUCTCREATE(3F), PXFSTRUCTFREE(3F)

248 004– 2165– 002

PXFGETUID ( 3F ) PXFGETUID ( 3F )

NAME
PXFGETUID – Gets the real user ID

SYNOPSIS
SUBROUTINE PXFGETUID (iuid, ierror)
INTEGER iuid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFGETUID subroutine uses the getuid(2) system call to get the real user ID.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
iuid An output integer variable for the real user ID for the current process.
ierror An output integer variable that contains zero if PXFGETUID was successful.

EXAMPLES
This example calls PXFGETUID and prints the current real user ID and returned error.
pro gram pxf test
int eger iui d, ier r
CAL L PXF GET UID(iu id,ierr)
pri nt *,’ iui d = ’,i uid,’ ierr = ’,i err
end

SEE ALSO
getuid(2)

004– 2165– 002 249

PXFINTGET ( 3F ) PXFINTGET ( 3F )

NAME
PXFINTGET – Allows values stored in individual components of a structure to be extracted and used

SYNOPSIS
INTEGER JHANDLE, VALUE, IERROR
CHARACTER*(n) compnam
CALL PXFINTGET (jhandle, compnam, value, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFINTGET() subroutine allows values stored in individual components of a structure to be extracted
and used.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following are arguments to PXFINTGET:
jhandle An input integer that references a structure. jhandle should have been created with
PXFSTRUCTCREATE.
compnam An input character variable. compnam is the name of a component of the structure. compnam
is case-sensitive.
value An output integer variable. Upon successful completion, value is set to the value stored in the
component of jhandle referenced by compnam.
ierror An output integer variable. It contains the exit status.

EXIT STATUS
Upon successful completion of PXFINTGET, the argument ierror is set to 0. If any of the following
conditions occur, ierror is set to the corresponding value:
ENONAME Component name is not defined for this structure
EBADHANDLE If jhandle is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
only).

250 004– 2165– 002

PXFINTSET ( 3F ) PXFINTSET ( 3F )

NAME
PXFINTSET – Allows components of a structure to be set or modified

SYNOPSIS
INTEGER JHANDLE, VALUE, IERROR
CHARACTER*(n) compnam
CALL PXFINTSET (jhandle, compnam, value, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFINTSET subroutine allows components of a structure to be set or modified.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The arguments for PXFINTSET are:
jhandle An input integer variable. jhandle references a structure. jhandle should have been created by
PXFSTRUCTNAME().
compnam An input character variable. compnam is the name of a component of the structure. compnam is
case-sensitive.
value An input integer variable. value is the value to be stored in the component of jhandle referenced
by compnam. The structures and components that can be accessed through PXFINTSET() are
described on the man page for the related routine.
ierror An output integer variable.

EXIT STATUS
Upon successful completion of PXFINTSET(), the argument ierror is set to 0. If any of the following
conditions occur, ierror is set to the corresponding value:
ENONAME Component name is not defined for this structure
EBADHANDLE
If jhandle is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk only).

004– 2165– 002 251

PXFISATTY ( 3F ) PXFISATTY ( 3F )

NAME
PXFISATTY – Determines if file descriptor corresponds to a valid file descriptor

SYNOPSIS
SUBROUTINE PXFISATTY (ifildes, isatty, ierror)
INTEGER ifildes, ierror
LOGICAL isatty

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFISATTY routine uses isatty(3C) to determine if ifildes is a valid file descriptor for a terminal.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of valid arguments for this routine:
ifildes An input integer variable containing the file descriptor to be checked for an associated terminal.
isatty An output logical variable which is .TRUE. when ifildes is a file descriptor with an associated
terminal. Otherwise isatty is .FALSE..
ierror An output integer variable for the PXFISATTY completion status. ierror contains zero if
PXFISATTY was successful.

EXAMPLES

252 004– 2165– 002

PXFISATTY ( 3F ) PXFISATTY ( 3F )

program pxftes t
int ege r len, ifilde s, ier ror , O_R DON LY
cha rac ter*20 path
log ica l isa tty
CAL L PXF CTE RMID(p ath,le n,i err or)
CAL L PXF CONST( ’O_RDO NLY ’,O _RDONL Y,e rro r)
CAL L PXF OPE N(path ,len,O _RD ONL Y,4 00,ifi lde s,erro r)
CAL L PXF ISA TTY(if ildes, isa tty ,ie rror)
pri nt *,i satty
end

SEE ALSO
PXFCONST(3F), PXFOPEN(3F)
ttyname(3C)

004– 2165– 002 253

PXFISBLK ( 3F ) PXFISBLK ( 3F )

NAME
PXFISBLK – Tests for block special file

SYNOPSIS
LOGICAL FUNCTION PXFISBLK(m)
INTEGER m

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The logical function PXFISBLK checks if a file is a block special file. The argument m should be supplied
by the st_mode component of the stat structure used by the PXFSTAT(3F) routine.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following argument is valid for this routine:
m An integer input variable containing the file mode.
If the file is a block special file, PXFISBLK returns a logical true, otherwise a logical false is returned.

EXAMPLES
In this example, the /dev/dsk directory is read until a block special file is found or the end of the
directory is reached. If a block special file is found, the file is printed.

254 004– 2165– 002

PXFISBLK ( 3F ) PXFISBLK ( 3F )

program pxftes t
int eger ierror ,mode, ile n,EEND
int eger idirid ,jdire nt, jstat
logica l PXF ISBLK, fou nd
charac ter*30 nam e, pat h

CAL L PXF STR UCTCRE ATE(’d ire nt’ ,jd irent, ier ror )
CAL L PXF STRUCT CREATE (’s tat ’,jsta t,i err or)
CAL L PXF CONST( ’EEND’ ,EE ND, ierror )
pat h = ’/d ev/ dsk’
fou nd = .FALSE .
CAL L PXF OPE NDIR(p ath,0, idi rid ,ie rror)
CAL L PXF CHD IR(pat h,0,ie rro r)
do whi le (fo und .eqv. .FA LSE.)
CALL PXFREA DDI R(i dirid, jdi ren t,i error)
if (ierro r .eq . EEN D) then
exit
end if
CAL L PXF STRGET (jdire nt, ’d_ nam e’,nam e,i len,ie rro r)
CAL L PXF STAT(n ame,0, jst at, ier ror)
CAL L PXF INTGET (jstat ,’s t_m ode ’,mode ,ie rro r)
if (PXFIS BLK(mo de) ) the n
fou nd = .TRUE.
endif
end do

if (fo und .eqv. .TR UE. ) the n

pri nt *,n ame,’ is a blo ck file.’
end if
end

SEE ALSO
PXFCONST(3F), PXFINTSET(3F), PXFSTRUCTCREATE(3F)

004– 2165– 002 255

PXFISCHR ( 3F ) PXFISCHR ( 3F )

NAME
PXFISCHR – Tests for character special file

SYNOPSIS
LOGICAL FUNCTION PXFISCHR(m)
INTEGER m

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The logical function PXFISCHR checks if a file is a character special file. The argument m should be
supplied by the st_mode component of the stat structure used by the PXFSTAT(3F) routine.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a valid argument for this routine:
m An integer input variable containing the file mode.
If the file is a character special file, PXFISCHR returns a logical true, otherwise a logical false is returned.

EXAMPLES
In this example, PXFSTAT is called on /dev/tty, which should be a character special file. After
PXFINTGET(3F) returns the mode of /dev/tty, PXFISCHR is called to check the mode of /dev/tty.

256 004– 2165– 002

PXFISCHR ( 3F ) PXFISCHR ( 3F )

program pxftes t
integer jstat, ier ror,mo de
logical pxfisc hr

CALL PXF STRUCT CRE ATE(’s tat’,j sta t,ierr or)

CALL PXF STAT(’ /de v/tty’ ,0,jst at, ierror )
CAL L PXF INT GET(js tat,’s t_m ode ’, mode, ier ror )
if (PXFIS CHR (mode) .eq v. .TRUE. ) the n
pri nt *,’ /de v/tty is a charac ter specia l fil e.’
else
print *,’/de v/t ty sho uld be a charac ter specia l file, but is not.’
end if
end

This program may display:

/de v/tty is a cha racter spe cia l fil e.

SEE ALSO
PXFISBLK, PXFINTGET(3F), PXFSTAT(3F), PXFSTRUCTCREATE(3F)

004– 2165– 002 257

PXFISDIR ( 3F ) PXFISDIR ( 3F )

NAME
PXFISDIR – Tests for directory file

SYNOPSIS
LOGICAL FUNCTION PXFISDIR(m)
INTEGER m

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libffio.so which is linked by default when compiling programs with
the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The logical function PXFISDIR checks if a file is a directory file. The argument m should be supplied by
the st_mode component of the stat structure used by the PXFSTAT(3F) routine.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following argument is available for this routine:
m An input integer variable containing the file mode.
If the file is a directory file, PXFISDIR returns a logical true, otherwise a logical false is returned.

EXAMPLES
In this example, the directory / is opened and read until a directory is found or the end of the directory is
reached. If a directory is found, found a directory in / is displayed.

258 004– 2165– 002

PXFISDIR ( 3F ) PXFISDIR ( 3F )

program pxftes t
int eger ierror ,mode, ile n,EEND
int eger idirid ,jdire nt, jstat
logica l PXF ISDIR, fou nd
charac ter*30 nam e, pat h

CAL L PXF STR UCTCRE ATE(’d ire nt’ ,jd irent, ier ror )
CAL L PXF STRUCT CREATE (’s tat ’,jsta t,i err or)
CAL L PXF CONST( ’EEND’ ,EE ND, ierror )
pat h = ’/’
CAL L PXF OPE NDIR(p ath,0, idi rid ,ie rror)
CAL L PXF CHD IR(pat h,0,ie rro r)
fou nd = .FALSE .

do whi le (fo und .eqv. .FA LSE.)

CALL PXFREA DDI R(i dirid, jdi ren t,i error)
if (ierro r .eq . EEN D) then
exit
end if
CAL L PXF STRGET (jdire nt, ’d_ nam e’,nam e,i len,ie rro r)
CAL L PXF STAT(n ame,0, jst at, ier ror)
CAL L PXF INTGET (jstat ,’s t_m ode ’,mode ,ie rro r)
if (PXFIS DIR(mo de) ) the n
fou nd = .TRUE.
endif
end do

if (fo und .eqv. .TR UE. ) the n

pri nt *,’fou nd a dir ect ory in /’
end if
end

SEE ALSO
PXFCONST(3F), PXFINTSET(3F), PXFSTAT(3F), PXFSTRUCTCREATE(3F)

004– 2165– 002 259

PXFISFIFO ( 3F ) PXFISFIFO ( 3F )

NAME
PXFISFIFO – Tests for pipe or a FIFO special file

SYNOPSIS
LOGICAL FUNCTION PXFISFIFO(m)
INTEGER m

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The logical function PXFISFIFO checks if a file is a pipe or FIFO special file. The argument m should be
supplied by the st_mode component of the stat structure used by the PXFSTAT(3F) routine.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following argument is valid for this routine:
m An integer input variable containing the file mode.
If the file is a block special file, PXFISFIFO returns a logical true, otherwise a logical false is returned.

EXAMPLES
In this example, a file named testfile in /tmp created by mkfifo(1) is tested to see if it is a FIFO
special file.

260 004– 2165– 002

PXFISFIFO ( 3F ) PXFISFIFO ( 3F )

program pxftes t
int eger mode, ierror
intege r jst at
logical PXFISF IFO

CAL L PXF CHDIR( ’/tmp’ ,0, ierror )

CALL MKF IFO(’t est file’, 644,ie rro r)
CALL PXF STRUCT CRE ATE(’s tat’,j sta t,ierr or)
CALL PXF STAT(’ tes tfile’ ,0,jst at, ierror )
CAL L PXF INTGET (jstat ,’s t_mode ’,mode ,ie rror)
if (PX FISFIF O(mode ,ie rro r) .eqv. .TR UE.) the n
pri nt *,’PAS SED : PXFISF IFO test’
els e
pri nt *,’FAI LED : PXFISF IFO test’
endif
end

SEE ALSO
PXFINTSET(3F), PXFSTAT(3F), PXFSTRUCTCREATE(3F)
mkfifo(1)

004– 2165– 002 261

PXFISREG ( 3F ) PXFISREG ( 3F )

NAME
PXFISREG – Tests for regular file

SYNOPSIS
LOGICAL FUNCTION PXFISREG(m)
INTEGER m

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The logical function PXFISREG checks if a file is a regular file. The argument m should be supplied by the
st_mode component of the stat structure used by the PXFSTAT(3F) routine. If the file is a regular file,
PXFISREG returns a logical true, otherwise a logical false is returned.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following argument is valid for this routine:
m An integer input variable containing the file mode.

EXAMPLES

262 004– 2165– 002

PXFISREG ( 3F ) PXFISREG ( 3F )

program pxftes t
integer jstat, ier ror,mo de
logical PXFISR EG
CALL PXF STRUCT CRE ATE(’s tat’,j sta t,ierr or)
CAL L PXF STAT(’ /etc/p ass wd’,0, jstat, ier ror)
CAL L PXF INT GET(js tat,’s t_m ode ’, mode, ier ror )
if (PX FIS REG(mo de) .eq v. .TRUE. ) the n
pri nt *,’ passwd is a reg ula r fil e.’
else
print *,’pas swd file is not a regula r fil e.’
end if
end

SEE ALSO
PXFINTGET(3F), PXFSTAT(3F), PXFSTRUCTCREATE(3F)

004– 2165– 002 263

PXFLINK ( 3F ) PXFLINK ( 3F )

NAME
PXFLINK – Creates a link to a file

SYNOPSIS
CHARACTER*n existf, newf
INTEGER lenexist, lennew, ierror
CALL PXFLINK(existf, lenexist, newf, lennew, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFLINK routine uses the link function to link an existing file to a new file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
existf An input character variable or array element containing the name of an existing file.
lenexist An input integer variable containing the length of existf in characters. If lenexist is zero, all
trailing blanks are removed before calling link().
newf An input character variable or array element containing the name of a new file.
lennew An input integer variable containing the length of newf in characters. If lennew is zero, all
trailing blanks are removed before calling link().
ierror An output integer variable that contains zero if the link was successful or nonzero if the link was
not completed.
In addition to the errors returned by the link(2) system call, PXFLINK may return the following errors:
EINVAL If lenexist < 0 or lenexist > LEN(existf) or lennew < 0 or lennew > LEN(newf).
ENOMEM If PXFLINK is unable to obtain memory to copy existf or newf.

264 004– 2165– 002

PXFLINK ( 3F ) PXFLINK ( 3F )

EXAMPLES

progra m test
cha rac ter*(1 2) filea, fileb
int ege r len fil a, len filb,i err
fil ea = ’ex ist file’
fil eb = ’ne wfile’
len fil a = 0
lenfil b = 0
cal l pxf lin k(file a,lenf ila,fi leb,lenfi lb, ierr)
if (ierr. ne. 0) the n
print *,’ FAIL: error fro m pxflink = ’,i err
else
print *,’ PASS: No err or fro m pxf lin k = ’
endif
end

004– 2165– 002 265

PXFLOCALTIME ( 3F ) PXFLOCALTIME ( 3F )

NAME
PXFLOCALTIME – Converts to local time

SYNOPSIS
SUBROUTINE PXFLOCALTIME (isecnds, iatime, ierror)
INTEGER isecnds, iatime, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFLOCALTIME routine uses the localtime function to convert seconds since 00:00:00 CTU
(coordinated universal time), January 1, 1970 (the Epoch), to broken-down time. Adjustments for time zone
and daylight savings time are made according to the TZ environment variable.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
isecnds An input integer variable containing the number of seconds since 00:00:00 CTU, January 1,
1970.
iatime An output integer array with the elements:
iatime(1) = seconds (0-61, for leap seconds)
iatime(2) = minutes (0-59)
iatime(3) = hours (0-23)
iatime(4) = day of the month (1-31)
iatime(5) = month of the year (1-12)
iatime(6) = Gregorian year (e.g., 1995)
iatime(7) = Day of the week (0 = Sunday)
iatime(8) = Day of the year (1-366)

266 004– 2165– 002

PXFLOCALTIME ( 3F ) PXFLOCALTIME ( 3F )

iatime(9) = Daylight savings flag (0 = standard, nonzero = daylight savings)

ierror An output integer variable that contains zero if PXFLOCALTIME was successful or nonzero if
PXFLOCALTIME was unsuccessful.
This routine may return the EINVAL error value if the current value of the TZ environment variable is
invalid. iatime is left unchanged if this error occurs.

EXAMPLES
In this example, the current time, date, and time system are displayed if PXFLOCALTIME and PXFTIME are
successful.
progra m pxf test
intege r ise cnds, iat ime (9), ierror

CALL PXFTIM E(isec nds ,ie rror)

if (ie rror .eq . 0) the n
CAL L PXF LOCALT IME (is ecnds, iatime,ierro r)
if (ie rro r .eq . 0) then
print *,’Tim e: ’,I ATIME( 3),’:’,IATIM E(2),’:’,IAT IME(1)
print *,’ Dat e: ’,I ATIME( 4), ’.’,IATIM E(5 ),’.’,IATIME (6)
if (IA TIME(9 ) .eq . 0) then
print *,’ sta ndard time’
els e
pri nt *,’day lig ht sav ing s’
end if
else
pri nt *,’ PXFTIM E err or = ’,ierror
endif
els e
pri nt *,’PXF TIME error = ’,i error
endif
end

This example may display:

Tim e: 8:3 7:24
Dat e: 11.7.1 996
day lig ht sav ings

SEE ALSO
ctime(3C)

004– 2165– 002 267

PXFOPEN ( 3F ) PXFOPEN ( 3F )

NAME
PXFOPEN – Provides a Fortran interface to the open(2) system call

SYNOPSIS
INTEGER ilen, iopenflag, imode, ifildes, ierror
CHARACTER*n path
CALL PXFOPEN(path, ilen, iopenflag, imode, ifildes, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The routine PXFOPEN provides a subset of the functionality of the open(2) system call.
The path argument identifies the file to be opened. If PXFOPEN successfully opens the file, the file
descriptor is returned in the argument ifildes, and ierror is set to zero. If the file cannot be opened, ierror is
set to the error value.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following is a list of arguments for this routine:
path An input character variable or array element containing the name of the file to be opened.
ilen An input integer variable containing the length of path in characters. If ilen is zero, the trailing
blanks are removed.
iopenflag An input integer variable containing the status flags. See the open(2) man page for more detail.
The value for this variable may be obtained through the use of PXFCONST(3F) or IPXFCONST.
The following values are currently supported for iopenflag:
• O_RDONLY
• O_WRONLY
• O_RDWR
• O_RAW*

268 004– 2165– 002

PXFOPEN ( 3F ) PXFOPEN ( 3F )

• O_LDRAW*
• O_NDELAY
• O_NONBLOCK
• O_NOCTTY
• O_BIG*
• O_APPEND
• O_CREAT
• O_TRUNC
• O_EXCL
• O_PLACE*
• O_RESTART*
• O_SSD*
• O_SYNC
• O_WELLFORMED*
* = UNICOS and UNICOS/mk systems only.
The integer values may be combined through the use of a bitwise inclusive OR function.
imode An input integer variable, denoting the file access permission. The value for this variable may
be retrieved through the use of PXFCONST or IPXFCONST. The following values are currently
supported for imode:
USER READ permissions bit: S_IRUSR
WRITE permissions bit: S_IWUSR
SEARCH/EXECUTE permissions bit: S_IXUSR
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXU
GROUP READ permissions bit: S_IRGRP
WRITE permissions bit: S_IWGRP
SEARCH/EXECUTE permissions bit: S_IXGRP
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXG
OTHER READ permissions bit: S_IROTH
WRITE permissions bit: S_IWOTH
SEARCH/EXECUTE permissions bit: S_IXOTH
Inclusive OR of READ/WRITE/EXECUTE: S_IRWXO
SETID Set user ID on execution: S_ISUID
Set group ID on execution: S_ISGID
The integer values may be combined through the use of a bitwise inclusive OR
function.

004– 2165– 002 269

PXFOPEN ( 3F ) PXFOPEN ( 3F )

ifildes An output integer variable. If the open system call was successful, ifildes will be set to the file
descriptor.
ierror An output integer variable containing the status:
0 If PXFOPEN was successful (the open(2) succeeded)
errno If the open(2) system call failed
EINVAL If ilen is less than 0 or ilen is greater than LEN(path)

NOTES
PXFOPEN does not provide a way to specify the cbits or cblks parameters to open(2).

SEE ALSO
open(2)

270 004– 2165– 002

PXFRENAME ( 3F ) PXFRENAME ( 3F )

NAME
PXFRENAME – Renames a file

SYNOPSIS
CHARACTER*n oldnm, newnm
INTEGER lenold, lennew, ierror
CALL PXFRENAME(oldnm, lenold, newnm, lennew, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFRENAME routine uses the rename() function to change the name of a file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
oldnm An input character variable or array element containing the current file name.
lenold An input integer variable containing the length of oldnm in characters. If lenold is zero, all
trailing blanks are removed before calling rename.
newnm An input character variable or array element containing the new name of the file.
lennew An input integer variable containing the length of newnm in characters. If lennew is zero, all
trailing blanks are removed before calling rename.
ierror An output integer variable that contains zero if the renaming of the file was successful or
nonzero if the renaming of the file was not completed.
In addition to the errors returned by rename(2) system call, PXFRENAME may return the following errors:
EINVAL If lenold < 0 or lenold > LEN(old) or lennew < 0 or lennew > LEN(newf).
ENOMEM If PXFRENAME is unable to obtain memory to copy oldnm or newnm.

004– 2165– 002 271

PXFRENAME ( 3F ) PXFRENAME ( 3F )

EXAMPLES

pro gram test

charac ter *(12) filea, fileb
int eger lenfil a, len filb,i err
fil ea = ’ol dname’
fileb = ’newna me’
len fila = 0
lenfil b = 0
call pxfren ame(fi lea,lenfi la,fil eb,len fil b,ierr)
if (ie rr.ne. 0) the n
print *,’FAI L: error from pxf ren ame = ’,ierr
else
pri nt *,’ PASS: No err or fro m pxfren ame = ’
end if
end

272 004– 2165– 002

PXFRMDIR ( 3F ) PXFRMDIR ( 3F )

NAME
PXFRMDIR – Removes a directory entry

SYNOPSIS
CHARACTER*n path
INTEGER ilen, ierror
CALL PXFRMDIR(path, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFRMDIR subroutine uses the rmdir function to remove a directory entry for the named file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
path An input character variable or array element containing the name of a file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling rmdir.
ierror An output integer variable that contains a status of zero if the named file was removed.
In addition to the errors returned by the rmdir(2) system call, PXFRMDIR may return the following errors:
EINVAL If ilen less than 0 or ilen is greater than LEN(path).
ENOMEM If PXFRMDIR is unable to obtain memory to copy path

004– 2165– 002 273

PXFRMDIR ( 3F ) PXFRMDIR ( 3F )

EXAMPLES

pro gram test

charac ter*(1 2) pat h
intege r ile n, ier r
pat h = ’testf ile’
ile n = 0
call pxfrmd ir(pat h,ilen,ie rr)
if (ie rr.ne. 0) the n
pri nt *,’ FAIL: error fro m pxf rmdir = ’,ierr
els e
pri nt *,’ PASS: No err or fro m pxfrmd ir = ’
end if
end

SEE ALSO
rmdir(2)

274 004– 2165– 002

PXFSETENV ( 3F ) PXFSETENV ( 3F )

NAME
PXFSETENV – Sets environment variable pair

SYNOPSIS
CHARACTER*n name, new
INTEGER len, name, lennew, ioverwrite, ierror
CALL PXFSETENV (name, lenname, new, lennew, ioverwrite, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSETENV routine uses the putenv(3C) function to change a currently existing "name=value" pair
or create a new name=value pair. The name or new arguments are stripped of trailing blanks if lenname or
lennew are zero.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
name An input character variable or array element containing the environment name value to be set.
lenname An input integer variable containing the character length of name. If lenname is zero, trailing
blanks are removed.
new An input character variable or array element containing the new environment value for the
name=value environment pair.
lennew An input integer variable containing the character length of new. If lennew is zero, trailing
blanks are removed.
ioverwrite An input integer variable containing a zero or nonzero number. When the value is zero, a
name=value pair with the name value matching name will not be replaced with a new name=new
pair.
A nonzero ioverwrite value will replace the matching name=value pair with name=new pair.

004– 2165– 002 275

PXFSETENV ( 3F ) PXFSETENV ( 3F )

ierror An output integer variable that contains zero if the environment variable was changed or nonzero
if PXFSETENV was not successful.
The PXFSETENV routine may return any of the following error values:
EINVAL If ilen is less than 0 or lenname is greater than LEN(path) or lennew is less than 0 or lennew is
greater than LEN(new).
ENOMEM If PXFSETENV is unable to obtain memory to copy name and new to a new name=value string.

EXAMPLES
In this example, PXFSETENV sets the SHELL environment value to /bin/csh.
pro gram testpx f
cha racter *10 nam e, val
int eger lennam e, lenval, ioverw, ierr
c set input arg uments
nam e=’SHELL’
ier r=0
len name=5
val =’/bin/cs h’
len val=8
iov erw=1
CAL L PXFSET ENV(na me, lenname,v al, lenval,io ver,ierr)
c print inp ut argume nts
pri nt *,’ nam e=-’,name ,’- ’
pri nt *,’ len name=’,le nna me
pri nt *,’ val =-’,val,’ -’
pri nt *,’ len val=’,len val
pri nt *,’ iot herw=’,io the rw
c print out put arg ume nt
pri nt *,’ ier r=’,ierr
end

SEE ALSO
setenv(3C)

276 004– 2165– 002

PXFSETGID ( 3F ) PXFSETGID ( 3F )

NAME
PXFSETGID – Sets group ID

SYNOPSIS
SUBROUTINE PXFSETGID (igid, ierror)
INTEGER igid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSETGID routine uses the setgid(2) function to set the real group ID, effective group ID, and
saved-set group IDs of the calling process. The following conditions determine the setting of an ID. They
are checked in the following order, and the first condition that is true is applied:
• If the process has appropriate privilege, the real, effective, and saved-set group IDs are all set to igid.
• If ID is equal to either the real group ID, the effective group ID, or the saved-set, group ID is set to igid.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
igid An input integer variable used to replace the current group ID for the calling process.
ierror An output integer variable that contains zero if PXFSETGID was successful. or nonzero if
PXFSETGID was not successful.
PXFSETGID may return EINVAL if the value of the igid argument is out of range or EPERM if the process
does not have the appropriate privileges and igid does not match the real user ID.

004– 2165– 002 277

PXFSETGID ( 3F ) PXFSETGID ( 3F )

NOTES
On a UNICOS multilevel security (MLS) system, a process with the effective privileges shown is granted the
following abilities:
Privilege Description
PRIV_SETGID The process may set the real group ID, effective group ID, and saved set-
group-ID.
On a UNICOS non-MLS system or a UNICOS MLS system with PRIV_SU enabled, the super user may set
the real group ID, effective group ID, and saved set-group-ID.

EXAMPLES
In this example, the current user ID for the current process will be obtained by calling PXFGETGID and
then setting the group ID for the current process by using the group ID returned by PXFGETGID.
pro gra m pxf test
int eger igid, ier ror

CAL L PXF GETGID (igid, ierror )

if (ie rror .eq . 0) the n
CAL L PXF SET GID(ig id, ierror )
if (ie rror .eq. 0) then
pri nt *,’ group id set to ’,i gid
else
pri nt *,’ group id not set to ’,i gid,’ becaus e of err or’
endif
els e
print *,’cou ld not obt ain use r ID err or = ’,i error
end if
end

SEE ALSO
setgid(2)

278 004– 2165– 002

PXFSETPGID ( 3F ) PXFSETPGID ( 3F )

NAME
PXFSETPGID – Set process group ID

SYNOPSIS
SUBROUTINE PXFSETPGID (ipid, ipgid, ierror)
INTEGER ipid, ipgid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSETPGID routine uses the setpgid(2) system call to change the process group ID of the process
with a process ID of ipid. The process group ID may be for an existing process group or a new process
group which will be created. Upon sucessful completion, the process with a process ID of ipid will have its
process group ID set to ipgid.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
ipid An input integer variable that contains the process ID of the process to change the process group
ID. As a special case, if ipid is zero the process ID of the calling process is used.
ipgid An input integer variable containing the new process group ID.
ierror An output integer variable that contains zero if PXFSETPGID was successful or nonzero if
PXFSETPGID was not successful.
PXFSETPGID may return any of the following error values:
EACCES If the value of ipid matches the process ID of a child process of the calling process and the child
process has successfully executed one of the PXFEXEC(3F) functions.
EINVAL If the value of ipgid is less than 0 or is not a value supported by the implementation.

004– 2165– 002 279

PXFSETPGID ( 3F ) PXFSETPGID ( 3F )

EPERM If the process indicated by ipid is a session leader; if the value of ipid is valid but matches the
process ID of a child process of the calling process and the child process is not in the same
session as the calling process; or if the value of ipgid does not match the process ID of the
process indicated by pid and no process with a process group ID exists that matches the value of
ipgid in the same session as the calling process.
ESRCH If the value of ipid does not match the ID of the calling process or of a child of the calling
process.

EXAMPLES

progra m pxf test

intege r ipi d, ier ror

CAL L PXF GET PID(ip id, ier ror)

if (ie rror .ne. 0) the n
pri nt *,’FAILED : PXF GETPID cal l wit h error = ’,ierr or
else
CALL PXFSET PGI D(ipid , ipid, ier ror )
if (ierro r .eq. 0) the n
pri nt *,’PAS SED: PXF SET PGID nor mal tes t’
els e
pri nt *,’ FAI LED: PXF SETPGID normal test wit h error = ’,ierr or
endif
endif
end

SEE ALSO
setpgid(2)

280 004– 2165– 002

PXFSETSID ( 3F ) PXFSETSID ( 3F )

NAME
PXFSETSID – Creates a new session for a calling process

SYNOPSIS
SUBROUTINE PXFSETSID (isid, ierror)
INTEGER isid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSETSID routine uses the setsid(2) system call to create a new session for the calling process.
The calling process must not be the process leader for PXFSETSID to be successful.
After the successful completion of PXFSETSID, the calling process will be the session leader for the new
session and the process group leader for the new process group. The calling process also will have no
controlling terminal.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
isid An output integer variable for the new process group ID of the calling process.
ierror An output integer variable that contains zero if PXFSETSID was successful or nonzero if
PXFSETSID was not successful.
This routine may return the EPERM error value if the calling process is already a process group leader, or the
calling process group ID of a process other than the calling process matches the process ID of the calling
process.

EXAMPLES
In this example, PXFFORK(3F) is called to create a child process, which calls PXFSETSID to create a new
session. The child writes the value of ierror to Fortran unit 10 and stops. After the fork, the parent process
waits for the child to finish execution, and then reads from Fortran unit 10. If the value read in from unit 10
is not equal to zero, the child’s call to PXFSETSID was unsucessful.

004– 2165– 002 281

PXFSETSID ( 3F ) PXFSETSID ( 3F )

program pxftes t
integer isid, ire tpid, ist at, ierror , i

CAL L PXF FORK(i retpid ,ie rro r)

if (ie rror .ne. 0) the n
pri nt *,’FAI LED: PXFFOR K cal l wit h error = ’,ierr or
else
if (ir etp id .eq . 0) then
CALL PXFSET SID (is id, ier ror )
wri te (10 ,*) ier ror
sto p
else
CAL L PXF WAI T(ista t, ire tpi d, ier ror)
rea d (10 ,*) i
if (i .eq. 0) the n
pri nt *,’PAS SED: PXFSET SID call under nor mal con dition s’
else
pri nt *,’FAI LED: PXFSET SID call with err or = ’,i
endif
end if
end if

SEE ALSO
setsid(2)
PXFFORK(3F)

282 004– 2165– 002

PXFSETUID ( 3F ) PXFSETUID ( 3F )

NAME
PXFSETUID – Sets user ID

SYNOPSIS
SUBROUTINE PXFSETUID (iuid, ierror)
INTEGER iuid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSETUID routine uses the setuid(2) function to set the real user ID, effective user ID, and saved
set user IDs of the calling process. The following conditions determine the setting of an ID. They are
checked in the following order, and the first condition that is true is applied:
• If the process has appropriate privilege, the real, effective, and saved set user IDs are all set to iuid.
• If the ID is equal to either the real user ID, the effective user ID, or the saved set user, ID is set to iuid.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
iuid An input integer variable used to replace the current user ID for the calling process.
ierror An output integer variable that contains zero if PXFSETUID was successful or nonzero if
PXFSETUID was not successful.
This routine may return EINVAL if the value of the iuid argument is out of range. or EPERM if the process
does not have the appropriate privileges and if iuid does not match the real user ID.

004– 2165– 002 283

PXFSETUID ( 3F ) PXFSETUID ( 3F )

NOTES
On a UNICOS multilevel security (MLS) system, a process with the effective privileges shown is granted the
following abilities:
Privilege Description
PRIV_SETGID The process may set the real user ID, effective user ID, and saved set-user-ID.
On a UNICOS non-MLS system or a UNICOS MLS system with PRIV_SU enabled, the super user may set
the real user ID, effective user ID, and saved set-user-ID.

EXAMPLES
In this example, the current user ID for the current process will be obtained by calling PXFGETUID and
then seting the user ID for the current process using the group ID returned by PXFGETUID.
progra m pxf test
int eger iuid, ier ror

CAL L PXF GETUID (iuid, ierror )

if (ie rror .eq . 0) the n
CAL L PXF SET UID(iu id, ierror )
if (ie rror .eq. 0) then
pri nt *,’ user id set to ’,i uid
else
pri nt *,’ user id not set to ’,iuid ,’ bec ause of error’
endif
els e
print *,’cou ld not obt ain use r ID err or = ’,i error
end if
end

SEE ALSO
setuid(2)
PXFGETUID(3F)

284 004– 2165– 002

PXFSLEEP ( 3F ) PXFSLEEP ( 3F )

NAME
PXFSLEEP – Delays process execution

SYNOPSIS
SUBROUTINE PXFSLEEP(iseconds, isecleft, ierror)
INTEGER iseconds, isecleft, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The PXFSLEEP subroutine waits iseconds before generating a SIGALRM signal. If a previous PXFSLEEP
has time remaining, isecleft contains the number of seconds until the signal SIGALRM would have been
generated.
The following is a list of arguments for this routine:
iseconds Default integer input variable containing the number of real-time seconds to wait before sending
the calling process a SIGALRM signal.
isecleft Default integer output variable containing the number of seconds left until a previous request
would have generated a SIGALRM signal.
ierror Default integer output variable containing a status of zero if PXFSLEEP was successful.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

NOTES
Replace the use of the sleep(3C) function with the subroutine call to PXFSLEEP().

EXAMPLES

004– 2165– 002 285

PXFSLEEP ( 3F ) PXFSLEEP ( 3F )

program pxftes t
intege r ise conds, ise cleft, ier ror

isecon ds = 10
isecle ft = 0
ierror = 0
CALL PXFSLE EP( ise conds, ise cle ft, ierror )
if (ie rror .ne. 0) the n
pri nt *,’ FAI LED: PXFSLE EP cal l fai led with err or = ’,i error
els e
pri nt *,’PAS SED : PXFSLE EP cal l ret urn ed no err or’
endif
if (is ecl eft .ne . 0) the n
pri nt *,’ FAI LED: PXFSLE EP, isecle ft not zer o, =’,isecle ft
end if
end

SEE ALSO
alarm(2)
sleep(3C)

286 004– 2165– 002

PXFSTAT ( 3F ) PXFSTAT ( 3F )

NAME
PXFSTAT – Retrieves the file status

SYNOPSIS
INTEGER jstat, ilen, ierror
CALL PXFSTAT(path, ilen, jstat, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSTAT routine uses the stat system call to get the file status.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
path An input character variable or array element containing the name of a file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling stat().
jstat An input integer variable or array element containing a handle for a stat structure. This handle
should have been created by a call to the PXFSTRUCTCREATE(3F) routine.
ierror An output integer variable that contains the status:
Zero PXFSTAT returned the status information.
Nonzero PXFSTAT was unable to return the status.
In addition to errors returned by the stat(2) system call, the following errors may occur:
EINVAL If ilen < 0 or ilen > LEN(path).
ENOMEM If PXFSTAT is unable to obtain memory to copy path.
EBADHANDLE If jstat is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

004– 2165– 002 287

PXFSTAT ( 3F ) PXFSTAT ( 3F )

The stat structure contains the following components:

• st_mode: File mode.
• st_ino: File serial number.
• st_dev: ID of device containing the file.
• st_nlink: Number of links.
• st_uid: User id of the owner of the file.
• st_gid: Group id of the owner of the file.
• st_size: File size in bytes for regular files. Unspecified for other files.
• st_atime: Last time that data within the file was accessed.
• st_mtime: Last time that data in the file was modified.
• st_ctime: Last time that file status was changed.

EXAMPLES

program test
charac ter*10 pat h
int eger ilen, jst at, ier r,i mode, ist ino
path = ’st t.f’
call pxfstr uctcre ate (’stat ’,jstat,i err )
print *,’str uct create error = ’,i err
ilen=0
call pxfsta t(path , ilen, jst at, ierr)
if (ierr. ne.0) the n
print *,’FAI L: error from pxfstat = ’,i err
else
pri nt *,’ PASS: No error from pxf stat = ’
endif
cal l pxf intget (js tat,’s t_i no’,istino,i err)
call pxfint get(js tat ,’mode’,i mod e,ierr)
print *,’ st_ino = ’,i sti no
pri nt *,’mode = ’,imod e
call pxf str uctfre e(s tat,ie rr)
end

288 004– 2165– 002

PXFSTRGET ( 3F ) PXFSTRGET ( 3F )

NAME
PXFSTRGET – Allows values stored in individual components of a structure to be extracted and used

SYNOPSIS
INTEGER jhandle, ilen, ierror
CHARACTER*(n) compnam, value
CALL PXFSTRGET (jhandle, compnam, value, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The routine PXFSTRGET allows character values stored in individual components of a structure to be
extracted and used.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
The following are arguments to PXFSTRGET:
jhandle An input integer that references a structure. jhandle should have been created with
PXFSTRUCTCREATE.
compnam An input character variable that is the name of a component of the structure. compnam is case-
sensitive.
value An output character variable. Upon successful completion, value is set to the value stored in the
component of jhandle referenced by compnam. If the length of the data being stored is less than
the declared length of value, value is padded with blanks.
The structures and components that may be accessed through PXFSTRGET are described on the
man page for the related PXF routine. For example, the PXFUNAME man page describes the
components for the utsname structure.
ilen An output integer variable. ilen is set to the actual length of the data assigned to value. If the
length of value is insufficient to contain the data being returned, the data is truncated, and ilen
contains the original length of the data before truncation. In this case, ierror is set to ETRUNC.

004– 2165– 002 289

PXFSTRGET ( 3F ) PXFSTRGET ( 3F )

ierror An output integer variable. Upon successful completion of PXFSTRGET, ierror is set to 0. If
any of the following conditions occur, ierror is set to the corresponding value:
ENONAME Component name is not defined for the specified structure.
ETRUNC The actual length of the data to be copied to value was longer than the
declared length of value.
EBADHANDLE If jhandle is an invalid handle or has an incorrect handle type (UNICOS and
UNICOS/mk systems only).

SEE ALSO
PXFSTRUCTCREATE(3F), PXFUNAME(3F)

290 004– 2165– 002

PXFSTRSET ( 3F ) PXFSTRSET ( 3F )

NAME
PXFSTRSET – Allows values stored in individual components of a structure to be set

SYNOPSIS
INTEGER jhandle, ilen, ierror
CHARACTER*n compnam, value
CALL PXFSTRSET (jhandle, compnam, value, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The routine PXFSTRSET allows character values stored in individual components of a structure to be set.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following are arguments to PXFSTRSET:
jhandle An input integer that references a structure. jhandle should have been created with
PXFSTRUCTCREATE.
compnam An input character variable. compnam is the name of a component of the structure. compnam is
case-sensitive.
value An input character variable. Upon successful completion, the component of jhandle referenced
by compnam is set to value.
ilen An input integer variable. ilen is the intended length of value. If ilen is zero, then trailing
blanks in value are stripped and ignored.
ierror An output integer variable. Upon successful completion of PXFSTRSET, ierror is set to 0. If
any of the following conditions occur, ierror is set to the corresponding value:
ENONAME Component name is not defined for the specified structure.
EBADHANDLE If jhandle is an invalid handle or has an incorrect handle type (UNICOS and
UNICOS/mk systems only).

004– 2165– 002 291

PXFSTRSET ( 3F ) PXFSTRSET ( 3F )

SEE ALSO
PXFSTRUCTCREATE(3F)

292 004– 2165– 002

PXFSTRUCTCOPY ( 3F ) PXFSTRUCTCOPY ( 3F )

NAME
PXFSTRUCTCOPY – Copies structure

SYNOPSIS
SUBROUTINE PXFSTRUCTCOPY (structname, jhandle1, jhandle2, ierror)
INTEGER jhandle1, jhandle2, ierror
CHARACTER*n structname

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSTRUCTCOPY routine copies structures created with PXFSTRUCTCREATE(3F). The structure
referenced by jhandle1 is copied to the structure referenced by jhandle2.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following are valid arguments for this routine:
structname An input character variable or array element containing the structure name corresponding to the
two structure handles’ type.
jhandle1 An input structure handle variable to be copied.
jhandle2 An output structure handle variable that will contain a copy of the structure of jhandle1 after
successful execution of PXFSTRUCTCOPY.
ierror An output integer variable that contains zero if PXFSTRUCTCOPY was successful or nonzero if
PXFSTRUCTCOPY was not successful.
This routine may also return any of the following error values:
ENONAME If structname is an invalid structure name, or if structname does not match the jhandle1 and
jhandle2 structure type.
ENOMEM If memory is unavailable to create data structures needed to copy a component.

004– 2165– 002 293

PXFSTRUCTCOPY ( 3F ) PXFSTRUCTCOPY ( 3F )

EBADHANDLE If jhandle1 or jhandle2 is an invalid handle or has an incorrect handle type (UNICOS and
UNICOS/mk only).

EXAMPLES
In this example, two utsname structures are created using PXFSTRUCTCREATE(3F). PXFUNAME(3F) is
called with one utsname structure, which is then copied to the other utsname structure.
pro gra m pxf tes t
int ege r jha ndl e1, jha ndl e2
int ege r ier ror

CAL L PXF STR UCT CRE ATE (’u tsn ame ’,j han dle 1,i err or)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF STR UCT CRE ATE for uts nam e1’
els e
CAL L PXF STR UCT CRE ATE (’u tsn ame ’,j han dle 2,i err or)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF STR UCT CRE ATE for uts nam e2 wit h err or = ’,i err or
els e
CAL L PXF UNA ME( jha ndl e1, ier ror )
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF UNA ME for uts nam e1 wit h err or = ’,i err or
els e
CAL L PXF STR UCT COP Y(’ uts nam e’, jha ndl e1, jha ndl e2, ier ror )
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF STR UCT COP Y wit h err or = ’, ier ror
els e
pri nt *,’ PAS SED : PXF STR UCT COP Y tes t for uts nam e str uct ’
end if
end if
end if
end if

CAL L PXF STR UCT FRE E(j han dle 1,i err or)
CAL L PXF STR UCT FRE E(j han dle 2,i err or)
end

SEE ALSO
PXFSTRUCTCREATE(3F), PXFUNAME(3F)

294 004– 2165– 002

PXFSTRUCTCREATE ( 3F ) PXFSTRUCTCREATE ( 3F )

NAME
PXFSTRUCTCREATE – Creates an instance of the desired structure and returns a nonzero handle in the
argument jhandle

SYNOPSIS
INTEGER jhandle, ierror
CHARACTER*n structname
CALL PXFSTRUCTCREATE (structname, jhandle, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSTRUCTCREATE() routine creates an instance of the desired structure and returns a nonzero handle
in the argument jhandle. All further references to this instance of the structure are through this handle. The
initial values of components within the new instance of the structure are undefined.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following are arguments for PXFSTRUCTCREATE:
structname An input character variable. structname specifies which type of structure should be created.
Values for structname that are currently recognized are shown in the following table.
structname must be in lowercase letters; trailing blanks are ignored.
Values for structname:

structname Structure name Header file containing definition

FLOCK flock <fcntl.h>

UTIMBUF utimbuf <utime.h>
UTSNAME utsname <sys/utsname.h>
STAT stat <stat.h>
TMS tms <sys/times.h>
GROUP group <grp.h>
PASSWD passwd <pwd.h>

004– 2165– 002 295

PXFSTRUCTCREATE ( 3F ) PXFSTRUCTCREATE ( 3F )

jhandle An output integer variable. The structure handle is returned in jhandle.

ierror An output integer variable.

EXIT STATUS
Upon successful completion of PXFSTRUCTCREATE, the argument ierror is set to 0. If any of the
following conditions occur, PXFSTRUCTCREATE sets the argument to the corresponding value:
ENONAME Component name is not defined for this structure
ENOHANDLE Instance of the structure could not be created

EXAMPLES

progra m tes t
int ege r jun am, ier r, ile n
cha rac ter*15 sname
* Cre ate STR UCTURE to be used by uname( )
cal l pxf struct cre ate(’u tsname’,juna m,ierr)
if (ierr.ne. 0) then
pri nt *,’FAI L: error from pxf structcre ate = ’,ierr
endif
* Fil l STR UCTURE throug h una me( )
call pxfuna me(jun am,ier r)
if (ierr. ne. 0) the n
pri nt *,’ FAIL: error fro m pxf uname = ’,ierr
end if
ile n = 0
* Ret rieve com ponent sysnam e from STRUCT URE
cal l pxf strget (ju nam,’s ysname’,snam e,ilen,ierr)
pri nt *, ’sy sna me=’,snam e
* Fre e STR UCTURE
cal l pxf str uctfre e(junam,i err )
if (ie rr.ne. 0) the n
print *,’ FAIL: error fro m pxfstr uctfree = ’,ierr
end if
end

296 004– 2165– 002

PXFSTRUCTFREE ( 3F ) PXFSTRUCTFREE ( 3F )

NAME
PXFSTRUCTFREE – Deletes the instance of the structure referenced by jhandle

SYNOPSIS
INTEGER jhandle, ierror
CALL PXFSTRUCTFREE (jhandle, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSTRUCTFREE routine deletes the instance of the structure referenced by jhandle. This structure
should have been created by PXFSTRUCTCREATE(3F).
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following are arguments to PXFSTRUCTFREE():
jhandle An input integer variable. jhandle is a handle for a structure.
ierror An output integer variable. Upon successful completion of PXFSTRUCTFREE(), ierror is set
to 0. This routine will set ierror to EBADHANDLE if jhandle is an invalid handle (UNICOS or
UNICOS/mk systems only).

EXAMPLES

pro gra m tes t

intege r jstat, ierr, ilen, imo de, ist ino
charac ter *10 path
* Create STR UCTURE to be used by sta t()
cal l pxfstr uctcreate(’s tat’,j stat,ierr )
if (ie rr.ne. 0) the n
pri nt *,’ FAIL: error from pxf struct create = ’,i err
endif

004– 2165– 002 297

PXFSTRUCTFREE ( 3F ) PXFSTRUCTFREE ( 3F )

* Fil l STRUCT URE throug h sta t()

ile n = 0
cal l pxf sta t(p ath, ile n, jst at, ier r)
if (ie rr.ne.0) the n
pri nt *,’FAI L: err or from pxf sta t = ’,i err
end if
* Ret rie ve component s st_ ino and mod e fro m STR UCTURE
cal l pxf int get(js tat,’s t_i no’ ,is ino,ie rr)
call pxf intget(js tat ,’m ode ’,imod e,i err )
print *, ’st _ino =’, stino
print *, ’mo de =’, mod e
* Fre e STRUCT URE
cal l pxf str uct free(j sta t,i err )
if (ie rr.ne. 0) the n
pri nt *,’ FAI L: err or fro m pxf struct fre e = ’,i err
end if
end

SEE ALSO
PXFSTRUCTCREATE

298 004– 2165– 002

PXFSYSCONF ( 3F ) PXFSYSCONF ( 3F )

NAME
PXFSYSCONF – Retrieves the value of configurable system variables

SYNOPSIS
INTEGER NAME, IVAL, IERROR
CALL PXFSYSCONF (name, ival, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFSYSCONF routine uses the sysconf() function to retrieve the current value for the name
configurable system variable.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
This routine has the following arguments:
name An input integer variable or array element containing the integer value of a symbolic constant for
one of the following configurable system variables defined in POSIX Std. 1003.1, section 4.8.1.2:
ARG_MAX
CHILD_MAX
CLK_TCK
NGROUPS_MAX
OPEN_MAX
STREAM_MAX
TZNAME_MAX
_POSIX_JOB_CONTROL
_POSIX_SAVED_IDS
_POSIX_VERSION
The integer value for each of these symbolic constants is retrieved through the use of PXFCONST
or IPXFCONST. The integer values may be combined through the use of a bitwise inclusive OR
function.

004– 2165– 002 299

PXFSYSCONF ( 3F ) PXFSYSCONF ( 3F )

ival An output integer variable that will contain the value of the system variable name.
ierror An output integer variable that contains zero if PXFSYSCONF was successful or nonzero if name is
an invalid system variable.

EXAMPLES
In this example, PXFSYSCONF will retrieve the value of the CLK_TCK system variable.
progra m test
intege r iva l, ierr, iclktc k
iva l = 0
iclktc k = 0
call pxfcon st (’C LK_ TCK’,iclk tck ,ierr)
if (ierr. ne. 0) the n
pri nt *,’ FAIL: err or from pxfconst = ’,ierr
got o 999 9
end if
cal l pxf syscon f (iclkt ck, ival, ierr)
if (ie rr.ne. 0) the n
print *,’ FAIL: error fro m pxfsys conf = ’,ierr
els e
pri nt *,’ PASS: error fro m pxf sysconf = ’,ierr
end if
pri nt *, ’CL K_TCK= ’,ival
9999 con tin ue
end

SEE ALSO
PXFCONST(3F)

300 004– 2165– 002

PXFTIME ( 3F ) PXFTIME ( 3F )

NAME
PXFTIME – Gets system time

SYNOPSIS
SUBROUTINE PXFTIME (itime, ierror)
INTEGER itime, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The routine PXFTIME uses the time function to return the number of seconds since 00:00:00 CTU
(coordinated universal time), January 1, 1970 (the Epoch).
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
itime An output integer variable specifying the number of seconds since 00:00:00 UTC, January 1,
1970.
ierror An output integer variable that contains zero if PXFTIME was successful or nonzero if
PXFTIME was not successful.

EXAMPLES
In this example, PXFTIME returns the current system time in number of seconds since January 1, 1970.

004– 2165– 002 301

PXFTIME ( 3F ) PXFTIME ( 3F )

program testpx f
intege r iti me, ier ror
c cal l PXFTIM E
CAL L PXF TIME(i time, ier ror)
c pri nt out put argume nts
pri nt *,’iti me=’,i tim e
pri nt *,’ier ror=’, ier ror
end

SEE ALSO
time(3C)

302 004– 2165– 002

PXFTIMES ( 3F ) PXFTIMES ( 3F )

NAME
PXFTIMES – Gets process times

SYNOPSIS
SUBROUTINE PXFTIMES (jtms, itime, ierror)
INTEGER jtms, itime, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFTIMES subroutine uses the times(2) system call to access system and user CPU time and wall-
clock time for the current process and any child processes.
Components of the tms structure are:
• tms_utime: User CPU time
• tms_stime: System CPU time
• tms_cutime: User CPU time of terminated child processes
• tms_cstime: System CPU time of terminated child processes
The processing time for a child process is included in the tms_cutime and tms_cstime elements of the
tms structure when the parent process waits for child process termination.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
jtms A handle of type tms created with PXFSTRUCTCREATE(3F).
itime An output integer variable for the number of system hardware clock ticks since some arbitrary
point in the past (for example, system startup time). This point does not change from one
invocation to another during the execution of the process.

004– 2165– 002 303

PXFTIMES ( 3F ) PXFTIMES ( 3F )

ierror An output integer variable that contains zero if PXFTIMES was successful or nonzero if
PXFTIMES was not successful.
PXFTIMES may return the EBADHANDLE error value if jtms is an invalid handle or has an incorrect handle
type.

EXAMPLES
This example shows how to use the PXFTIMES routine to retrieve system and user CPU time information
since the beginning of process execution.
pro gram tes tpxf
int eger itime, jtms, ierr, itmp
c cre ate the tms struct
cal l PXF STR UCTCRE ATE(’tms’ ,jt ms,ier r)
print *,’str uct create error = ’,i err
c cal l PXF TIM ES and print out ret urn ed inform ation
call PXFTIM ES(jtm s,itim e,i err)
pri nt *,’ time = ’,i tim e
cal l PXF INT GET(jt ms, ’tm s_utime’, itmp,ierr)
print *,’ tms_ut ime = ’,itmp,’ ’,ierr
cal l PXF INTGET (jt ms,’tm s_stime’,itm p,ierr)
pri nt *,’tms _stime = ’,itmp,’ ’,i err
call PXFINT GET(jt ms,’tm s_c utime’,it mp,ierr)
pri nt *,’tms _cu time = ’,i tmp,’ ’,ierr
call PXFINT GET (jtms,’tms_c stime’,itmp, ierr)
pri nt *,’ tms _cstim e = ’,i tmp ,’ ’,ierr
c free the tms str uct
cal l PXF STRUCT FRE E(jtms ,ierr)
end

SEE ALSO
times(2)
PXFSTRUCTCREATE(3F)

304 004– 2165– 002

PXFUCOMPARE ( 3F ) PXFUCOMPARE ( 3F )

NAME
PXFUCOMPARE – Compares unsigned integers

SYNOPSIS
SUBROUTINE PXFUCOMPARE (i1, i2, icmpr, idiff)
INTEGER i1, i2, icmpr, idiff

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFUCOMPARE routine performs comparisons of C unsigned integers returned by some IEEE
FORTRAN 77 routines.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
i1 An input integer variable for a C unsigned integer.
i2 An input integer variable for a C unsigned integer.
icmpr An output integer variable that, on return from the routine, contains one of these values:
– 1 If i1 < i2
0 If i1 = i2
1 If i1 > i2
All of the comparisons are made using C unsigned integer comparisons.
idiff An output integer variable that on return from the routine contains the absolute value of the
difference of i1 and i2. Since the values are C unsigned integers and FORTRAN 77 does not
directly support unsigned integers the value may be negative, which indicates the value is
beyond the maximum positive value of a FORTRAN 77 integer.

EXAMPLES
In this example, the program calls PXFTIMES(3F) to return the process time information and then uses
PXFUCOMPARE to determine if the system time was greater than 1000000000 clock ticks.

004– 2165– 002 305

PXFUCOMPARE ( 3F ) PXFUCOMPARE ( 3F )

pro gra m tes tpx f

int ege r iti me, jtm s, ier r, sti me, icm pr, idi ff

cal l PXF STR UCT CRE ATE (’t ms’ ,jt ms, ier r)
if (ie rr .ne . 0) the n
pri nt *,’ FAI LED : PXF STR UCT CRE ATE cal l wit h err or = ’,i err or
els e
cal l PXF TIM ES( jtm s,i tim e,i err )
if (ie rr .ne . 0) the n
pri nt *,’ FAI LED : PXF TIM ES cal l wit h err or = ’,i err or
els e
cal l PXF INT GET (jt ms, ’tm s_s tim e’, sti me, ier r)
if (ie rr .ne . 0) the n
pri nt *,’ FAI LED : PXF INT GET cal l for tms _st ime wit h err or = ’,i err or
els e
CAL L PXF UCO MPA RE( sti me, 100 000 000 0,i cmp r,i dif f)
if (ic mpr .eq . 1) the n
pri nt *,’ Sys tem tim e lon ger tha n 100 000 000 0 clo ck tic ks. ’
els e
pri nt *,’ Sys tem tim e les s tha n or equ al to 100 000 000 0 clo ck tic ks. ’
end if
end if
end if
end if
end

SEE ALSO
PXFTIMES(3F)

306 004– 2165– 002

PXFUMASK ( 3F ) PXFUMASK ( 3F )

NAME
PXFUMASK – Sets the file creation mask

SYNOPSIS
SUBROUTINE PXFUMASK (icmask, iprevcmask, ierror)
INTEGER icmask, iprevcmask, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFUMASK routine uses the umask(2) system call to change the file mode creation mask of the calling
process. Only the file permission bits of icmask are used.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
icmask An input integer variable for the new file mode creation mask. The symbolic constants used to
compose the file mask can be access by calling PXFCONST(3F).
iprevcmask An output integer variable for the old file mode creation mask.
ierror An output integer variable that will contain a status of zero if the routine was successful.

EXAMPLES
In this example, the program calls PXFUMASK with a file mode creation mask of octal 022. Then a file is
created using the new file creation mask.

004– 2165– 002 307

PXFUMASK ( 3F ) PXFUMASK ( 3F )

pro gra m pxf tes t

int ege r icm ask , ipr evc mas k, imo de, ifi lde s, ifi lem ode , ier ror
int ege r ite mp
int ege r jst at
cha rac ter *3 cma sk

cma sk = ’02 2’
rea d(c mas k,1 ) icm ask
1 for mat (O3 )
CAL L PXF UMA SK( icm ask , ipr evc mas k, ier ror )
CAL L PXF CON ST( ’S_ IRW XU’ ,im ode ,ie rro r)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF CON ST cal l for S_I RWX U wit h err or= ’,i err or
els e
CAL L PXF CON ST( ’S_ IRW XG’ ,it emp ,ie rro r)
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF CON ST cal l for S_I RWX G wit h err or= ’,i err or
els e
imo de = IOR (im ode ,it emp )
CAL L PXF CRE AT( ’/t mp/ tem pfi le’ , 0, imo de, ifi lde s, ier ror )
if (ie rro r .ne . 0) the n
pri nt *,’ FAI LED : PXF CRE AT cal l wit h err or = ’,i err or
els e
end if
end if
end

SEE ALSO
umask(2)
PXFCONST(3F)

308 004– 2165– 002

PXFUNAME ( 3F ) PXFUNAME ( 3F )

NAME
PXFUNAME – Retrieves the operating system name

SYNOPSIS
INTEGER junam, ierror
CALL PXFUNAME(junam, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFUNAME routine uses the uname() system call to get the components of the operating system name.
The components of the utsname structure are:
• sysname: Name of the operating system
• nodename: Name of node in the operating system
• release: Current release level of the operating system
• version: Current version level of the release
• machine: Name of hardware type currently executing the program
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
junam An input integer variable or array element containing a handle for a utsname structure. This
should have been created by a call to the PXFSTRUCTCREATE(3F) routine.
ierror An output integer variable that contains zero if PXFUNAME returned the structure successfully or
nonzero if PXFUNAME was unable to return the structure.

004– 2165– 002 309

PXFUNAME ( 3F ) PXFUNAME ( 3F )

EXAMPLES

pro gram test

intege r jun am, ier r, ile n
cha racter *15 sna me, nna me, rel , vers, mac h
cal l pxf struct cre ate(’u tsname ’,juna m,ierr )
cal l pxf uname( jun am,ier r)
IF (ierr. ne.0) then
print *,’FAI L: error from pxf uname = ’,ierr
els e
print *,’PAS S: No error from pxf uname = ’
end if
ilen = 0
cal l pxf strget (junam ,’sysn ame’,s name,i len,ie rr)
ile n = 0
call pxfstr get(ju nam,’node nam e’,nna me, ilen,ierr )
ilen = 0
call pxfstr get(ju nam,’rele ase’,r el, ilen,ierr )
ilen = 0
call pxfstr get(ju nam,’version ’,v ers,ilen, ier r)
ilen = 0
call pxfstr get(ju nam,’mach ine’,m ach,il en, ierr)
print *, ’sy sname= ’,snam e
print *, ’no dename =’,nname
print *, ’re lease= ’,rel
print *, ’ve rsion= ’,vers
print *, ’ma chine= ’,mach
cal l pxf struct fre e(juna m,ierr )

SEE ALSO
uname(2)
PXFSTRUCTCREATE(3F)

310 004– 2165– 002

PXFUNLINK ( 3F ) PXFUNLINK ( 3F )

NAME
PXFUNLINK – Removes a directory entry

SYNOPSIS
CHARACTER*n path
INTEGER ilen, ierror
CALL PXFUNLINK(path, ilen, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFUNLINK routine uses the unlink(2) system call to remove a directory entry for the named file.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
path An input character variable or array element containing the name of a file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all trailing
blanks are removed before calling unlink.
ierror An output integer variable that contains a zero if the named file was removed.
In addition to the errors returned by the unlink(2) system call, PXFUNLINK may return the following
errors:
EINVAL If ilen < 0 or ilen > LEN(path).
ENOMEM If PXFUNLINK is unable to obtain memory to copy path.

004– 2165– 002 311

PXFUNLINK ( 3F ) PXFUNLINK ( 3F )

EXAMPLES

pro gram test

charac ter*(1 2) pat h
intege r ile n, ier r
pat h = ’testf ile’
ile n = 0
cal l pxf unlink (path, ilen,i err)
if (ierr. ne.0) the n
pri nt *,’ FAIL: error fro m pxf unl ink = ’,i err
els e
print *,’PAS S: No err or fro m pxfunl ink = ’
endif
end

SEE ALSO
unlink(2)

312 004– 2165– 002

PXFWAIT ( 3F ) PXFWAIT ( 3F )

NAME
PXFWAIT, PXFWAITPID – Obtains information about a calling process’ child process

SYNOPSIS
SUBROUTINE PXFWAIT (istat, iretpid, ierror)
INTEGER istat, iretpid, ierror
SUBROUTINE PXFWAITPID (ipid, istat, ioptions, iretpid, ierror)
INTEGER ipid, istat, ioptions, iretpid, ierror

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The PXFWAIT routine uses the wait(2) system call to obtain information about one of the calling process’s
child processes.
The PXFWAITPID routine uses the waitpid(2) system call to obtain information about one of the calling
process’s child processes.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of arguments for this routine:
ipid An input integer variable containing the child process ID for which information is requested.
• If ipid is equal to – 1, status is requested for any child process; PXFWAITPID is then
equivalent to PXFWAIT.
• If ipid is greater than 0, it specifies the process ID of a single child process for which status
is requested.
• If ipid is equal to 0, status is requested for any child process with a process group ID that is
equal to that of the calling process.
• If ipid is less than – 1, status is requested for any child process with a process group ID that
is equal to the absolute value of ipid.
istat An output integer variable for the status information.
ioptions An input integer variable constructed from an inclusive OR of zero or more of the following
options:

004– 2165– 002 313

PXFWAIT ( 3F ) PXFWAIT ( 3F )

WNOHANG The waitpid system call does not suspend execution of the calling process if
status is not immediately available for one of the calling processes specified by
pid.
WUNTRACED If job control is supported, the status of any child processes specified by pid that
are stopped, and with a status that has not yet been reported since they stopped,
are also reported to the requesting process.
UNICOS and UNICOS/mk systems only:
WMTWAIT Waits for the children of any member of the multitasking group. In UNICOS 9.0
this is the default behavior for both wait and waitpid. The flag is still
provided for source compatibility. To get the previous behavior, see the
description of the WLWPWAIT flag.
WLWPWAIT Waits only for the immediate children of the calling light-weight process (LWP).
This flag is not recommended for general use.
iretpid An output integer variable for the child process ID.
ierror An output integer variable that contains zero if the routine was successful or nonzero if the
routine was not successful.
Any of the following error values may be returned:
ECHILD PXFWAIT: If the calling process has no existing unwaited-for child processes.
PXFWAITPID: The process or process group specified by ipid does not exist or is not a child
of the calling process.
EINTR If receipt of a signal other than the death-of-a-child-process signal.
EINVAL The value of the ioptions argument is not valid.

EXAMPLES

PXFWAIT example:

314 004– 2165– 002

PXFWAIT ( 3F ) PXFWAIT ( 3F )

program pxftes t
intege r ist at, iretpi d, ipi d, ier ror, i, j

CALL PXF FORK(i pid ,ierro r)

if (ie rror .ne. 0) the n
pri nt *,’FAI LED : PXF FOR K cal l failed wit h error = ’,i error
els e
if (ip id .eq . 0) the n
j = 0
do i=1,10 000 0
j = j + i
end do
sto p
else
CAL L PXF WAIT(i sta t,i retpid ,ie rro r)
if (ie rro r .eq . 0) then
pri nt *,’PAS SED: PXFWAI T nor mal test’
else
pri nt *,’ FAI LED : PXF WAIT call with err or = ’,i error
end if
end if
endif
end

PXFWAITPID example:

004– 2165– 002 315

PXFWAIT ( 3F ) PXFWAIT ( 3F )

program pxftes t
intege r ist at, iretpi d, ipi d, ier ror , i, j, ioptio ns

CALL PXF FOR K(ipid ,ierro r)

if (ie rro r .ne. 0) then
print *,’ FAILED : PXF FOR K cal l fai led with error = ’,ierr or
els e
if (ip id .eq . 0) then
j = 0
do i=1,10 000 0
j = j + i
end do
sto p
els e
iop tions = 0
CAL L PXF WAITPI D(i pid ,is tat,io pti ons ,iretp id,ier ror)
if (ie rror .eq. 0) the n
print *,’ PASSED : PXFWAI TPI D normal tes t’
els e
pri nt *,’FAI LED : PXF WAITPI D cal l with err or = ’,i error
endif
end if
endif
end

SEE ALSO
wait(2), waitpid(2)

316 004– 2165– 002

PXFWIFEXITED ( 3F ) PXFWIFEXITED ( 3F )

NAME
PXFWIFEXITED – Determines if child process exited with exit

SYNOPSIS
LOGICAL FUNCTION PXFWEXITED(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The logical function PXFWIFEXITED returns the value TRUE if the child process exited with exit().
IPXFWEXITSTATUS() returns part of the bits of argument x from exit(x).
The following argument is used for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

004– 2165– 002 317

PXFWIFEXITED ( 3F ) PXFWIFEXITED ( 3F )

program pxftes t
intege r ist at, iretpi d, ipi d, ier ror , i, j
log ical lwifex ited, PXF WIF EXITED

CALL PXF FORK(i pid ,ierro r)

if (ie rror .ne. 0) the n
print *,’ FAILED : PXF FOR K cal l fai led with error = ’,ierror
els e
if (ip id .eq . 0) then
j = 0
do i=1 ,10000 0
j = j + i
end do
sto p
els e
CAL L PXF WAIT(i stat,i ret pid ,ie rror)
if (ie rro r .eq . 0) the n
pri nt *,’PAS SED : PXF WAI T normal tes t’
lwifex ite d = PXF WIF EXITED (istat )
if (lwife xit ed .eqv. .TR UE. ) the n ! exit nor mal ly
print *,’ PXF WIF EXI TED tes t PASSED ’
els e
pri nt *,’PXF WIF EXI TED ret urned FAL SE’
pri nt *,’ PXF WAI T ist at = ’, ist at
pri nt *,’ PXFWIF EXI TED tes t FAI LED’
endif
else
print *,’ FAILED : PXF WAIT call with err or = ’,i err or
endif
endif
end if
end

SEE ALSO
IPXFWEXITSTATUS, PXFFORK(3F), PXFWAIT(3F)

318 004– 2165– 002

PXFWIFSIGNALED ( 3F ) PXFWIFSIGNALED ( 3F )

NAME
PXFWIFSIGNALED – Determines if the child process terminated because of a signal

SYNOPSIS
LOGICAL FUNCTION PXFWIFSIGNALED(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The PXFWIFSIGNALED logical function returns TRUE if the child process has terminated because of a
signal. The IPXFWTERMSIG(3F) function returns part of the signal that terminated the child process.
The following argument is used for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

pro gram pxf test

int ege r ist at, ire tpid, ipid, ierror , ichldi d, isi g
log ical lwi fsigna led, PXF WIFSIG NALED

CAL L PXF FOR K(ipid ,ierror)

if (ie rror .ne . 0) the n
print *,’ FAILED : PXFFOR K call fai led with err or = ’,i error
print *,’ ipid=’ ,ipid

004– 2165– 002 319

PXFWIFSIGNALED ( 3F ) PXFWIFSIGNALED ( 3F )

else
print *,’PAS SED : PXF FOR K cal l’
if( ipid.e q.0) then
call PXFGET PID(ic hld id, ierror )
if( ierror .ne . 0) then
print *, ’PX FGETPID FAILED , ierror =’, ierror
else
print *, ’PX FGETPID PASSED ’
endif
call PXFCON ST("SI GKI LL" ,isig, ier ror)
if( ierror .ne . 0) then
print *, ’PX FCO NST FAI LED , ier ror =’, ier ror
els e
print *, ’PX FCO NST PAS SED ’
end if
call PXFKIL L(ichl did ,is ig,ier ror )
if( ierror .ne . 0) then
print *, ’PX FKI LL FAI LED, ier ror=’, ierror
els e
print *, ’PX FKI LL PAS SED’
end if
els e
CAL L PXF WAI T(istat,i ret pid ,ierror)
if (ie rror .eq. 0) the n
print *,’ PAS SED: PXF WAIT normal test’
lwi fsi gnaled = PXF WIFSIG NALED(istat)
if (lw ifs ignale d .eq v. .TRUE. ) then ! exi t normal ly
pri nt *,’ PXF WIF SIGNAL ED test PAS SED’
else
pri nt *,’PXF WIF SIG NALED tes t FAILED ’
pri nt *,’PXF WIFSIG NAL ED return ed FALSE’
pri nt *,’PXF WAI T ist at = ’, istat
print *,’ iretpi d= ’, ire tpid
end if
else
print *,’FAI LED : PXF WAI T cal l with error = ’,ierror
print *,’PXF WAI T ist at = ’, istat
pri nt *,’iretpi d= ’, ire tpid
end if
endif
end if
print *,’ tes t com plete’
end

320 004– 2165– 002

PXFWIFSIGNALED ( 3F ) PXFWIFSIGNALED ( 3F )

SEE ALSO
IPXFTERMSIG(3F), PXFWAIT(3F)

004– 2165– 002 321

PXFWIFSTOPPED ( 3F ) PXFWIFSTOPPED ( 3F )

NAME
PXFWIFSTOPPED – Determines if a child process has stopped

SYNOPSIS
LOGICAL FUNCTION PXFWIFSTOPPED(istat)
INTEGER istat

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
The PXFWIFSTOPPED logical function returns the value TRUE if the child process has stopped.
The following argument is used for this routine:
istat An input integer variable with the PXFWAIT or PXFWAITPID output status argument.
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX systems,
the default kind is KIND=4.

EXAMPLES

322 004– 2165– 002

PXFWIFSTOPPED ( 3F ) PXFWIFSTOPPED ( 3F )

program pxftes t
intege r istat, ire tpid, ipi d, ierror , iop ts, isi g
logica l lwi fst opped, PXFWIF STO PPE D

CAL L PXF FORK(i pid ,ie rror)

if (ie rro r .ne . 0) the n
pri nt *,’FAI LED: PXFFOR K cal l fai led with err or = ’,i error
else
print *,’ FAILED : PXF FORK call failed wit h err or = ’,i err or
if (ip id. eq.0)t hen !child
cal l PXF GETPID (ic hld id, ier ror)
if (ierro r .ne . 0) the n
pri nt *, ’PXFGETPI D FAI LED , ier ror =’, ierror
print *, ’ic hld id= ’, ichldi d
els e
pri nt *, ’PXFGE TPI D PAS SED ’
end if
cal l PXF CON ST("SIGST OP" ,is ig, ierror )
if (ie rror .ne . 0) then
print *, ’PX FCONST FAI LED, ierror =’, ierror
print *, ’is ig=’, isi g
els e
pri nt *, ’PX FCONST PAS SED ’
end if
cal l PXF KIL L(ichldid ,is ig, ier ror)
if (ie rror .ne . 0) then
pri nt *, ’PXFKI LL FAI LED ier ror=’, ier ror
print *, ’ic hld id= ’, ich ldi d
print *, ’is ig= ’, isig
els e
print *, ’PX FKILL PAS SED ’
end if
sto p "CH ILD"
else
call PXFCON ST( "WU NTRACE D", iop ts, ierror )
if (ierro r .ne . 0) the n
pri nt *, ’PX FCO NST FAI LED , ier ror=’, ier ror
pri nt *, ’io pts =’, iop ts
else
print *, ’PXFCO NST PASSED ’
end if
cal l PXF WAITPI D(i pid ,istat ,io pts ,ir etpid, ierror )
if (ie rror.n e.0 )then
pri nt *, ’PXFWA ITP ID FAI LED, ierror =’, ier ror

004– 2165– 002 323

PXFWIFSTOPPED ( 3F ) PXFWIFSTOPPED ( 3F )

print *, ’ipid= ’, ipi d

pri nt *, ’iretp id= ’, iretpi d
pri nt *, ’iopts =’, iop ts
pri nt *, ’istat =’, ist at
els e
pri nt *, ’PXFWA ITP ID PASSED ’
end if
if (ip id .ne . iretpi d) the n
pri nt *,’ exp ected pid s of chi ld to equ al’
pri nt *,’ for k pid of child= ’,i pid
pri nt *,’ wai t pid of chi ld= ’,iret pid
endif
if (PXFWI FST OPPED( ist at) )th en
print *, ’PXFWI FST OPP ED PAS S’
els e
pri nt *, ’IP XFWSTO PSI G FAI L’
endif
call PXF CONST( "SIGKI LL" ,is ig,ier ror )
if (ie rror .ne. 0) the n
pri nt *, ’PX FCO NST FAI LED , ier ror =’, ier ror
pri nt *, ’is ig= ’, isig
else
print *, ’PXFCONST PAS SED’
end if
cal l PXF KILL(i pid ,is ig,ier ror )
if (ierro r .ne . 0) the n
pri nt *, ’PX FKILL FAI LED ier ror=’, ier ror
pri nt *, ’ip id= ’, ipid
pri nt *, ’is ig= ’, isig
else
print *, ’PXFKI LL PAS SED ’
end if
endif
endif
print *,’tes t comple te’
end

SEE ALSO
IPXFWSTOPSIG(3F), PXFWAIT(3F)

324 004– 2165– 002

PXFUTIME ( 3F ) PXFUTIME ( 3F )

NAME
PXFUTIME – Sets access and modification times of a file

SYNOPSIS
CHARACTER*n path
INTEGER ilen, jutimbuf, ierror
CALL PXFUTIME(path, ilen, jutimbuf, ierror)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

STANDARDS
IEEE standard interface for FORTRAN 77

DESCRIPTION
On IRIX systems, this routine is in libfortran.so which is linked by default when compiling programs
with the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
The routine PXFUTIME provides the functionality of the utime(2) system call.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX
systems, all arguments must be of default kind unless documented otherwise. On UNICOS and
UNICOS/mk, default kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default
kind is KIND=4.
The following is a list of valid arguments for this routine:
path An input character variable or array element containing the name of the file.
ilen An input integer variable containing the length of path in characters. If ilen is zero, all
trailing blanks are removed before calling utime.
jutimbuf An input integer variable. It is a handle for a structure of type utimbuf. The handle must
be created by a call to the PXFSTRUCTCREATE(3F) routine prior to the call to PXFUTIME.
The names of the components of the utimbuf structure are actime and modtime. These
components can be accessed through the PXFINTSET subroutine. The functionality obtained
in utime by passing a NULL can be obtained in PXFUTIME by passing a handle argument
with a value of zero.
ierror An output integer variable that contains zero if the call to utime was successful or nonzero if
the call to utime was not completed.

004– 2165– 002 325

PXFUTIME ( 3F ) PXFUTIME ( 3F )

In addition to the errors returned by the utime(2) system call, PXFUTIME may return the following errors:
EINVAL If ilen is less than 0 or ilen is greater than LEN(path).
ENOMEM If PXFUTIME is unable to obtain memory to copy path.
EBADHANDLE If jutimbuf is an invalid handle or has an incorrect handle type (UNICOS and UNICOS/mk
systems only).

EXAMPLES

pro gram test

charac ter*12 fil ea, fileb

intege r ile nfila, ile nfi lb, jut imbuf, ier r

! cre ate fil e

open(f ile =’exis tfile’ , uni t=9 , sta tus =’NEW’ )
write( 9,* ) ’HI ’, 1.2, 11, ’GO ODB YE’
endfil e 9
close 9

fil ea = ’exist fil e’

ilenfi la = 0
ilenfi lb = 0

! Set fil e access and modifi cat ion tim e to cur ren t tim e
cal l pxf utime( filea, ile nfi la,0,i err )
if (ierr.ne. 0) the n
print *,’ FAIL: pxf uti me’
print *,’ nonzer o sta tus on exi sti ng fil e = ’,i err
els e
print *,’ PASS: pxf uti me’
print *,’zer o sta tus on exi sti ng fil e’
end if

end

The output of this test on a UNICOS system is:

PASS: pxf uti me
zero status on existi ng fil e

326 004– 2165– 002

INDEX

32 bits from 64 bits write ............................................................................... writibm(3F)........................................................ 104

32-bit words write ........................................................................................... writibm(3F)........................................................ 104
Abort NAMELIST job ..................................................................................... rnlskip(3F) ......................................................... 76
Accept data ...................................................................................................... acptbad(3F) ......................................................... 19
Accesses a single string element of a structure component that is an array .. pxfestrget(3F) ................................................ 207
ACPTBAD(3F) ................................................................................................. acptbad(3F) ......................................................... 19
acptbad(3F) ................................................................................................. acptbad(3F) ......................................................... 19
Add characters for NAMELIST ....................................................................... rnl(3F) ................................................................... 73
alarm ................................................................................................................ pxfalarm(3F) ..................................................... 182
Allows an index to be used as the current index by creating a subindex ...... stindx(3F) ............................................................ 86
Allows components of a structure to be set or modified ................................ pxfintset(3F) ................................................... 251
Allows each NAMELIST variable to begin on a new line ............................. wnlline(3F) ......................................................... 96
Allows values stored in individual components of a structure to be
extracted and used ........................................................................................... pxfintget(3F) ................................................... 250
Allows values stored in individual components of a structure to be
extracted and used ........................................................................................... pxfstrget(3F) ................................................... 289
Allows values stored in individual components of a structure to be set ........ pxfstrset(3F) ................................................... 291
Alternate tape path (disable) ........................................................................... startsp(3F) ......................................................... 85
Analogous stride ............................................................................................. fflistio(3C) ..................................................... 137
APUTWA(3F) .................................................................................................... putwa(3F) .............................................................. 64
aputwa(3F) .................................................................................................... putwa(3F) .............................................................. 64
AQCLOSE(3F) ................................................................................................. aqclose(3F) ......................................................... 22
aqclose(3F) ................................................................................................. aqclose(3F) ......................................................... 22
AQIO ............................................................................................................... aqrecall(3F) ....................................................... 27
AQIO close ..................................................................................................... aqclose(3F) ......................................................... 22
AQIO dataset open .......................................................................................... aqopen(3F) ............................................................ 23
AQIO file close ............................................................................................... aqclose(3F) ......................................................... 22
AQIO status .................................................................................................... aqstat(3F) ............................................................ 29
AQIO wait ....................................................................................................... aqwait(3F) ............................................................ 31
AQIO write ..................................................................................................... aqwrite(3F) ......................................................... 32
AQIO(3F) ........................................................................................................ intro_io(3F) ......................................................... 9
aqio(3F) ........................................................................................................ intro_io(3F) ......................................................... 9
AQOPEN(3F) .................................................................................................... aqopen(3F) ............................................................ 23
aqopen(3F) .................................................................................................... aqopen(3F) ............................................................ 23
AQOPENM(3F) ................................................................................................. aqopen(3F) ............................................................ 23
aqopenm(3F) ................................................................................................. aqopen(3F) ............................................................ 23
AQREAD(3F) .................................................................................................... aqread(3F) ............................................................ 25
aqread(3F) .................................................................................................... aqread(3F) ............................................................ 25
AQREADC(3F) ................................................................................................. aqread(3F) ............................................................ 25
aqreadc(3F) ................................................................................................. aqread(3F) ............................................................ 25
AQRECALL(3F) ............................................................................................... aqrecall(3F) ....................................................... 27
aqrecall(3F) ............................................................................................... aqrecall(3F) ....................................................... 27
AQSTAT(3F) .................................................................................................... aqstat(3F) ............................................................ 29
aqstat(3F) .................................................................................................... aqstat(3F) ............................................................ 29
AQWAIT(3F) .................................................................................................... aqwait(3F) ............................................................ 31
aqwait(3F) .................................................................................................... aqwait(3F) ............................................................ 31
AQWRITE(3F) ................................................................................................. aqwrite(3F) ......................................................... 32

004– 2165– 002 Index-1

aqwrite(3F) ................................................................................................. aqwrite(3F) ......................................................... 32
AQWRITEC(3F) ............................................................................................... aqwrite(3F) ......................................................... 32
aqwritec(3F) ............................................................................................... aqwrite(3F) ......................................................... 32
ASNCTL(3F) .................................................................................................... asnctl(3F) ............................................................ 34
asnctl(3F) .................................................................................................... asnctl(3F) ............................................................ 34
ASNFILE(3F) ................................................................................................. assign(3F) ............................................................ 38
asnfile(3F) ................................................................................................. assign(3F) ............................................................ 38
ASNQFILE(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
asnqfile(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
ASNQUNIT(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
asnqunit(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
ASNRM(3F) ...................................................................................................... assign(3F) ............................................................ 38
asnrm(3F) ...................................................................................................... assign(3F) ............................................................ 38
ASNUNIT(3F) ................................................................................................. assign(3F) ............................................................ 38
asnunit(3F) ................................................................................................. assign(3F) ............................................................ 38
Assign environment ........................................................................................ assign(3F) ............................................................ 38
Assign options ................................................................................................. asnqfile(3F) ....................................................... 36
assign processing, C interface ......................................................................... ffassign(3C) ..................................................... 127
ASSIGN(3F) .................................................................................................... assign(3F) ............................................................ 38
assign(3F) .................................................................................................... assign(3F) ............................................................ 38
ASYNCDR(3F) ................................................................................................. asyncms(3F) ......................................................... 40
asyncdr(3F) ................................................................................................. asyncms(3F) ......................................................... 40
Asynchronous .................................................................................................. fflistio(3C) ..................................................... 137
Asynchronous .................................................................................................. ffreada(3C) ....................................................... 152
Asynchronous .................................................................................................. ffwritea(3C) ..................................................... 161
Asynchronous I/O ........................................................................................... ffreada(3C) ....................................................... 152
Asynchronous I/O status check ....................................................................... checkms(3F) ......................................................... 42
Asynchronous mode ........................................................................................ asyncms(3F) ......................................................... 40
Asynchronous read .......................................................................................... ffreada(3C) ....................................................... 152
Asynchronous read .......................................................................................... aqread(3F) ............................................................ 25
Asynchronous status ........................................................................................ aqstat(3F) ............................................................ 29
Asynchronous write ........................................................................................ ffwritea(3C) ..................................................... 161
Asynchronous write ........................................................................................ aqwrite(3F) ......................................................... 32
ASYNCMS(3F) ................................................................................................. asyncms(3F) ......................................................... 40
asyncms(3F) ................................................................................................. asyncms(3F) ......................................................... 40
Bad data .......................................................................................................... acptbad(3F) ......................................................... 19
Bad data skip .................................................................................................. skipbad(3F) ......................................................... 81
blanks for value ............................................................................................... fsup(3F)................................................................. 53
block special files ............................................................................................ pxfisblk(3F) ..................................................... 254
Block tape position ......................................................................................... settp(3F) .............................................................. 79
Blocks in file ................................................................................................... numblks(3F) ......................................................... 60
Buffer record into ............................................................................................ findms(3F) ............................................................ 49
Byte and bit manipulation ............................................................................... intro_pxf(3F) ................................................... 165
C interface for assign processing .................................................................... ffassign(3C) ..................................................... 127
C routines and calls ........................................................................................ intro_applibs(3F) ............................................. 1
callseq(3F) ................................................................................................. callseq(3F) ........................................................... 3
change output value ........................................................................................ fsup(3F)................................................................. 53
Changes the current directory to a specified directory ................................... pxfchdir(3F) ..................................................... 184
Changes the owner and group of a file .......................................................... pxfchown(3F) ..................................................... 189
Changes the root directory to a specified directory ........................................ pxfchroot(3F) ................................................... 191

Index-2 004– 2165– 002

Character changes NAMELIST ....................................................................... rnl(3F) ................................................................... 73
Character functions ......................................................................................... intro_pxf(3F) ................................................... 165
Character read ................................................................................................. readc(3F) .............................................................. 68
Character write ................................................................................................ writec(3F) .......................................................... 102
Check AQIO status ......................................................................................... aqstat(3F) ............................................................ 29
Check status of I/O ......................................................................................... checkms(3F) ......................................................... 42
Check tape position ......................................................................................... checktp(3F) ......................................................... 44
CHECKDR(3F) ................................................................................................. checkms(3F) ......................................................... 42
checkdr(3F) ................................................................................................. checkms(3F) ......................................................... 42
CHECKMS(3F) ................................................................................................. checkms(3F) ......................................................... 42
checkms(3F) ................................................................................................. checkms(3F) ......................................................... 42
Checks status of asynchronous random-access I/O operation ........................ checkms(3F) ......................................................... 42
Checks tape position ....................................................................................... checktp(3F) ......................................................... 44
Checks the accessibility of a named file ......................................................... pxfaccess(3F) ................................................... 180
Checks the status of asynchronous queued I/O requests ................................ aqstat(3F) ............................................................ 29
CHECKTP(3F) ................................................................................................. checktp(3F) ......................................................... 44
checktp(3F) ................................................................................................. checktp(3F) ......................................................... 44
child process exit ............................................................................................ pxfwifexited(3F) ............................................ 317
child process termination ................................................................................ ipxfwtermsig(3F) ............................................ 177
Clears all environment variables ..................................................................... pxfclearenv(3F) .............................................. 193
CLOSDR(3F) .................................................................................................... closms(3F) ............................................................ 46
closdr(3F) .................................................................................................... closms(3F) ............................................................ 46
Close and finalize random access file ............................................................. wclose(3F) ............................................................ 93
Close AQIO file .............................................................................................. aqclose(3F) ......................................................... 22
Close file ......................................................................................................... ffopen(3C) ......................................................... 141
Close volume .................................................................................................. closev(3F) ............................................................ 45
Closes an asynchronous queued I/O file ......................................................... aqclose(3F) ......................................................... 22
Closes volume and mounts next volume in Volume Identifier list ................ closev(3F) ............................................................ 45
CLOSEV(3F) .................................................................................................... closev(3F) ............................................................ 45
closev(3F) .................................................................................................... closev(3F) ............................................................ 45
CLOSMS(3F) .................................................................................................... closms(3F) ............................................................ 46
closms(3F) .................................................................................................... closms(3F) ............................................................ 46
Compares unsigned integers ........................................................................... pxfucompare(3F) .............................................. 305
Compatibility of libraries among machines .................................................... intro_applibs(3F) ............................................. 1
Component name ............................................................................................ pxfstructcreate(3F) ..................................... 295
Components ..................................................................................................... pxfintget(3F) ................................................... 250
Components ..................................................................................................... pxfintset(3F) ................................................... 251
Controls function of ASSIGN, ASNFILE, ASNUNIT, and ASNRM
routines ............................................................................................................ asnctl(3F) ............................................................ 34
Conversion input type ..................................................................................... rnltype(3F) ......................................................... 77
Converts to local time ..................................................................................... pxflocaltime(3F) ............................................ 266
Copies structure ............................................................................................... pxfstructcopy(3F) ......................................... 293
Create subindex ............................................................................................... stindx(3F) ............................................................ 86
Creates a link to a file ..................................................................................... pxflink(3F)........................................................ 264
Creates a new file or rewrites an existing file ................................................ pxfcreat(3F) ..................................................... 199
Creates a new session for a calling process ................................................... pxfsetsid(3F) ................................................... 281
Creates a process ............................................................................................. pxffork(3F)........................................................ 219
Creates an instance of the desired structure and returns a nonzero handle
in the argument jhandle .................................................................................. pxfstructcreate(3F) ..................................... 295
Data ................................................................................................................. ffread(3C) ......................................................... 149

004– 2165– 002 Index-3

Data accept ...................................................................................................... acptbad(3F) ......................................................... 19
Data bad skip .................................................................................................. skipbad(3F) ......................................................... 81
Data buffer a record ........................................................................................ findms(3F) ............................................................ 49
Data reading .................................................................................................... getwa(3F) .............................................................. 57
Data transfer (asynchronous) .......................................................................... aqread(3F) ............................................................ 25
Data writing .................................................................................................... write(3F) ............................................................ 100
Defines a group of processes to be associated with a global file. .................. glio_group(3F) ................................................ 163
delay process execution .................................................................................. pxfsleep(3F) ..................................................... 285
Delays process execution ................................................................................ pxfsleep(3F) ..................................................... 285
Delete characters for NAMELIST ................................................................... rnl(3F) ................................................................... 73
Deletes the instance of the structure referenced by jhandle ........................... pxfstructfree(3F) ......................................... 297
Delimiter NAMELIST change ......................................................................... wnl(3F) ................................................................... 94
Describes performance options available with the FFIO layers ..................... intro_ffio(3F) ................................................ 113
Details the calling sequence for UNICOS systems ........................................ callseq(3F) ........................................................... 3
Determines action if type mismatch occurs across equal sign on
NAMELIST input record ................................................................................. rnltype(3F) ......................................................... 77
Determines if a child process has stopped ..................................................... pxfwifstopped(3F) ......................................... 322
Determines if child process exited with exit ............................................... pxfwifexited(3F) ............................................ 317
Determines if file descriptor corresponds to a valid file descriptor ............... pxfisatty(3F) ................................................... 252
Determines if the child process terminated because of a signal .................... pxfwifsignaled(3F) ....................................... 319
directory file test ............................................................................................. pxfisdir(3F) ..................................................... 258
Disable EOV processing ................................................................................. setsp(3F) .............................................................. 78
Disables special tape processing ..................................................................... endsp(3F) .............................................................. 48
Disk random access write ............................................................................... writms(3F) .......................................................... 105
Echo lines NAMELIST .................................................................................... rnlecho(3F) ......................................................... 75
Enable EOV processing .................................................................................. setsp(3F) .............................................................. 78
Enables and disables EOV processing ............................................................ setsp(3F) .............................................................. 78
Enables special tape processing ...................................................................... startsp(3F) ......................................................... 85
ENDSP(3F) ...................................................................................................... endsp(3F) .............................................................. 48
endsp(3F) ...................................................................................................... endsp(3F) .............................................................. 48
Environment list .............................................................................................. pxfgetenv(3F) ................................................... 226
Environment name .......................................................................................... pxfgetenv(3F) ................................................... 226
EOV processing .............................................................................................. setsp(3F) .............................................................. 78
Error unit NAMELIST ..................................................................................... rnlecho(3F) ......................................................... 75
error values returned ....................................................................................... pxfconst(3F) ..................................................... 195
Executes a new process image file ................................................................. pxfexecv(3F) ..................................................... 209
ffassign(3C) .............................................................................................. ffassign(3C) ..................................................... 127
ffbksp(3C) ................................................................................................... ffseek(3C) ......................................................... 156
ffbkspf(3C) ................................................................................................. ffseek(3C) ......................................................... 156
ffclose(3C) ................................................................................................. ffopen(3C) ......................................................... 141
ffclosef(3C) .............................................................................................. ffopen(3C) ......................................................... 141
fffcntl(3C) ................................................................................................. fffcntl(3C) ....................................................... 128
ffflush(3C) ................................................................................................. ffread(3C) ......................................................... 149
FFIO ................................................................................................................ ffstrerror(3C) ................................................ 160
FFIO ................................................................................................................ ffwritea(3C) ..................................................... 161
FFIO error string ............................................................................................. ffstrerror(3C) ................................................ 160
FFIO specifications ......................................................................................... intro_ffio(3F) ................................................ 113
FFIO(3F) ........................................................................................................ intro_ffio(3F) ................................................ 113
ffio(3F) ........................................................................................................ intro_ffio(3F) ................................................ 113
ffiolock(3C) .............................................................................................. ffiolock(3C) ..................................................... 136

Index-4 004– 2165– 002

ffiounlock(3C) .......................................................................................... ffiolock(3C) ..................................................... 136
fflistio(3C) .............................................................................................. fflistio(3C) ..................................................... 137
fflistreq structure .................................................................................... fflistio(3C) ..................................................... 137
ffopen(3C) ................................................................................................... ffopen(3C) ......................................................... 141
ffopenf(3C) ................................................................................................. ffopen(3C) ......................................................... 141
ffopens(3C) ................................................................................................. ffopen(3C) ......................................................... 141
ffpos(3C) ...................................................................................................... ffpos(3C) ............................................................ 145
ffread(3C) ................................................................................................... ffread(3C) ......................................................... 149
ffreada(3C) ................................................................................................. ffreada(3C) ....................................................... 152
ffreadf(3C) ................................................................................................. ffread(3C) ......................................................... 149
ffseek(3C) ................................................................................................... ffseek(3C) ......................................................... 156
ffseekf(3C) ................................................................................................. ffseek(3C) ......................................................... 156
ffsetsp(3C) ................................................................................................. ffsetsp(3C) ....................................................... 159
FFSTRERROR(3C) .......................................................................................... ffstrerror(3C) ................................................ 160
ffstrerror(3C) .......................................................................................... ffstrerror(3C) ................................................ 160
ffweod(3C) ................................................................................................... ffread(3C) ......................................................... 149
ffweodf(3C) ................................................................................................. ffread(3C) ......................................................... 149
ffweof(3C) ................................................................................................... ffread(3C) ......................................................... 149
ffweoff(3C) ................................................................................................. ffread(3C) ......................................................... 149
ffwrite(3C) ................................................................................................. ffread(3C) ......................................................... 149
ffwritea(3C) .............................................................................................. ffwritea(3C) ..................................................... 161
ffwritef(3C) .............................................................................................. ffread(3C) ......................................................... 149
FIFO speical file test ....................................................................................... pxfisfifo(3F) ................................................... 260
File close (random access) .............................................................................. wclose(3F) ............................................................ 93
File descriptor ................................................................................................. pxffileno(3F) ................................................... 218
File descriptor ................................................................................................. gtstdptr(3F) ....................................................... 59
file descriptor check ........................................................................................ pxfisatty(3F) ................................................... 252
File memory reduce ........................................................................................ stindx(3F) ............................................................ 86
File open ......................................................................................................... openms(3F) ............................................................ 61
File size in blocks ........................................................................................... numblks(3F) ......................................................... 60
File stride ........................................................................................................ fflistio(3C) ..................................................... 137
FILE structure ................................................................................................. gtstdptr(3F) ....................................................... 59
File tape position ............................................................................................. settp(3F) .............................................................. 79
fileattr(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
Finalizes changes and closes word-addressable, random-access file .............. wclose(3F) ............................................................ 93
FINDMS(3F) .................................................................................................... findms(3F) ............................................................ 49
findms(3F) .................................................................................................... findms(3F) ............................................................ 49
Flexible File I/O .............................................................................................. fffcntl(3C) ....................................................... 128
Flexible File I/O .............................................................................................. ffopen(3C) ......................................................... 141
Flexible File I/O .............................................................................................. ffpos(3C) ............................................................ 145
Flexible File I/O .............................................................................................. ffread(3C) ......................................................... 149
Flexible File I/O .............................................................................................. ffseek(3C) ......................................................... 156
Flexible File I/O .............................................................................................. ffsetsp(3C) ....................................................... 159
Flock structure ................................................................................................. pxffcntl(3F) ..................................................... 216
FLUSH(3F) ...................................................................................................... flush(3F) .............................................................. 51
flush(3F) ...................................................................................................... flush(3F) .............................................................. 51
Foreign dataset conversion .............................................................................. ffopen(3C) ......................................................... 141
Foreign dataset conversion .............................................................................. ffread(3C) ......................................................... 149
Foreign dataset conversion .............................................................................. ffseek(3C) ......................................................... 156
Format output control ..................................................................................... wnl(3F) ................................................................... 94

004– 2165– 002 Index-5

Fortran output change ..................................................................................... fsup(3F)................................................................. 53
FSUP(3F) ........................................................................................................ fsup(3F)................................................................. 53
fsup(3F) ........................................................................................................ fsup(3F)................................................................. 53
FSUPC(3F) ...................................................................................................... fsup(3F)................................................................. 53
fsupc(3F) ...................................................................................................... fsup(3F)................................................................. 53
Full record (read) ............................................................................................ readc(3F) .............................................................. 68
Full-record mode ............................................................................................. write(3F) ............................................................ 100
Full-record read ............................................................................................... read(3F)................................................................. 66
Function control (ASSIGN) ............................................................................ asnctl(3F) ............................................................ 34
Function of ASSIGN and other routines ........................................................ asnctl(3F) ............................................................ 34
Generates terminal pathname .......................................................................... pxfctermid(3F) ................................................ 202
Get FFIO error message string ....................................................................... ffstrerror(3C) ................................................ 160
Gets effective user ID ..................................................................................... pxfgeteuid(3F) ................................................ 229
Gets group information using the group ID ................................................... pxfgetgrgid(3F) .............................................. 231
Gets group information using the group name ............................................... pxfgetgrnam(3F) .............................................. 233
Gets information about an opened tape file .................................................... gettp(3F) .............................................................. 54
Gets password information about login name ................................................ pxfgetpwnam(3F) .............................................. 245
Gets password information by using user ID ................................................. pxfgetpwuid(3F) .............................................. 247
Gets process times .......................................................................................... pxftimes(3F) ..................................................... 303
Gets supplementary group IDs ........................................................................ pxfgetgroups(3F) ............................................ 235
Gets system time ............................................................................................. pxftime(3F)........................................................ 301
Gets the effective group ID ............................................................................ pxfgetegid(3F) ................................................ 225
Gets the parent process ID .............................................................................. pxfgetppid(3F) ................................................ 243
Gets the pathname of the working directory .................................................. pxfgetcwd(3F) ................................................... 223
Gets the process group ID .............................................................................. pxfgetpgrp(3F) ................................................ 239
Gets the process ID ......................................................................................... pxfgetpid(3F) ................................................... 241
Gets the real group ID .................................................................................... pxfgetgid(3F) ................................................... 230
Gets the real user ID ....................................................................................... pxfgetuid(3F) ................................................... 249
Gets user name ................................................................................................ pxfgetlogin(3F) .............................................. 237
GETTP(3F) ...................................................................................................... gettp(3F) .............................................................. 54
gettp(3F) ...................................................................................................... gettp(3F) .............................................................. 54
GETWA(3F) ...................................................................................................... getwa(3F) .............................................................. 57
getwa(3F) ...................................................................................................... getwa(3F) .............................................................. 57
glio_group(3F) .......................................................................................... glio_group(3F) ................................................ 163
glio_group_mpi(3F) ................................................................................. glio_group(3F) ................................................ 163
glio_group_shmem(3F) ............................................................................ glio_group(3F) ................................................ 163
GTSTDPTR(3F) ............................................................................................... gtstdptr(3F) ....................................................... 59
gtstdptr(3F) ............................................................................................... gtstdptr(3F) ....................................................... 59
IBM floating-point .......................................................................................... readibm(3F) ......................................................... 70
IBM words read .............................................................................................. readibm(3F) ......................................................... 70
IBM words write ............................................................................................. writibm(3F)........................................................ 104
IBM-from-Cray read ....................................................................................... readibm(3F) ......................................................... 70
IEEE(3F) ........................................................................................................ intro_pxf(3F) ................................................... 165
Index (write master) ........................................................................................ closms(3F) ............................................................ 46
Initial value ..................................................................................................... pxfstructcreate(3F) ..................................... 295
Initiates a list of I/O requests using flexible file I/O ...................................... fflistio(3C) ..................................................... 137
Initiates EOV processing for files opened using flexible file I/O .................. ffsetsp(3C) ....................................................... 159
Input ................................................................................................................ read(3F)................................................................. 66
Input type mismatch ........................................................................................ rnltype(3F) ......................................................... 77
Input wait for end ........................................................................................... waitms(3F) ............................................................ 91

Index-6 004– 2165– 002

Interlanguage calls .......................................................................................... intro_applibs(3F) ............................................. 1
interpret child process exit .............................................................................. pxfwifexited(3F) ............................................ 317
interpret exit argument .................................................................................... ipxfwexitstatus(3F) ..................................... 171
interpret signal number ................................................................................... ipxfwstopsig(3F) ............................................ 174
intro1(3F) .................................................................................................... intro_applibs(3F) ............................................. 1
intro5(3F) .................................................................................................... intro_io(3F) ......................................................... 9
intro9(3F) .................................................................................................... intro_pxf(3F) ................................................... 165
INTRO_APPLIBS(3F) ................................................................................... intro_applibs(3F) ............................................. 1
intro_applibs(3F) ................................................................................... intro_applibs(3F) ............................................. 1
Introduction to CrayLibs Application Libraries .............................................. intro_applibs(3F) ............................................. 1
Introduction to Fortran-callable I/O routines .................................................. intro_io(3F) ......................................................... 9
introduction to I/O routines ............................................................................. intro_io(3F) ......................................................... 9
Introduction to PXF POSIX library ................................................................ intro_pxf(3F) ................................................... 165
INTRO_FFIO(3F) .......................................................................................... intro_ffio(3F) ................................................ 113
intro_ffio(3F) .......................................................................................... intro_ffio(3F) ................................................ 113
INTRO_IO(3F) ............................................................................................... intro_io(3F) ......................................................... 9
intro_io(3F) ............................................................................................... intro_io(3F) ......................................................... 9
INTRO_PXF(3F) ............................................................................................. intro_pxf(3F) ................................................... 165
intro_pxf(3F) ............................................................................................. intro_pxf(3F) ................................................... 165
intro_specialibs(3F) ............................................................................ intro_pxf(3F) ................................................... 165
I/O asynchronous ............................................................................................ aqopen(3F) ............................................................ 23
I/O check of status .......................................................................................... checkms(3F) ......................................................... 42
I/O mode (asynchronous) ................................................................................ asyncms(3F) ......................................................... 40
I/O mode to synchronous ................................................................................ syncms(3F) ............................................................ 88
I/O open .......................................................................................................... openms(3F) ............................................................ 61
I/O read (asynchronous) .................................................................................. aqread(3F) ............................................................ 25
I/O request ....................................................................................................... ffreada(3C) ....................................................... 152
I/O requests ..................................................................................................... fflistio(3C) ..................................................... 137
I/O routines ..................................................................................................... intro_io(3F) ......................................................... 9
I/O wait (AQIO) ............................................................................................. aqwait(3F) ............................................................ 31
I/O wait (asynchronous) .................................................................................. aqwait(3F) ............................................................ 31
I/O wait (asynchronous operation) .................................................................. waitms(3F) ............................................................ 91
I/O write (AQIO) ............................................................................................ aqwrite(3F) ......................................................... 32
IPXFARGC(3F) ............................................................................................... ipxfargc(3F) ..................................................... 170
ipxfargc(3F) ............................................................................................... ipxfargc(3F) ..................................................... 170
IPXFCONST(3F) ............................................................................................. pxfconst(3F) ..................................................... 195
ipxfconst(3F) ............................................................................................. pxfconst(3F) ..................................................... 195
IPXFWEXITSTATUS(3F) .............................................................................. ipxfwexitstatus(3F) ..................................... 171
ipxfwexitstatus(3F) .............................................................................. ipxfwexitstatus(3F) ..................................... 171
IPXFWSTOPSIG(3F) ...................................................................................... ipxfwstopsig(3F) ............................................ 174
ipxfwstopsig(3F) ...................................................................................... ipxfwstopsig(3F) ............................................ 174
IPXFWTERMSIG(3F) ...................................................................................... ipxfwtermsig(3F) ............................................ 177
ipxfwtermsig(3F) ...................................................................................... ipxfwtermsig(3F) ............................................ 177
ISUP(3F) ........................................................................................................ fsup(3F)................................................................. 53
isup(3F) ........................................................................................................ fsup(3F)................................................................. 53
ISUPC(3F) ...................................................................................................... fsup(3F)................................................................. 53
isupc(3F) ...................................................................................................... fsup(3F)................................................................. 53
Length of output line ...................................................................................... wnllong(3F) ......................................................... 97
Library buffering ............................................................................................. pxffileno(3F) ................................................... 218
Line length on output ...................................................................................... wnllong(3F) ......................................................... 97

004– 2165– 002 Index-7

List .................................................................................................................. fflistio(3C) ..................................................... 137
Makes bad data available ................................................................................ acptbad(3F) ......................................................... 19
Manipulate files ............................................................................................... fffcntl(3C) ....................................................... 128
Manipulate files ............................................................................................... ffpos(3C) ............................................................ 145
Manipulate files ............................................................................................... ffsetsp(3C) ....................................................... 159
Manipulates characters recognized by NAMELIST ........................................ rnl(3F) ................................................................... 73
Master index (write) ........................................................................................ closms(3F) ............................................................ 46
Memory less for file ........................................................................................ stindx(3F) ............................................................ 86
Mode (asynchronous) ...................................................................................... asyncms(3F) ......................................................... 40
Mode to synchronous ...................................................................................... syncms(3F) ............................................................ 88
modify output value ........................................................................................ fsup(3F)................................................................. 53
Mount next volume ......................................................................................... closev(3F) ............................................................ 45
NAMELIST delimiter change .......................................................................... wnl(3F) ................................................................... 94
NAMELIST error unit ..................................................................................... rnlecho(3F) ......................................................... 75
NAMELIST input changes .............................................................................. rnl(3F) ................................................................... 73
NAMELIST record skip ................................................................................... rnlskip(3F) ......................................................... 76
NAMELIST variable on new line .................................................................... wnlline(3F) ......................................................... 96
NUMBLKS(3F) ................................................................................................. numblks(3F) ......................................................... 60
numblks(3F) ................................................................................................. numblks(3F) ......................................................... 60
Obtains information about a calling process’ child process ........................... pxfwait(3F)........................................................ 313
Open AQIO file ............................................................................................... aqopen(3F) ............................................................ 23
Open file .......................................................................................................... ffopen(3C) ......................................................... 141
Open file .......................................................................................................... openms(3F) ............................................................ 61
Open random access ....................................................................................... wopen(3F) .............................................................. 98
OPENDR(3F) .................................................................................................... openms(3F) ............................................................ 61
opendr(3F) .................................................................................................... openms(3F) ............................................................ 61
OPENMS(3F) .................................................................................................... openms(3F) ............................................................ 61
openms(3F) .................................................................................................... openms(3F) ............................................................ 61
Opens a file for asynchronous queued I/O ..................................................... aqopen(3F) ............................................................ 23
Opens a local file as a random-access file that can be accessed or
changed by the record-addressable, random-access file I/O routines ............. openms(3F) ............................................................ 61
Opens a word-addressable, random-access file ............................................... wopen(3F) .............................................................. 98
Opens or closes a file using flexible file I/O .................................................. ffopen(3C) ......................................................... 141
Output characters ............................................................................................ writec(3F) .......................................................... 102
Output data ...................................................................................................... write(3F) ............................................................ 100
Output format control ..................................................................................... wnl(3F) ................................................................... 94
Output line length ........................................................................................... wnllong(3F) ......................................................... 97
Output unit NAMELIST .................................................................................. rnlecho(3F) ......................................................... 75
output value change ........................................................................................ fsup(3F)................................................................. 53
Output wait for end ......................................................................................... waitms(3F) ............................................................ 91
Packing routines .............................................................................................. intro_pxf(3F) ................................................... 165
Partial record (read) ........................................................................................ readc(3F) .............................................................. 68
Partial-record mode ......................................................................................... write(3F) ............................................................ 100
Partial-record read ........................................................................................... read(3F)................................................................. 66
Pascal routines and calls ................................................................................. intro_applibs(3F) ............................................. 1
Performs directory operations ......................................................................... pxfdirectory(3F) ............................................ 204
Performs functions on files opened using flexible file I/O ............................. fffcntl(3C) ....................................................... 128
Ported COS routines ....................................................................................... intro_pxf(3F) ................................................... 165
Position at tape block ...................................................................................... settp(3F) .............................................................. 79
Position information ........................................................................................ gettp(3F) .............................................................. 54

Index-8 004– 2165– 002

Positions a tape file at a tape block and/or a tape volume ............................. settp(3F) .............................................................. 79
Positions files opened using flexible file I/O .................................................. ffpos(3C) ............................................................ 145
Posix routine ................................................................................................... ipxfargc(3F) ..................................................... 170
Posix routine ................................................................................................... pxfgetarg(3F) ................................................... 222
process execution delay .................................................................................. pxfsleep(3F) ..................................................... 285
Provide locking for FFIO functions ................................................................ ffiolock(3C) ..................................................... 136
Provides a Fortran interface to the open(2) system call ............................... pxfopen(3F)........................................................ 268
Provides a subset of fcntl(2) functionality, except the third argument is
always an integer ............................................................................................ pxffcntl(3F) ..................................................... 216
Provides asynchronous read using flexible file I/O ........................................ ffreada(3C) ....................................................... 152
Provides asynchronous write using flexible file I/O ....................................... ffwritea(3C) ..................................................... 161
Provides flexible file I/O ................................................................................. ffread(3C) ......................................................... 149
Provides library interface to assign processing ............................................... ffassign(3C) ..................................................... 127
Provides library interface to assign processing .......................................... assign(3F) ............................................................ 38
Provides user control of NAMELIST output format ....................................... wnl(3F) ................................................................... 94
PUTWA(3F) ...................................................................................................... putwa(3F) .............................................................. 64
putwa(3F) ...................................................................................................... putwa(3F) .............................................................. 64
PXFACCESS(3F) ............................................................................................. pxfaccess(3F) ................................................... 180
pxfaccess(3F) ............................................................................................. pxfaccess(3F) ................................................... 180
PXFALARM(3F) ............................................................................................... pxfalarm(3F) ..................................................... 182
pxfalarm(3F) ............................................................................................... pxfalarm(3F) ..................................................... 182
PXFCHDIR(3F) ............................................................................................... pxfchdir(3F) ..................................................... 184
pxfchdir(3F) ............................................................................................... pxfchdir(3F) ..................................................... 184
PXFCHMOD(3F) ............................................................................................... pxfchmod(3F) ..................................................... 186
pxfchmod(3F) ............................................................................................... pxfchmod(3F) ..................................................... 186
PXFCHOWN(3F) ............................................................................................... pxfchown(3F) ..................................................... 189
pxfchown(3F) ............................................................................................... pxfchown(3F) ..................................................... 189
PXFCHROOT(3F) ............................................................................................. pxfchroot(3F) ................................................... 191
pxfchroot(3F) ............................................................................................. pxfchroot(3F) ................................................... 191
PXFCLEARENV(3F) ........................................................................................ pxfclearenv(3F) .............................................. 193
pxfclearenv(3F) ........................................................................................ pxfclearenv(3F) .............................................. 193
pxfclosedir(3F) ........................................................................................ pxfdirectory(3F) ............................................ 204
PXFCLOSEDIR,(3F) ...................................................................................... pxfdirectory(3F) ............................................ 204
PXFCONST(3F) ............................................................................................... pxfconst(3F) ..................................................... 195
pxfconst(3F) ............................................................................................... pxfconst(3F) ..................................................... 195
PXFCREAT(3F) ............................................................................................... pxfcreat(3F) ..................................................... 199
pxfcreat(3F) ............................................................................................... pxfcreat(3F) ..................................................... 199
PXFCTERMID(3F) .......................................................................................... pxfctermid(3F) ................................................ 202
pxfctermid(3F) .......................................................................................... pxfctermid(3F) ................................................ 202
pxfdirectory(3F) ...................................................................................... pxfdirectory(3F) ............................................ 204
PXFESTRGET(3F) .......................................................................................... pxfestrget(3F) ................................................ 207
pxfestrget(3F) .......................................................................................... pxfestrget(3F) ................................................ 207
PXFEXECV(3F) ............................................................................................... pxfexecv(3F) ..................................................... 209
pxfexecv(3F) ............................................................................................... pxfexecv(3F) ..................................................... 209
PXFEXECVE(3F) ............................................................................................. pxfexecv(3F) ..................................................... 209
pxfexecve(3F) ............................................................................................. pxfexecv(3F) ..................................................... 209
PXFEXECVP(3F) ............................................................................................. pxfexecv(3F) ..................................................... 209
pxfexecvp(3F) ............................................................................................. pxfexecv(3F) ..................................................... 209
PXFFCNTL(3F) ............................................................................................... pxffcntl(3F) ..................................................... 216
pxffcntl(3F) ............................................................................................... pxffcntl(3F) ..................................................... 216

004– 2165– 002 Index-9

PXFFILENO(3F) ............................................................................................. pxffileno(3F) ................................................... 218
pxffileno(3F) ............................................................................................. pxffileno(3F) ................................................... 218
PXFFORK(3F) ................................................................................................. pxffork(3F)........................................................ 219
pxffork(3F) ................................................................................................. pxffork(3F)........................................................ 219
PXFGETARG(3F) ............................................................................................. pxfgetarg(3F) ................................................... 222
pxfgetarg(3F) ............................................................................................. pxfgetarg(3F) ................................................... 222
PXFGETCWD(3F) ............................................................................................. pxfgetcwd(3F) ................................................... 223
pxfgetcwd(3F) ............................................................................................. pxfgetcwd(3F) ................................................... 223
PXFGETEGID(3F) .......................................................................................... pxfgetegid(3F) ................................................ 225
pxfgetegid(3F) .......................................................................................... pxfgetegid(3F) ................................................ 225
PXFGETENV(3F) ............................................................................................. pxfgetenv(3F) ................................................... 226
pxfgetenv(3F) ............................................................................................. pxfgetenv(3F) ................................................... 226
PXFGETEUID(3F) .......................................................................................... pxfgeteuid(3F) ................................................ 229
pxfgeteuid(3F) .......................................................................................... pxfgeteuid(3F) ................................................ 229
PXFGETGID(3F) ............................................................................................. pxfgetgid(3F) ................................................... 230
pxfgetgid(3F) ............................................................................................. pxfgetgid(3F) ................................................... 230
PXFGETGRGID(3F) ........................................................................................ pxfgetgrgid(3F) .............................................. 231
pxfgetgrgid(3F) ........................................................................................ pxfgetgrgid(3F) .............................................. 231
PXFGETGRNAM(3F) ........................................................................................ pxfgetgrnam(3F) .............................................. 233
pxfgetgrnam(3F) ........................................................................................ pxfgetgrnam(3F) .............................................. 233
PXFGETGROUPS(3F) ...................................................................................... pxfgetgroups(3F) ............................................ 235
pxfgetgroups(3F) ...................................................................................... pxfgetgroups(3F) ............................................ 235
PXFGETLOGIN(3F) ........................................................................................ pxfgetlogin(3F) .............................................. 237
pxfgetlogin(3F) ........................................................................................ pxfgetlogin(3F) .............................................. 237
PXFGETPGRP(3F) .......................................................................................... pxfgetpgrp(3F) ................................................ 239
pxfgetpgrp(3F) .......................................................................................... pxfgetpgrp(3F) ................................................ 239
PXFGETPID(3F) ............................................................................................. pxfgetpid(3F) ................................................... 241
pxfgetpid(3F) ............................................................................................. pxfgetpid(3F) ................................................... 241
PXFGETPPID(3F) .......................................................................................... pxfgetppid(3F) ................................................ 243
pxfgetppid(3F) .......................................................................................... pxfgetppid(3F) ................................................ 243
PXFGETPWNAM(3F) ........................................................................................ pxfgetpwnam(3F) .............................................. 245
pxfgetpwnam(3F) ........................................................................................ pxfgetpwnam(3F) .............................................. 245
PXFGETPWUID(3F) ........................................................................................ pxfgetpwuid(3F) .............................................. 247
pxfgetpwuid(3F) ........................................................................................ pxfgetpwuid(3F) .............................................. 247
PXFGETUID(3F) ............................................................................................. pxfgetuid(3F) ................................................... 249
pxfgetuid(3F) ............................................................................................. pxfgetuid(3F) ................................................... 249
PXFINTGET(3F) ............................................................................................. pxfintget(3F) ................................................... 250
pxfintget(3F) ............................................................................................. pxfintget(3F) ................................................... 250
PXFINTSET(3F) ............................................................................................. pxfintset(3F) ................................................... 251
pxfintset(3F) ............................................................................................. pxfintset(3F) ................................................... 251
PXFISATTY(3F) ............................................................................................. pxfisatty(3F) ................................................... 252
pxfisatty(3F) ............................................................................................. pxfisatty(3F) ................................................... 252
PXFISBLK(3F) ............................................................................................... pxfisblk(3F) ..................................................... 254
pxfisblk(3F) ............................................................................................... pxfisblk(3F) ..................................................... 254
PXFISCHR(3F) ............................................................................................... pxfischr(3F) ..................................................... 256
pxfischr(3F) ............................................................................................... pxfischr(3F) ..................................................... 256
PXFISCONST(3F) .......................................................................................... pxfconst(3F) ..................................................... 195
pxfisconst(3F) .......................................................................................... pxfconst(3F) ..................................................... 195
PXFISDIR(3F) ............................................................................................... pxfisdir(3F) ..................................................... 258
pxfisdir(3F) ............................................................................................... pxfisdir(3F) ..................................................... 258

Index-10 004– 2165– 002

PXFISFIFO(3F) ............................................................................................. pxfisfifo(3F) ................................................... 260
pxfisfifo(3F) ............................................................................................. pxfisfifo(3F) ................................................... 260
PXFISREG(3F) ............................................................................................... pxfisreg(3F) ..................................................... 262
pxfisreg(3F) ............................................................................................... pxfisreg(3F) ..................................................... 262
PXFLINK(3F) ................................................................................................. pxflink(3F)........................................................ 264
pxflink(3F) ................................................................................................. pxflink(3F)........................................................ 264
PXFLOCALTIME(3F) ...................................................................................... pxflocaltime(3F) ............................................ 266
pxflocaltime(3F) ...................................................................................... pxflocaltime(3F) ............................................ 266
PXFOPEN(3F) ................................................................................................. pxfopen(3F)........................................................ 268
pxfopen(3F) ................................................................................................. pxfopen(3F)........................................................ 268
PXFOPENDIR(3F) .......................................................................................... pxfdirectory(3F) ............................................ 204
pxfopendir(3F) .......................................................................................... pxfdirectory(3F) ............................................ 204
PXFREADDIR(3F) .......................................................................................... pxfdirectory(3F) ............................................ 204
pxfreaddir(3F) .......................................................................................... pxfdirectory(3F) ............................................ 204
PXFRENAME(3F) ............................................................................................. pxfrename(3F) ................................................... 271
pxfrename(3F) ............................................................................................. pxfrename(3F) ................................................... 271
PXFREWINDDIR(3F) ...................................................................................... pxfdirectory(3F) ............................................ 204
pxfrewinddir(3F) ...................................................................................... pxfdirectory(3F) ............................................ 204
PXFRMDIR(3F) ............................................................................................... pxfrmdir(3F) ..................................................... 273
pxfrmdir(3F) ............................................................................................... pxfrmdir(3F) ..................................................... 273
PXFSETENV(3F) ............................................................................................. pxfsetenv(3F) ................................................... 275
pxfsetenv(3F) ............................................................................................. pxfsetenv(3F) ................................................... 275
PXFSETGID(3F) ............................................................................................. pxfsetgid(3F) ................................................... 277
pxfsetgid(3F) ............................................................................................. pxfsetgid(3F) ................................................... 277
PXFSETPGID(3F) .......................................................................................... pxfsetpgid(3F) ................................................ 279
pxfsetpgid(3F) .......................................................................................... pxfsetpgid(3F) ................................................ 279
PXFSETSID(3F) ............................................................................................. pxfsetsid(3F) ................................................... 281
pxfsetsid(3F) ............................................................................................. pxfsetsid(3F) ................................................... 281
PXFSETUID(3F) ............................................................................................. pxfsetuid(3F) ................................................... 283
pxfsetuid(3F) ............................................................................................. pxfsetuid(3F) ................................................... 283
PXFSLEEP(3F) ............................................................................................... pxfsleep(3F) ..................................................... 285
pxfsleep(3F) ............................................................................................... pxfsleep(3F) ..................................................... 285
PXFSTAT(3F) ................................................................................................. pxfstat(3F)........................................................ 287
pxfstat(3F) ................................................................................................. pxfstat(3F)........................................................ 287
PXFSTRGET(3F) ............................................................................................. pxfstrget(3F) ................................................... 289
pxfstrget(3F) ............................................................................................. pxfstrget(3F) ................................................... 289
PXFSTRSET(3F) ............................................................................................. pxfstrset(3F) ................................................... 291
pxfstrset(3F) ............................................................................................. pxfstrset(3F) ................................................... 291
PXFSTRUCTCOPY(3F) ................................................................................... pxfstructcopy(3F) ......................................... 293
pxfstructcopy(3F) ................................................................................... pxfstructcopy(3F) ......................................... 293
PXFSTRUCTCREATE(3F) .............................................................................. pxfstructcreate(3F) ..................................... 295
pxfstructcreate(3F) .............................................................................. pxfstructcreate(3F) ..................................... 295
PXFSTRUCTFREE(3F) ................................................................................... pxfstructfree(3F) ......................................... 297
pxfstructfree(3F) ................................................................................... pxfstructfree(3F) ......................................... 297
PXFSYSCONF(3F) .......................................................................................... pxfsysconf(3F) ................................................ 299
pxfsysconf(3F) .......................................................................................... pxfsysconf(3F) ................................................ 299
PXFTIME(3F) ................................................................................................. pxftime(3F)........................................................ 301
pxftime(3F) ................................................................................................. pxftime(3F)........................................................ 301
PXFTIMES(3F) ............................................................................................... pxftimes(3F) ..................................................... 303
pxftimes(3F) ............................................................................................... pxftimes(3F) ..................................................... 303

004– 2165– 002 Index-11

PXFUCOMPARE(3F) ........................................................................................ pxfucompare(3F) .............................................. 305
pxfucompare(3F) ........................................................................................ pxfucompare(3F) .............................................. 305
PXFUMASK(3F) ............................................................................................... pxfumask(3F) ..................................................... 307
pxfumask(3F) ............................................................................................... pxfumask(3F) ..................................................... 307
PXFUNAME(3F) ............................................................................................... pxfuname(3F) ..................................................... 309
pxfuname(3F) ............................................................................................... pxfuname(3F) ..................................................... 309
PXFUNLINK(3F) ............................................................................................. pxfunlink(3F) ................................................... 311
pxfunlink(3F) ............................................................................................. pxfunlink(3F) ................................................... 311
PXFUTIME(3F) ............................................................................................... pxfutime(3F) ..................................................... 325
pxfutime(3F) ............................................................................................... pxfutime(3F) ..................................................... 325
PXFWAIT(3F) ................................................................................................. pxfwait(3F)........................................................ 313
pxfwait(3F) ................................................................................................. pxfwait(3F)........................................................ 313
PXFWAITPID(3F) .......................................................................................... pxfwait(3F)........................................................ 313
pxfwaitpid(3F) .......................................................................................... pxfwait(3F)........................................................ 313
PXFWIFEXITED(3F) ...................................................................................... pxfwifexited(3F) ............................................ 317
pxfwifexited(3F) ...................................................................................... pxfwifexited(3F) ............................................ 317
PXFWIFSIGNALED(3F) ................................................................................. pxfwifsignaled(3F) ....................................... 319
pxfwifsignaled(3F) ................................................................................. pxfwifsignaled(3F) ....................................... 319
PXFWIFSTOPPED(3F) ................................................................................... pxfwifstopped(3F) ......................................... 322
pxfwifstopped(3F) ................................................................................... pxfwifstopped(3F) ......................................... 322
Query assign options ....................................................................................... asnqfile(3F) ....................................................... 36
Queue read request .......................................................................................... aqread(3F) ............................................................ 25
Queue write request ........................................................................................ aqwrite(3F) ......................................................... 32
Queues a simple or compound asynchronous I/O read request ...................... aqread(3F) ............................................................ 25
Queues a simple or compound asynchronous I/O write request .................... aqwrite(3F) ......................................................... 32
Random access and asynchronous I/O ............................................................ asyncms(3F) ......................................................... 40
Random access buffering ................................................................................ findms(3F) ............................................................ 49
Random access close (with index) .................................................................. closms(3F) ............................................................ 46
Random access I/O ......................................................................................... aqopen(3F) ............................................................ 23
Random access I/O check ............................................................................... checkms(3F) ......................................................... 42
Random access I/O mode ............................................................................... syncms(3F) ............................................................ 88
Random access open ....................................................................................... openms(3F) ............................................................ 61
Random access read ........................................................................................ getwa(3F) .............................................................. 57
Random access synchronous ........................................................................... syncms(3F) ............................................................ 88
Read asynchronously ....................................................................................... aqread(3F) ............................................................ 25
Read characters ............................................................................................... readc(3F) .............................................................. 68
Read data ......................................................................................................... getwa(3F) .............................................................. 57
Read from file ................................................................................................. ffreada(3C) ....................................................... 152
Read IBM words ............................................................................................. readibm(3F) ......................................................... 70
Read random access ........................................................................................ readms(3F) ............................................................ 71
Read record ..................................................................................................... findms(3F) ............................................................ 49
Read words ...................................................................................................... read(3F)................................................................. 66
READ(3F) ........................................................................................................ read(3F)................................................................. 66
read(3F) ........................................................................................................ read(3F)................................................................. 66
READC(3F) ...................................................................................................... readc(3F) .............................................................. 68
readc(3F) ...................................................................................................... readc(3F) .............................................................. 68
READCP(3F) .................................................................................................... readc(3F) .............................................................. 68
readcp(3F) .................................................................................................... readc(3F) .............................................................. 68
READDR(3F) .................................................................................................... readms(3F) ............................................................ 71
readdr(3F) .................................................................................................... readms(3F) ............................................................ 71

Index-12 004– 2165– 002

READIBM(3F) ................................................................................................. readibm(3F) ......................................................... 70
readibm(3F) ................................................................................................. readibm(3F) ......................................................... 70
READMS(3F) .................................................................................................... readms(3F) ............................................................ 71
readms(3F) .................................................................................................... readms(3F) ............................................................ 71
READP(3F) ...................................................................................................... read(3F)................................................................. 66
readp(3F) ...................................................................................................... read(3F)................................................................. 66
Reads a record from a random-access file to memory ................................... readms(3F) ............................................................ 71
Reads characters, full or partial record mode ................................................. readc(3F) .............................................................. 68
Reads record into data buffers used by random-access routines .................... findms(3F) ............................................................ 49
Reads two IBM 32-bit floating-point words from each Cray Research
64-bit word ...................................................................................................... readibm(3F) ......................................................... 70
Reads words, full or partial record modes ...................................................... read(3F)................................................................. 66
Record read random access ............................................................................. readms(3F) ............................................................ 71
Record skip NAMELIST ................................................................................. rnlskip(3F) ......................................................... 76
Record-oriented data ....................................................................................... ffread(3C) ......................................................... 149
Reduce file memory ........................................................................................ stindx(3F) ............................................................ 86
regular files ...................................................................................................... pxfisreg(3F) ..................................................... 262
Removes a directory entry .............................................................................. pxfrmdir(3F) ..................................................... 273
Removes a directory entry .............................................................................. pxfunlink(3F) ................................................... 311
Renames a file ................................................................................................. pxfrename(3F) ................................................... 271
Replacement character NAMELIST ................................................................ wnl(3F) ................................................................... 94
Repositions a flexible file I/O file ................................................................... ffseek(3C) ......................................................... 156
Requests tape synchronization ........................................................................ tsync(3F) .............................................................. 90
Retrieves the file status ................................................................................... pxfstat(3F)........................................................ 287
Retrieves the operating system name .............................................................. pxfuname(3F) ..................................................... 309
Retrieves the value of configurable system variables ..................................... pxfsysconf(3F) ................................................ 299
Return .............................................................................................................. numblks(3F) ......................................................... 60
Returns a command-line argument ................................................................. pxfgetarg(3F) ................................................... 222
Returns a value for the environment name ..................................................... pxfgetenv(3F) ................................................... 226
Returns lower bit of signal that terminates a child process ........................... ipxfwtermsig(3F) ............................................ 177
Returns part of the lower bits of signal number that terminates child
process ............................................................................................................. ipxfwstopsig(3F) ............................................ 174
Returns pointer to standard file ....................................................................... gtstdptr(3F) ....................................................... 59
Returns the assign options currently in effect for a file name or unit
number ............................................................................................................ asnqfile(3F) ....................................................... 36
Returns the current size of a file in 4096-byte blocks ................................... numblks(3F) ......................................................... 60
Returns the file descriptor for a specified unit ............................................... pxffileno(3F) ................................................... 218
Returns the lower bits of exit argument ...................................................... ipxfwexitstatus(3F) ..................................... 171
Returns the number of command-line arguments excluding the command
name ................................................................................................................ ipxfargc(3F) ..................................................... 170
Returns the value associated with symbolic constants ................................... pxfconst(3F) ..................................................... 195
rnl(3F) ........................................................................................................... rnl(3F) ................................................................... 73
RNLCOMM(3F) ................................................................................................. rnl(3F) ................................................................... 73
rnlcomm(3F) ................................................................................................. rnl(3F) ................................................................... 73
RNLDELM(3F) ................................................................................................. rnl(3F) ................................................................... 73
rnldelm(3F) ................................................................................................. rnl(3F) ................................................................... 73
RNLECHO(3F) ................................................................................................. rnlecho(3F) ......................................................... 75
rnlecho(3F) ................................................................................................. rnlecho(3F) ......................................................... 75
RNLFLAG(3F) ................................................................................................. rnl(3F) ................................................................... 73
rnlflag(3F) ................................................................................................. rnl(3F) ................................................................... 73

004– 2165– 002 Index-13

RNLREP(3F) .................................................................................................... rnl(3F) ................................................................... 73
rnlrep(3F) .................................................................................................... rnl(3F) ................................................................... 73
RNLSEP(3F) .................................................................................................... rnl(3F) ................................................................... 73
rnlsep(3F) .................................................................................................... rnl(3F) ................................................................... 73
RNLSKIP(3F) ................................................................................................. rnlskip(3F) ......................................................... 76
rnlskip(3F) ................................................................................................. rnlskip(3F) ......................................................... 76
RNLTYPE(3F) ................................................................................................. rnltype(3F) ......................................................... 77
rnltype(3F) ................................................................................................. rnltype(3F) ......................................................... 77
routines(3F) ............................................................................................... intro_pxf(3F) ................................................... 165
schedule alarm ................................................................................................. pxfalarm(3F) ..................................................... 182
Schedule alarm signal ..................................................................................... pxfalarm(3F) ..................................................... 182
SEEK(3F) ........................................................................................................ getwa(3F) .............................................................. 57
seek(3F) ........................................................................................................ getwa(3F) .............................................................. 57
Selects NAMELIST output line length ............................................................ wnllong(3F) ......................................................... 97
Separator NAMELIST change ......................................................................... wnl(3F) ................................................................... 94
Set I/O mode ................................................................................................... asyncms(3F) ......................................................... 40
Set process group ID ....................................................................................... pxfsetpgid(3F) ................................................ 279
Sets access and modification times of a file ................................................... pxfutime(3F) ..................................................... 325
Sets environment variable pair ........................................................................ pxfsetenv(3F) ................................................... 275
Sets file modes for a named file ..................................................................... pxfchmod(3F) ..................................................... 186
Sets group ID .................................................................................................. pxfsetgid(3F) ................................................... 277
Sets I/O mode for random-access routines to asynchronous .......................... asyncms(3F) ......................................................... 40
Sets I/O mode for random-access routines to synchronous ............................ syncms(3F) ............................................................ 88
Sets the file creation mask .............................................................................. pxfumask(3F) ..................................................... 307
Sets user ID ..................................................................................................... pxfsetuid(3F) ................................................... 283
SETSP(3F) ...................................................................................................... setsp(3F) .............................................................. 78
setsp(3F) ...................................................................................................... setsp(3F) .............................................................. 78
SETTP(3F) ...................................................................................................... settp(3F) .............................................................. 79
settp(3F) ...................................................................................................... settp(3F) .............................................................. 79
Size of file ....................................................................................................... numblks(3F) ......................................................... 60
Skip bad data .................................................................................................. skipbad(3F) ......................................................... 81
Skip record NAMELIST .................................................................................. rnlskip(3F) ......................................................... 76
SKIPBAD(3F) ................................................................................................. skipbad(3F) ......................................................... 81
skipbad(3F) ................................................................................................. skipbad(3F) ......................................................... 81
SKIPF(3F) ...................................................................................................... skipf(3F) .............................................................. 83
skipf(3F) ...................................................................................................... skipf(3F) .............................................................. 83
Skips bad data ................................................................................................. skipbad(3F) ......................................................... 81
Skips files ........................................................................................................ skipf(3F) .............................................................. 83
special character files ...................................................................................... pxfischr(3F) ..................................................... 256
Special tape processing ................................................................................... startsp(3F) ......................................................... 85
Special tape processing (disable) .................................................................... endsp(3F) .............................................................. 48
Specifies output unit for NAMELIST error messages and echo lines ............ rnlecho(3F) ......................................................... 75
Standard file descriptor ................................................................................... gtstdptr(3F) ....................................................... 59
Standard libraries ............................................................................................ intro_applibs(3F) ............................................. 1
STARTSP(3F) ................................................................................................. startsp(3F) ......................................................... 85
startsp(3F) ................................................................................................. startsp(3F) ......................................................... 85
Status of AQIO requests ................................................................................. aqstat(3F) ............................................................ 29
Status of I/O .................................................................................................... checkms(3F) ......................................................... 42
STINDR(3F) .................................................................................................... stindx(3F) ............................................................ 86
stindr(3F) .................................................................................................... stindx(3F) ............................................................ 86

Index-14 004– 2165– 002

STINDX(3F) .................................................................................................... stindx(3F) ............................................................ 86
stindx(3F) .................................................................................................... stindx(3F) ............................................................ 86
Stream pointer ................................................................................................. gtstdptr(3F) ....................................................... 59
Stream-oriented data ....................................................................................... ffread(3C) ......................................................... 149
Structure .......................................................................................................... pxfstructcreate(3F) ..................................... 295
Structure components ...................................................................................... pxfintget(3F) ................................................... 250
Structure components ...................................................................................... pxfintset(3F) ................................................... 251
Structure instances .......................................................................................... pxfstructfree(3F) ......................................... 297
Structure instances .......................................................................................... pxfsysconf(3F) ................................................ 299
Subindex creation ............................................................................................ stindx(3F) ............................................................ 86
Suppress values in Fortran edit-directed output ............................................. fsup(3F)................................................................. 53
Suspend for AQIO requests ............................................................................ aqwait(3F) ............................................................ 31
SYNCDR(3F) .................................................................................................... syncms(3F) ............................................................ 88
syncdr(3F) .................................................................................................... syncms(3F) ............................................................ 88
Synchronize I/O mode .................................................................................... syncms(3F) ............................................................ 88
Synchronous read ............................................................................................ getwa(3F) .............................................................. 57
Synchronously and asynchronously reads data from the word-addressable,
random-access file ........................................................................................... getwa(3F) .............................................................. 57
SYNCMS(3F) .................................................................................................... syncms(3F) ............................................................ 88
syncms(3F) .................................................................................................... syncms(3F) ............................................................ 88
Takes appropriate action when an undesired NAMELIST group is
encountered ..................................................................................................... rnlskip(3F) ......................................................... 76
Tape block position at ..................................................................................... settp(3F) .............................................................. 79
Tape data accepting ........................................................................................ acptbad(3F) ......................................................... 19
Tape file position ............................................................................................ gettp(3F) .............................................................. 54
Tape position ................................................................................................... skipf(3F) .............................................................. 83
Tape position (checks) .................................................................................... checktp(3F) ......................................................... 44
Tape processing (disable) ................................................................................ endsp(3F) .............................................................. 48
Tape processing (disable) ................................................................................ startsp(3F) ......................................................... 85
Tape skip data ................................................................................................. skipbad(3F) ......................................................... 81
Tape synchronization ...................................................................................... tsync(3F) .............................................................. 90
terminal pathname ........................................................................................... pxfctermid(3F) ................................................ 202
Tests for block special file .............................................................................. pxfisblk(3F) ..................................................... 254
Tests for character special file ........................................................................ pxfischr(3F) ..................................................... 256
Tests for directory file ..................................................................................... pxfisdir(3F) ..................................................... 258
Tests for pipe or a FIFO special file .............................................................. pxfisfifo(3F) ................................................... 260
Tests for regular file ........................................................................................ pxfisreg(3F) ..................................................... 262
Timing routines ............................................................................................... intro_pxf(3F) ................................................... 165
TSYNC(3F) ...................................................................................................... tsync(3F) .............................................................. 90
tsync(3F) ...................................................................................................... tsync(3F) .............................................................. 90
Type conversion on input ............................................................................... rnltype(3F) ......................................................... 77
Type mismatch on input ................................................................................. rnltype(3F) ......................................................... 77
Unit NAMELIST errors ................................................................................... rnlecho(3F) ......................................................... 75
unitattr(3F) ............................................................................................... asnqfile(3F) ....................................................... 36
Variable NAMELIST on new line ................................................................... wnlline(3F) ......................................................... 96
Wait for AQIO request ................................................................................... aqrecall(3F) ....................................................... 27
Wait for I/O .................................................................................................... waitms(3F) ............................................................ 91
WAITDR(3F) .................................................................................................... waitms(3F) ............................................................ 91
waitdr(3F) .................................................................................................... waitms(3F) ............................................................ 91
WAITMS(3F) .................................................................................................... waitms(3F) ............................................................ 91

004– 2165– 002 Index-15

waitms(3F) .................................................................................................... waitms(3F) ............................................................ 91
Waits for completion of an asynchronous I/O operation ................................ waitms(3F) ............................................................ 91
Waits for completion of asynchronous queued I/O request ........................... aqrecall(3F) ....................................................... 27
Waits for completion of asynchronous queued I/O requests .......................... aqwait(3F) ............................................................ 31
WCLOSE(3F) .................................................................................................... wclose(3F) ............................................................ 93
wclose(3F) .................................................................................................... wclose(3F) ............................................................ 93
wnl(3F) ........................................................................................................... wnl(3F) ................................................................... 94
WNLDELM(3F) ................................................................................................. wnl(3F) ................................................................... 94
wnldelm(3F) ................................................................................................. wnl(3F) ................................................................... 94
WNLFLAG(3F) ................................................................................................. wnl(3F) ................................................................... 94
wnlflag(3F) ................................................................................................. wnl(3F) ................................................................... 94
WNLLINE(3F) ................................................................................................. wnlline(3F) ......................................................... 96
wnlline(3F) ................................................................................................. wnlline(3F) ......................................................... 96
WNLLONG(3F) ................................................................................................. wnllong(3F) ......................................................... 97
wnllong(3F) ................................................................................................. wnllong(3F) ......................................................... 97
WNLREP(3F) .................................................................................................... wnl(3F) ................................................................... 94
wnlrep(3F) .................................................................................................... wnl(3F) ................................................................... 94
WNLSEP(3F) .................................................................................................... wnl(3F) ................................................................... 94
wnlsep(3F) .................................................................................................... wnl(3F) ................................................................... 94
WOPEN(3F) ...................................................................................................... wopen(3F) .............................................................. 98
wopen(3F) ...................................................................................................... wopen(3F) .............................................................. 98
Word addressable open ................................................................................... wopen(3F) .............................................................. 98
Word-addressable data .................................................................................... getwa(3F) .............................................................. 57
Word-addressable file close ............................................................................ wclose(3F) ............................................................ 93
Word-addressable file read .............................................................................. getwa(3F) .............................................................. 57
Word-addressable write ................................................................................... putwa(3F) .............................................................. 64
Words read ...................................................................................................... read(3F)................................................................. 66
WRITDR(3F) .................................................................................................... writms(3F) .......................................................... 105
writdr(3F) .................................................................................................... writms(3F) .......................................................... 105
Write AQIO .................................................................................................... aqwrite(3F) ......................................................... 32
Write characters .............................................................................................. writec(3F) .......................................................... 102
Write IBM words ............................................................................................ writibm(3F)........................................................ 104
Write master index .......................................................................................... closms(3F) ............................................................ 46
Write to random-access ................................................................................... putwa(3F) .............................................................. 64
Write words ..................................................................................................... write(3F) ............................................................ 100
WRITE(3F) ...................................................................................................... write(3F) ............................................................ 100
write(3F) ...................................................................................................... write(3F) ............................................................ 100
WRITEC(3F) .................................................................................................... writec(3F) .......................................................... 102
writec(3F) .................................................................................................... writec(3F) .......................................................... 102
WRITECP(3F) ................................................................................................. writec(3F) .......................................................... 102
writecp(3F) ................................................................................................. writec(3F) .......................................................... 102
WRITEP(3F) .................................................................................................... write(3F) ............................................................ 100
writep(3F) .................................................................................................... write(3F) ............................................................ 100
Writes characters, full or partial record mode ................................................ writec(3F) .......................................................... 102
Writes data buffered by Fortran output statements to a file ........................... flush(3F) .............................................................. 51
Writes master index and closes random-access file ........................................ closms(3F) ............................................................ 46
Writes to a random-access file on disk ........................................................... writms(3F) .......................................................... 105
Writes to a word-addressable, random-access file .......................................... putwa(3F) .............................................................. 64
Writes two IBM 32-bit floating-point words from each Cray 64-bit word .... writibm(3F)........................................................ 104
Writes words, full or partial record mode ...................................................... write(3F) ............................................................ 100

Index-16 004– 2165– 002

WRITIBM(3F) ................................................................................................. writibm(3F)........................................................ 104
writibm(3F) ................................................................................................. writibm(3F)........................................................ 104
WRITMS(3F) .................................................................................................... writms(3F) .......................................................... 105
writms(3F) .................................................................................................... writms(3F) .......................................................... 105

004– 2165– 002 Index-17

Application Programmer’s Library
Reference Manual, Volume 2
004–2165–002
Copyright © 1994, 1995, 1997–1999 Silicon Graphics, Inc. All Rights Reserved. This manual or parts thereof may not be
reproduced in any form unless permitted by contract or by written permission of Silicon Graphics, Inc.

Portions of this manual are based on material reproduced or adapted from IEEE Std 1003.9–1992, copyright (c) 1992 by the
Institute of Electrical and Electronics Engineers, Inc. The IEEE takes no responsibility for and will assume no liability for damages
resulting from the reader’s misinterpretation of said information resulting from the placement and context in this publication.
Information is reproduced with the permission of the IEEE.

LIMITED AND RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in the Rights in Data clause at FAR
52.227-14 and/or in similar or successor clauses in the FAR, or in the DOD, DOE or NASA FAR Supplements. Unpublished rights
reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre
Pkwy., Mountain View, CA 94043-1351.

Autotasking, CF77, Cray, Cray Ada, CraySoft, Cray Y-MP, Cray-1, CRInform, CRI/TurboKiva, HSX, LibSci, MPP Apprentice, SSD,
SUPERCLUSTER, UNICOS, X-MP EA, and UNICOS/mk are federally registered trademarks and Because no workstation is an
island, CCI, CCMT, CF90, CFT, CFT2, CFT77, ConCurrent Maintenance Tools, COS, Cray Animation Theater, Cray APP, Cray C90,
Cray C90D, Cray C++ Compiling System, CrayDoc, Cray EL, Cray J90, Cray J90se, CrayLink, Cray NQS, Cray/REELlibrarian,
Cray S-MP, Cray SSD-T90, Cray SV1, Cray T90, Cray T3D, Cray T3E, CrayTutor, Cray X-MP, Cray XMS, Cray-2, CSIM, CVT,
Delivering the power . . ., DGauss, Docview, EMDS, GigaRing, HEXAR, IOS, ND Series Network Disk Array,
Network Queuing Environment, Network Queuing Tools, OLNET, RQS, SEGLDR, SMARTE, SUPERLINK,
System Maintenance and Remote Testing Environment, Trusted UNICOS, and UNICOS MAX are trademarks of Cray Research,
L.L.C., a wholly owned subsidiary of Silicon Graphics, Inc.

SGI is a trademark of Silicon Graphics, Inc. IRIX and Silicon Graphics are registered trademarks and the Silicon Graphics logo is a
trademark of Silicon Graphics, Inc.

CDC is a trademark of Control Data Systems, Inc. DEC, ULTRIX, VAX, and VMS are trademarks of Digital Equipment
Corporation. ER90 is a trademark of EMASS, Inc. ETA is a trademark of ETA Systems, Inc. IBM is a trademark of International
Business Machines Corporation. MIPS is a trademark of MIPS Computer Systems. UNIX is a registered trademark in the United
States and other countries, licensed exclusively through X/Open Company Limited. X/Open is a registered trademark of X/Open
Company Ltd. X Window System and the X device are trademarks of The Open Group.

The UNICOS operating system is derived from UNIX® System V. The UNICOS operating system is also based in part on the
Fourth Berkeley Software Distribution (BSD) under license from The Regents of the University of California.
 New Features

Application Programmer’s Library Reference Manual, Volume 2 004–2165–002

This manual describes the Application Library for CrayLibs 3.3. The changes to the manual are detailed
below.
New conversion routines are available for IRIX systems. See IEG2MIPS(3F) and VAX2MIPS(3F).
New FFIO layers are available for IRIX systems. See INTRO_FFIO(3F) for details. In addition, a new
routine was add which maps an error number to an error message string. See ffstrerror(3C) for details.
 Record of Revision

Version Description

1.2 October 1994

Original Printing. This manual supports the Programming Environment 1.2 release.
Many of the routines in this manual were originally printed in the UNICOS Fortran
Language Reference Manual, publication SR–2079.

2.0 November 1995

Reprint to support the Programming Environment 2.0 release.

3.0 June 1997

Reprint to support the Programming Environment 3.0 release. The Shared Memory
Library routines (SHMEM) are deferred until a later release on IRIX systems.

3.1 August 1998

Reprint to support the Programming Environment 3.1 release. The printed text of
this manual was made available in postscript (.ps) format only for this release.

3.3 July 1999

Reprint to support the Programming Environment 3.3 release. The printed text of
this manual was made available in postscript (.ps) format only for this release.

004–2165–002 i
 About This Guide

This publication documents Fortran-callable subprograms and routines

available to users of the CrayLibs product, which is included in the
Programming Environment (PE) 3.3 release.
The CrayLibs product contains several libraries; the library routines can be
called from source code written in a number of programming languages,
including Fortran, C, Pascal, and assembly language. The information in this
document supplements information contained in other manuals of the
Programming Environment documentation set.
This is a reference manual for application and system programmers. Readers
should also have a working knowledge of either the UNICOS, UNICOS/mk, or
UNIX operating system and a working knowledge of the Fortran or C
programming language.
Portions of this manual are based on materials reproduced or adapted from
IEEE Std 1003.9–1992, copyright (c) 1992 by the Institute of Electrical and
Electronics Engineers, Inc. The IEEE takes no responsibility for and will assume
no liability for damages resulting from the placement and context in this
publication. Information is reproduced with the permission of the IEEE.

Documentation Organization
The printed versions of the application library man pages appear in 2 volumes
and are grouped according to topics. See the INTRO_APPLIBS(3F) man page
for details about the contents of each volume.
Each topic section also has an introductory man page which explains the
contents of the section and provides other information about the usage of those
routines. The following introductory man pages are available:
INTRO_CONVERSION(3F) INTRO_PROGAIDS(3F)
INTRO_FFIO(3F) INTRO_PXF(3F)

INTRO_HEAP(3F) INTRO_SORTSEARCH(3F)

INTRO_INTERFACE(3F) INTRO_STREAMS(3)

INTRO_IO(3F) INTRO_SYNC(3F)

004–2165–002 iii
Application Programmer’s Library Reference Manual, Volume 2

Related Publications
The following documents contain additional information that may be helpful:
• Segment Loader (SEGLDR) and ld Reference Manual
• UNICOS User Commands Reference Manual
• Guide to Parallel Vector Applications
• Tape Subsystem User’s Guide
• UNICOS System Libraries Reference Manual
• UNICOS System Calls Reference Manual
• Application Programmer’s I/O Guide
• Optimizing Application Code on UNICOS Systems
The following manuals document the CrayLibs product. All man pages in these
manuals can also be viewed online by using the man command:
• Scientific Library Reference Manual
• Intrinsic Procedures Reference Manual
• Scientific Libraries Ready Reference
• Application Programmer’s Library Ready Reference
In addition to these documents, several documents are available that describe
the compiler systems available on UNICOS and UNICOS/mk. Some of these
manuals are:
• CF90 Ready Reference
• CF90 Commands and Directives Reference Manual
• Fortran Language Reference Manual, Volume 1
• Fortran Language Reference Manual, Volume 2
• Fortran Language Reference Manual, Volume 3
• Cray C/C++ Reference Manual

iv 004–2165–002
 About This Guide

The following manuals document the compilers that are available on IRIX
systems:
• MIPSPro 7 Fortran 90 Commands and Directives Reference Manual
• MIPSpro Assembly Language Programmer’s Guide
• MIPSpro Fortran 77 Language Reference Manual
• MIPSpro Fortran 77 Programmer’s Guide
• MIPSpro 64-Bit Porting and Transition Guide

Obtaining Publications
SGI maintains information about available publications at the following URL:
http://techpubs.sgi.com/library

This Web site contains information that allows you to browse documents online,
order documents, and send feedback to SGI. You can also order a printed SGI
document by calling 1 800 627 9307.
The User Publications Catalog describes the availability and content of all Cray
hardware and software documents that are available to customers. Customers
who subscribe to the Cray Inform (CRInform) program can access this
information on the CRInform system.
SGI maintains information on publicly available Cray documents at the
following URL:
http://www.cray.com/swpubs/

This Web site contains information that allows you to browse documents online
and send feedback to SGI. To order a printed Cray document, either call
+1 651 683 5907 or send a facsimile of your request to fax number
+1 651 683 3840. SGI employees may also order printed Cray documents by
sending their orders via electronic mail to orderdsk.
Customers outside of the United States and Canada should contact their local
service organization for ordering information and documentation information.

Conventions
The following conventions are used throughout this document:

004–2165–002 v
Application Programmer’s Library Reference Manual, Volume 2

Convention Meaning
command This fixed-space font denotes literal items such as
commands, files, routines, path names, signals,
messages, and programming language structures.
variable Italic typeface denotes variable entries and words
or concepts being defined.
user input This bold, fixed-space font denotes literal items
that the user enters in interactive sessions.
Output is shown in nonbold, fixed-space font.
In addition to these formatting conventions, several naming conventions are
used throughout the documentation. “Cray PVP systems” denotes all
configurations of Cray parallel vector processing (PVP) systems that run the
UNICOS operating system. “Cray MPP systems” denotes all configurations of
the Cray T3E series that run the UNICOS/mk operating system. “IRIX
systems” denotes SGI platforms which run the IRIX operating system.
The default shell in the UNICOS and UNICOS/mk operating systems, referred
to as the standard shell, is a version of the Korn shell that conforms to the
following standards:
• Institute of Electrical and Electronics Engineers (IEEE) Portable Operating
System Interface (POSIX) Standard 1003.2–1992
• X/Open Portability Guide, Issue 4 (XPG4)
The UNICOS and UNICOS/mk operating systems also support the optional use
of the C shell.

Man page sections

The entries in this document are based on a common format. The following list
shows the order of sections in an entry and describes each section. Most entries
contain only a subset of these sections.

Section heading Description

NAME Specifies the name of the entry and briefly states
its function.
SYNOPSIS Presents the syntax of the entry.
IMPLEMENTATION Identifies the systems to which the entry applies.

vi 004–2165–002
 About This Guide

STANDARDS Provides information about the portability of a

utility or routine.
DESCRIPTION Discusses the entry in detail.
NOTES Presents items of particular importance.
CAUTIONS Describes actions that can destroy data or
produce undesired results.
WARNINGS Describes actions that can harm people,
equipment, or system software.
ENVIRONMENT Describes predefined shell variables that
VARIABLES determine some characteristics of the shell or that
affect the behavior of some programs, commands,
or utilities.
RETURN VALUES Describes possible return values that indicate a
library or system call executed successfully, or
identifies the error condition under which it
failed.
EXIT STATUS Describes possible exit status values that indicate
whether the command or utility executed
successfully.
MESSAGES Describes informational, diagnostic, and error
messages that may appear. Self-explanatory
messages are not listed.
ERRORS Documents error codes. Applies only to system
calls.
FORTRAN Describes how to call a system call from Fortran.
EXTENSIONS Applies only to system calls.
BUGS Indicates known bugs and deficiencies.
EXAMPLES Shows examples of usage.
FILES Lists files that are either part of the entry or are
related to it.

004–2165–002 vii
Application Programmer’s Library Reference Manual, Volume 2

SEE ALSO Lists entries and publications that contain related

information.

Reader Comments
If you have comments about the technical accuracy, content, or organization of
this document, please tell us. Be sure to include the title and part number of
the document with your comments.
You can contact us in any of the following ways:
• Send e-mail to the following address:
[email protected]

• Send a fax to the attention of “Technical Publications” at: +1 650 932 0801.
• Use the Feedback option on the Technical Publications Library World Wide
Web page:
http://techpubs.sgi.com

• Call the Technical Publications Group, through the Technical Assistance

Center, using one of the following numbers:
For SGI IRIX based operating systems: 1 800 800 4SGI
For UNICOS or UNICOS/mk based operating systems or Cray Origin 2000
systems: 1 800 950 2729 (toll free from the United States and Canada) or
+1 651 683 5600
• Send mail to the following address:
Technical Publications
SGI
1600 Amphitheatre Pkwy.
Mountain View, California 94043–1351
We value your comments and will respond to them promptly.

viii 004–2165–002
CONTENTS

Conversion routines

intro_conversion, INTRO_CONVERSION ....... Introduction to conversion routines ........................................................... 327

b2oct, B2OCT ........................................................... Places an octal Hollerith representation of a Cray Research numeric
value into a specified part of an integer array .......................................... 333
cdc2cray, CDC2CRAY, CRAY2CDC ........................ Converts CDC data to Cray Research format and vice versa ................... 335
chconv, CHCONV ...................................................... Converts decimal ASCII numerals to an integer value ............................. 338
cri2cray, CRI2CRAY, CRAY2CRI ........................ Converts IEEE/MPP 64-bit data to Cray Research PVP 64-bit data
and vice versa ............................................................................................ 340
cri2ibm, CRI2IBM, IBM2CRI ............................... Converts Cray Research IEEE Fortran data types to IBM
(360/370-style) Fortran data types ............................................................. 343
cri2ieg, CRI2IEG, IEG2CRI ............................... Converts Fortran data types between Cray IEEE and generic IEEE
data types ................................................................................................... 346
cry2cri, CRY2CRI, CRI2CRY ............................... Converts Fortran data types between Cray floating-point and IEEE
floating-point systems ................................................................................ 349
cry2mips, CRY2MIPS, MIPS2CRY ........................ Converts Fortran data types between Cray Fortran data types and
MIPS IEEE Fortran data types .................................................................. 352
dsasc, DSASC, ASCDC ............................................. Converts CDC display code character to ASCII character and vice
versa ........................................................................................................... 355
eta2cray, ETA2CRAY, CRAY2ETA ........................ Converts ETA/CYBER 205 data to Cray Research format and vice
versa ........................................................................................................... 356
fp6064, FP6064, FP6460 ...................................... Converts between CDC 60-bit and Cray Research 64-bit numbers ......... 359
ibm2cray, IBM2CRAY, CRAY2IBM ........................ Converts IBM data to Cray Research format and vice versa ................... 360
ieg2cray, IEG2CRAY, CRAY2IEG ........................ Converts IEEE/Generic 32-bit data to Cray Research 64-bit data and
vice versa ................................................................................................... 363
ieg2cri_77, IEG2CRI_77, CRI2IEG_77 .......... Converts IEEE 32-bit data to Cray Research IEEE 64-bit data and
vice versa ................................................................................................... 366
ieg2mips, IEG2MIPS, MIPS2IEG ........................ Converts generic IEEE data to MIPS IEEE data and vice versa .............. 369
ieu2cray, IEU2CRAY, CRAY2IEU ........................ Converts DEC ULTRIX/generic little-endian 32-bit data to Cray
Research 64-bit data and vice versa .......................................................... 372
int6064, INT6064 .................................................. Converts CDC 60-bit integers to Cray Research 64-bit integers .............. 375
int6460, INT6460 .................................................. Converts Cray Research 64-bit integers to CDC 60-bit integers .............. 376
nve2cray, NVE2CRAY, CRAY2NVE ........................ Converts NOS/VE data to Cray Research format and vice versa ............ 377
rbn, RBN, RNB ........................................................... Converts trailing blanks to nulls and vice versa ....................................... 380
uscctc, USCCTC, USCCTI ...................................... Converts EBCDIC character data to ASCII character data, and vice
versa ........................................................................................................... 381
usdctc, USDCTC ...................................................... Converts IBM 64-bit floating-point numbers to Cray Research 64-bit,
single-precision numbers ........................................................................... 383
usdcti, USDCTI ...................................................... Converts Cray 64-bit single-precision, floating-point numbers to IBM
64-bit double-precision numbers ............................................................... 384
usictc, USICTC, USICTI ...................................... Converts between IBM INTEGER*2/INTEGER*4 and Cray Research
64-bit integer numbers ............................................................................... 385
usictp, USICTP ...................................................... Converts a Cray Research 64-bit integer to an IBM packed-decimal
field ............................................................................................................ 387
uslctc, USLCTC, USLCTI ...................................... Converts between IBM LOGICAL*1/LOGICAL*4 and Cray
Research 64-bit logical values ................................................................... 388
uspctc, USPCTC ...................................................... Converts specified number of bytes of IBM packed-decimal field to
64-bit integer field ..................................................................................... 389

004– 2165– 002 ix

ussctc, USSCTC ...................................................... Converts IBM 32-bit floating-point numbers to Cray Research 64-bit
single-precision numbers ........................................................................... 390
usscti, USSCTI ...................................................... Converts Cray Research 64-bit single-precision, floating-point
numbers to IBM 32-bit single-precision numbers ..................................... 391
vax2cray, VAX2CRAY, CRAY2VAX ........................ Converts VAX data to Cray Research format and vice versa .................. 393
vax2mips, VAX2MIPS, MIPS2VAX ........................ Converts generic IEEE data to MIPS IEEE data and vice versa .............. 396
vxdctc, VXDCTC ...................................................... Converts VAX 64-bit, D-format numbers to Cray Research 64-bit
single-precision numbers ........................................................................... 399
vxdcti, VXDCTI ...................................................... Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX D-format, 64-bit, double-precision, floating-point
numbers ..................................................................................................... 400
vxgctc, VXGCTC ...................................................... Converts VAX 64-bit G-format numbers to Cray Research 64-bit
single-precision numbers ........................................................................... 402
vxgcti, VXGCTI ...................................................... Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX G-format, 64-bit, single-precision, floating-point
numbers ..................................................................................................... 403
vxictc, VXICTC ...................................................... Converts VAX INTEGER*2 (16 bits) or INTEGER*4 (32 bits) to
Cray Research 64-bit integers ................................................................... 405
vxicti, VXICTI ...................................................... Converts Cray 64-bit integers to VAX INTEGER*2 (16 bit) or
INTEGER*4 (32 bit) numbers .................................................................. 406
vxlctc, VXLCTC ...................................................... Converts VAX 32-bit logical numbers to Cray Research 64-bit
logical numbers ......................................................................................... 408
vxlcti, VXLCTI ...................................................... Converts Cray Research 64-bit logical numbers to VAX 32-bit
logical numbers ......................................................................................... 409
vxsctc, VXSCTC ...................................................... Converts VAX 32-bit floating-point numbers to Cray Research 64-bit
single-precision real numbers .................................................................... 410
vxscti, VXSCTI ...................................................... Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX F format, 32-bit, single-precision, floating-point
numbers ..................................................................................................... 411
vxzctc, VXZCTC ...................................................... Converts VAX 64-bit complex numbers to Cray Research 128-bit
complex numbers ....................................................................................... 413
vxzcti, VXZCTI ...................................................... Converts Cray Research 128-bit complex numbers to VAX 64-bit
complex numbers ....................................................................................... 414

Interface routines
intro_interface, INTRO_INTERFACE ............ Introduction to system interface routines .................................................. 417
abort, ABORT ...........................................................
Requests abort with traceback ................................................................... 419
clearbt, CLEARBT, SETBT .................................... Temporarily disables or enables bidirectional memory transfers .............. 420
clearfi, CLEARFI, SENSEFI, SETFI ................. Modifies floating-point interrupt status ..................................................... 421
errexit, ERREXIT .................................................. Requests abort ........................................................................................... 422
exit, EXIT ................................................................
Exits from a Fortran program ................................................................... 423
getcwd, GETCWD ...................................................... Returns the current working directory ...................................................... 424
gethost, GETHOST .................................................. Returns name of host mainframe .............................................................. 425
getoarg, GETOARG .................................................. Gets command-line arguments .................................................................. 426
getoargc, GETOARGC ............................................. Gets command-line arguments .................................................................. 427
getvarg, GETVARG .................................................. Gets command-line arguments, allowing blanks or commas as
delimiters ................................................................................................... 428
getvargc, GETVARGC ............................................. Gets command-line arguments, allowing blanks or commas as
delimiters ................................................................................................... 429
iargc, IARGC, GETARG ........................................... Returns number of command-line arguments or the argument itself ....... 430
ishell, ISHELL ...................................................... Executes a UNICOS shell command ........................................................ 431

x 004– 2165– 002

nlimit, NLIMIT ...................................................... Provides an interface to setting or obtaining resource limit values .......... 432
remark, REMARK, REMARK2 .................................... Enters a message in the stderr file ....................................................... 437
remarkf, REMARKF .................................................. Enters a formatted message in the stderr file ....................................... 438
samefile, SAMEFILE ............................................. Checks to see whether two files have the same inode number ................ 440
sensebt, SENSEBT .................................................. Determines if bidirectional memory transfer is enabled or disabled ........ 441
uname, UNAME ........................................................... Returns name of current operating system (Fortran interface to
uname(2)) ................................................................................................. 442

Heap routines
intro_heap, INTRO_HEAP ................................... Introduction to heap, table, and data segment management ..................... 445
craydump, CRAYDUMP ............................................. Dump arrays of memory ........................................................................... 449
hpalloc, HPALLOC .................................................. Allocates a block of memory from the heap ............................................ 450
hpcheck, HPCHECK .................................................. Checks the integrity of the heap ............................................................... 451
hpclmove, HPCLMOVE ............................................. Extends a block or copies the contents of the block into a larger
block .......................................................................................................... 452
hpdeallc, HPDEALLC ............................................. Returns a block of memory to the list of available space (the heap) ....... 453
hpdump, HPDUMP ...................................................... Dumps the address and size of each heap block ...................................... 454
hpnewlen, HPNEWLEN ............................................. Changes the size of an allocated heap block ............................................ 455
hpshrink, HPSHRINK ............................................. Returns memory from the heap to the operating system .......................... 456
ihplen, IHPLEN ...................................................... Returns the length of a heap block ........................................................... 457
ihpvalid, IHPVALID ............................................. Returns validity of block address .............................................................. 458
tmadw, TMADW ........................................................... Adds a word to a table .............................................................................. 459
tmamu, TMAMU ........................................................... Reports table management operation statistics .......................................... 460
tmats, TMATS ........................................................... Allocates table space ................................................................................. 461
tminit, TMINIT ...................................................... Initializes table descriptor vector and zeroes table length vector ............. 462
tmmsc, TMMSC ........................................................... Searches the table by using a mask to locate a specific field within an
entry using an optional offset .................................................................... 463
tmmve, TMMVE ........................................................... Moves memory (words) ............................................................................ 464
tmptc, TMPTC ........................................................... Processes table collisions .......................................................................... 465
tmpts, TMPTS ........................................................... Presets table space ..................................................................................... 466
tmsrc, TMSRC ........................................................... Searches the table by using optional mask to locate specific field
within entry and offset .............................................................................. 467
tmvsc, TMVSC ........................................................... Searches a vector table for the search argument ....................................... 468

Programming Aid routines

intro_progaids, INTRO_PROGAIDS ................. Introduction to programming aids ............................................................. 469
auxstat, AUXSTAT .................................................. Gives the number of reads and writes to SDS that have occurred
while accessing auxiliary array variables .................................................. 473
bitvec, BITVEC ...................................................... Generates a bit mask corresponding to integer or real arrays
according to a specified condition ............................................................. 474
bitvecm, BITVECM .................................................. Generates a bit mask corresponding to masked integer arrays
according to a specified condition ............................................................. 477
byt, PUTBYT, IGTBYT ............................................. Replaces a byte in a variable or an array ................................................. 479
dtts, DTTS ................................................................ Converts ASCII date and time to time stamp ........................................... 480
fsigctl, FSIGCTL .................................................. Specifies action on receipt of signal ......................................................... 481
getcallerinfo, GETCALLERINFO ..................... Returns the name and line number of the calling routine ........................ 483
getpmc, GETPMC, GETTMC, GETHMC ..................... Returns 128-word output array describing machine characteristics .......... 485
iceil, ICEIL ........................................................... Returns integer ceiling of a rational number ............................................ 487
icpused, ICPUSED .................................................. Gets task CPU time in real-time clock (RTC) ticks ................................. 488
mov, STRMOV, MOVBIT, MOVBITZ .......................... Moves bytes or bits from one variable or array to another ...................... 489

004– 2165– 002 xi

mtts, MTTS ................................................................ Converts machine time (real-time clock value) to time stamp ................. 492
mvc, MVC .................................................................... Moves characters from one memory area to another ................................ 493
pack, PACK ................................................................ Compresses stored data ............................................................................. 494
p32, P32, U32 ........................................................... Packs or unpacks 32-bit words into or from Cray 64-bit words .............. 496
p6460, P6460, U6064 ............................................. Packs or unpacks 60-bit words into or from Cray 64-bit words .............. 497
reprieve, REPRIEVE ............................................. Describes error handling under the UNICOS and UNICOS/mk
operating system ........................................................................................ 498
second, SECOND ...................................................... Returns elapsed CPU time ........................................................................ 500
secondr, SECONDR .................................................. Returns elapsed wall-clock time in seconds .............................................. 502
setplimq, SETPLIMQ ............................................. Initiates a detailed tracing of each call and return .................................... 503
shutdsav, SHUTDSAV ............................................. Sets up the calling program to be checkpointed on system shutdown ..... 504
sigoff, SIGOFF, SIGON ........................................ Controls receipt of signals ......................................................................... 506
stop_all, STOP_ALL ............................................. Stops all PEs in an application .................................................................. 507
symdebug, SYMDEBUG ............................................. Produces a symbolic snapshot of a running process ................................. 508
symdump, SYMDUMP .................................................. Produces a symbolic snapshot dump of a running program ..................... 511
sysclock, SYSCLOCK ............................................. Returns real-time clock value and number of wraps ................................ 516
timef, TIMEF ........................................................... Returns elapsed wall-clock time in milliseconds since the previous
call to TIMEF ............................................................................................ 517
tracebk, TRACEBK .................................................. Prints a traceback ...................................................................................... 518
trbk, TRBK ................................................................ Lists all subroutines active in the current calling sequence ...................... 520
trbklvl, TRBKLVL .................................................. Returns information on current level of calling sequence ........................ 521
tremain, TREMAIN .................................................. Returns the CPU time (in seconds of type real) remaining for the
program ...................................................................................................... 523
trimlen, TRIMLEN .................................................. Returns the length of a character argument without counting trailing
blanks ......................................................................................................... 524
tsecnd, TSECND ...................................................... Returns elapsed CPU time for a calling task or process .......................... 526
tsdt, TSDT ................................................................ Converts time stamps to ASCII date and time strings .............................. 528
tsmt, TSMT ................................................................ Converts time stamp to machine time (real-time clock value) ................. 529
unitts, UNITTS ...................................................... Returns time-stamp units in specified standard-time units ........................ 530
unpack, UNPACK ...................................................... Expands stored data ................................................................................... 531
xpfmt, XPFMT ........................................................... Produces a printable image of an exchange package ................................ 532

Synch routines
intro_sync, INTRO_SYNC ................................... Introduction to synchronization routines ................................................... 535
clear_event ........................................................... Clears an event and returns control to the calling PE .............................. 536
set_barrier ........................................................... Registers the arrival of a PE at a barrier .................................................. 539
set_event ................................................................ Posts an event and returns control to the calling PE ................................ 540
test_barrier ......................................................... Tests a barrier to determine its state (set or cleared) ................................ 542
test_event ............................................................. Returns the state of an event, either posted or cleared ............................. 543
wait_barrier ......................................................... Suspends PE execution until all PEs arrive at the barrier ........................ 544
wait_event ............................................................. Delays the calling PE until the eureka event is posted ............................. 545

Search/sort routines
intro_sortsearch, INTRO_SORTSEARCH ....... Introduction to sorting and searching routines .......................................... 547
cluseq, CLUSEQ, CLUSNE ...................................... Searches a vector for clusters of values equal or not equal to a target .... 551
clusflt, CLUSFLT, CLUSFLE, CLUSFGT,
CLUSFGE .................................................................... Searches a real vector for clusters of values with a specified logical
relationship to a real target ........................................................................ 553

xii 004– 2165– 002

clusilt, CLUSILT, CLUSILE, CLUSIGT,
CLUSIGE .................................................................... Searches an integer vector for clusters of values with a specified
logical relationship to an integer target ..................................................... 555
iilz, IILZ, ILLZ, ILSUM ...................................... Returns number of leading occurrences of an object in a vector ............. 557
inflmax, INFLMAX, INFLMIN ............................... Searches for the maximum or minimum value in subfields of a vector
element ...................................................................................................... 559
intmax, INTMAX, INTMIN ...................................... Searches an integer vector for the maximum or minimum value ............. 561
isamax, ISAMAX, ICAMAX, ISAMIN ..................... Searches a vector for the first occurrence of the maximum or
minimum absolute value ............................................................................ 562
ismax, ISMAX, ISMIN ............................................. Searches a real vector for the first occurrence of the maximum or
minimum value .......................................................................................... 564
isortd, ISORTD ...................................................... Performs a distribution counting sort on the elements of an integer
vector ......................................................................................................... 566
isrcheq, ISRCHEQ, ISRCHNE ............................... Searches a vector for the first element equal or not equal to a target ...... 571
isrchflt, ISRCHFLT, ISRCHFLE, ISRCHFGT,
ISRCHFGE .................................................................. Searches a real vector for the first element with a specified logical
relationship to a real target ........................................................................ 573
isrchilt, ISRCHILT, ISRCHILE, ISRCHIGT,
ISRCHIGE .................................................................. Searches an integer vector for the first element with a specified
logical relationship to an integer target ..................................................... 575
isrchmeq, ISRCHMEQ, ISRCHMNE ........................ Searches a vector for the first element whose subfield is equal or not
equal to a target ......................................................................................... 577
isrchmlt, ISRCHMLT, ISRCHMLE, ISRCHMGT,
ISRCHMGE .................................................................. Searches a vector for the first element whose subfield has a specified
logical relationship with a target ............................................................... 579
orders, ORDERS ...................................................... Internal, fixed-length record-sorting routine optimized for Cray
Research systems ....................................................................................... 581
osrchi, OSRCHI, OSRCHF ...................................... Searches an ordered vector for the first location that contains a target .... 592
osrchm, OSRCHM ...................................................... Searches an ordered integer vector for the first element whose
subfield is equal to an integer target ......................................................... 594
ssortb, SSORTB, ISORTB ...................................... Performs Batcher’s Odd-Even Merge sort on the elements of a real or
integer general vector ................................................................................ 598
wheneq, WHENEQ, WHENNE ...................................... Searches a vector for all elements equal or not equal to a target ............ 605
whenflt, WHENFLT, WHENFLE, WHENFGT,
WHENFGE .................................................................... Searches a real vector for all elements with a specified logical
relationship to a real target ........................................................................ 607
whenilt, WHENILT, WHENILE, WHENIGT,
WHENIGE .................................................................... Searches an integer vector for all elements that have a specified
relationship to an integer target ................................................................. 609
whenmeq, WHENMEQ, WHENMNE ............................... Searches a vector for all elements whose subfields are equal or not
equal to a target ......................................................................................... 611
whenmlt, WHENMLT, WHENMLE, WHENMGT,
WHENMGE .................................................................... Searches a vector for all elements whose subfields have a specified
logical relationship with a target ............................................................... 613

Appendix A
cinter ....................................................................... Introduction to interfaces to C library routines ......................................... 615

004– 2165– 002 xiii

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

NAME
INTRO_CONVERSION – Introduction to conversion routines

IMPLEMENTATION
See individual man pages for implementation details.

DESCRIPTION
These Fortran-callable subroutines perform conversion of data residing in systems memory. Conversion
subprograms are listed under the following types of routines:
• Foreign data conversion
• Numeric conversion
• ASCII conversion
• IEEE conversion
• Other conversion
For more information regarding foreign data conversion, see the Application Programmer’s I/O Guide.
The USCCTC and USCCTI routines are available on IRIX systems. Both routines are documented on the
USCCTC man page. In addition, the CRY2MIPS and MIPS2CRY routines are available on IRIX systems.
Both routines are documented on the CRY2MIPS man page.

FOREIGN DATA CONVERSION ROUTINES

The foreign data conversion routines translate data in both directions between Cray internal representations
and that of other vendors, including IBM, CDC, ETA, IEEE, and DEC (VAX systems). The following
tables list these conversion routines by the data type on which they operate; use the newer routines:
IBM2CRAY, CDC2CRAY, VAX2CRAY, NVE2CRAY, IEG2CRAY, ETA2CRAY, CRAY2IBM, CRAY2CDC,
CRAY2VAX, CRAY2NVE, CRAY2IEG, and CRAY2ETA. Generally, routines that are inverses of each other
(that is, converted from Cray data types to IBM and IBM to Cray ) are listed under a single entry. Routine
descriptions follow later in this section, listed alphabetically by entry name.

004– 2165– 002 327

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

These routines are used for data conversion:

Conversion routines on Cray PVP systems

Name Foreign->Native Native->Foreign

IBM IBM2CRAY CRAY2IBM

VAX/VMS VAX2CRAY CRAY2VAX
CDC (NOS) CDC2CRAY CRAY2CDC
CDC (NOS/VE) NVE2CRAY CRAY2NVE
CDC CYBER 205 ETA2CRAY CRAY2ETA
Generic IEEE (32-bit) IEG2CRAY CRAY2IEG
IEEE little-endian IEU2CRAY CRAY2IEU
Cray IEEE (64-bit) CRI2CRAY CRAY2CRI
SGI MIPS MIPS2CRY CRY2MIPS
User conversion USR2CRAY CRAY2USR
Site conversion STE2CRAY CRAY2STE

Conversion routines for Cray MPP systems:

Name Foreign->Native Native->Foreign

Cray PVP systems (non-IEEE) CRAY2CRI and CRY2CRI CRI2CRAY and CRI2CRY
IBM IBM2CRI CRI2IBM
Generic IEEE (32-bit) IEG2CRI CRI2IEG
User conversion USR2CRAY CRAY2USR
Site conversion STE2CRAY CRAY2STE

Conversion routines on Cray T90 (non-IEEE)

Name Foreign->Native Native->Foreign

Cray PVP systems (non-IEEE) CRY2CRI CRI2CRY

IBM IBM2CRI CRI2IBM
Generic IEEE (32-bit) IEG2CRI CRI2IEG
User conversion USR2CRAY CRAY2USR
Site conversion STE2CRAY CRAY2STE

328 004– 2165– 002

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

Conversion routines on IRIX systems (MIPS)

Name Foreign->Native Native->Foreign

Cray PVP systems (non-IEEE) CRY2MIPS MIPS2CRY

User conversion USR2CRAY CRAY2USR
Site conversion STE2CRAY CRAY2STE
IEEE Fortran converson IEG2MIPS MIPS2IEG
VAX Fortran conversion VAX2MIPS MIPS2VAX

Superseded routines: Foreign to Cray

The following table lists superseded, older routines that are supported to maintain continuity. Use the newer
routines named in the preceding list.

Conversion IBM CDC VAX/VMS

Foreign single precision to Cray single precision USSCTC FP6064 VXSCTC

Foreign double precision to Cray single precision USDCTC --- VXDCTC
VXGCTC
Foreign double precision to Cray double --- --- VXBCTC
precision
Foreign integer to Cray integer USICTC INT6064 VXICTC
Foreign logical to Cray logical USLCTC --- VXLCTC
Foreign character to ASCII USCCTC DSASC ---
VAX 64-bit complex to Cray single precision --- --- VXZCTC
IBM packed-decimal field to Cray integer USPCTC --- ---

Superseded routines: Cray to Foreign

The following routines convert Cray types to foreign types. The man pages for these routines appear under
the name of the inverse of each routine (for example, CRAY2IBM is described under entry IBM2CRAY).
Routine Type
CRAY2IBM IBM
CRAY2CDC CDC
CRAY2VAX VAX/VMS
CRAY2NVE NOS/VE
CRAY2ETA ETA/CYBER 205
CRAY2IEG IEEE (32-bit)
CRAY2IEU DEC
CRAY2CRI IEEE (UNICOS/mk)

004– 2165– 002 329

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

The following table lists older routines that convert Cray types to foreign types. These routines are
supported to maintain continuity; use the newer routines named in the preceding list rather than these
routines.

Conversion IBM CDC VAX/VMS

Cray single precision to foreign single precision USSCTI FP6460 VXSCTI

Cray single precision to foreign double precision USDCTI --- VXDCTI,
VXGCTI
Cray double precision to foreign double precision --- --- VXBCTI
Cray integer to foreign integer USICTI INT6460 VXICTI
Cray logical to foreign logical USLCTI --- VXLCTI
ASCII character to foreign character USCCTI ASCDC ---
Cray complex to foreign complex --- --- VXZCTI
Cray integer to foreign packed-decimal field USICTP --- ---

NUMERIC CONVERSION ROUTINE

CHCONV converts decimal ASCII numerals to an integer format. It is an internal library routine.
ASCII CONVERSION FUNCTIONS
The ASCII conversion functions convert binary integers to or from 1-word ASCII strings (not Fortran
character variables).
Note: The ASCII conversion functions are not intrinsic to Fortran. Their default type is real, even though
their results are generally used as integers.
The ASCII conversion routines use one type integer argument. The DTB and OTB routines can also use a
second optional argument as an error code. The resulting error codes (0 if no error; – 1 if there are errors)
are returned in the second argument for Fortran calls. If no error code argument is included in Fortran calls,
the routine aborts if an error is encountered.
The following calls show how the ASCII conversion routines are used. These Fortran calls convert a binary
number to decimal ASCII, then convert back from ASCII to binary. They use internal I/O routines.
result=BTD(integer)
result Decimal ASCII result (right-justified, blank-filled)
integer Integer argument

result=DTB(arg,errcode)
result Integer value
arg Decimal ASCII (left-justified, zero-filled)
errcode 0 if conversion successful; – 1 if error

330 004– 2165– 002

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

The following table lists the ASCII conversion functions.

Purpose Name Argument range Result

Binary to decimal ASCII BTD 0 ≤ x ≤ 99999999 One-word ASCII string

(right-justified, blank-filled) (right-justified, blank-
filled)
Binary to decimal ASCII BTDL 0 ≤ x ≤ 99999999 One-word ASCII string
(left-justified, zero-filled) (left-justified, zero-
filled)
Binary to decimal ASCII BTDR 0 ≤ x ≤ 99999999 One-word ASCII string
(right-justified, zero-filled) (right-justified, zero-
filled)
Binary to octal ASCII BTO 0 ≤ x ≤ 77777777 8 One-word ASCII string
(right-justified, blank-filled) (right-justified, blank-
filled)
Binary to octal ASCII (left- BTOL 0 ≤ x ≤ 77777777 8 One-word ASCII string
justified, zero-filled) (left-justified, zero-
filled)
Binary to octal ASCII BTOR 0 ≤ x ≤ 77777777 8 One-word ASCII string
(right-justified, zero-filled) (right-justified, zero-
filled)
Decimal ASCII to binary DTB Decimal ASCII One word containing
(left-justified, zero- decimal equivalent of
filled) ASCII string
Octal ASCII to binary OTB Octal ASCII (left- One word containing
justified, zero-filled) octal equivalent of
ASCII string

The Cray Assembly Language (CAL) entry points are the same as the Fortran entry points for the preceding
routines with the percent sign (%) appended. For example, BTDL is called as BTDL% from CAL.

IEEE CONVERSION ROUTINES

The IEEE conversion routines convert Cray single-precision real numbers to or from IEEE single- or
double-precision real numbers.
The following list contains the purpose and name of the IEEE conversion routines. See the individual man
pages for implementation details.
• IEG2CRAY: Converts IEEE/Generic 32-bit data to Cray data
• CRAY2IEG: Converts Cray data to IEEE/Generic 32-bit data
• IEU2CRAY: Converts DEC ULTRIX/Generic Little Endian 32-bit data to Cray data

004– 2165– 002 331

INTRO_CONVERSION ( 3F ) INTRO_CONVERSION ( 3F )

• CRAY2IEU: Converts Cray data to DEC ULTRIX Generic Little Endian 32-bit data
• CRI2CRY: Converts Fortran data from UNICOS/mk to UNICOS type
• CRY2CRI: Converts Fortran data from UNICOS to UNICOS/mk type
• CRI2CRAY: Converts IEEE/MPP 32-bit data to Cray PVP 64-bit data
• CRAY2CRI: Converts Cray PVP 64-bit data to IEEE/MPP 32-bit data

OTHER CONVERSION ROUTINES

These routines place the octal ASCII representation of a Cray word into a character area, convert trailing
blanks to nulls or trailing nulls to blanks, and translate a string from one code to another, using a translation
table.
The following list contains the purpose and name of these conversion routines.
• B2OCT: Places an octal ASCII representation of a Cray word into a character area
• CHCONV: Converts decimal ASCII to integers
• RBN: Converts trailing blanks to nulls
• RNB: Converts trailing nulls to blanks

332 004– 2165– 002

B2OCT ( 3F ) B2OCT ( 3F )

NAME
B2OCT – Places an octal Hollerith representation of a Cray numeric value into a specified part of an integer
array

SYNOPSIS
CALL B2OCT(s, j, k, v, n)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
B2OCT puts an octal Hollerith representation of a Cray numeric value into a specified part of an integer
array.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
s An integer array to contain the octal Hollerith representation of the integer input value.
j An integer variable, expression, or constant specifying the byte offset within array s where the
first character of the octal representation is to be placed. A value of 1 indicates that the
destination begins with the first (leftmost) byte of the first word of s. j must be greater than 0.
k An integer variable, expression, or constant containing the number of characters used in the
Hollerith representation; k must be greater than 0. k indicates the size of the total area to be
filled, and the area is blank-filled if necessary.
v An integer variable, expression, or constant containing a value to be converted. The low-order n
bits of word v are used to form the Hollerith representation. The value in v must be less than or
63
equal to 2 – 1.
n An integer variable, expression, or constant containing the number of low-order bits of v to
convert to octal Hollerith character representation; n must be within the range: 1 ≤ n ≤ 64. If
insufficient space is available in s (3k<n), the specified region in s is automatically filled with
asterisks (*).
B2OCT places the octal Hollerith representation of the low-order n bits of a full Cray word into a specified
part of s. The k bytes in array s, pointed to by j, are first set to Hollerith blanks. The low-order n bits of v
are then converted to octal Hollerith, using leading zeros if necessary. The converted value (n/3 bytes,
rounded up) is right-justified in the blanked-out destination area of s.

004– 2165– 002 333

B2OCT ( 3F ) B2OCT ( 3F )

The B2OCT routine is an internal library routine that may not be available in a future release. Use the octal
(O) edit descriptor with an internal file to create the octal representation of a numeric value. An example of
the O edit descriptor with an internal file is:
progra m tes tf
intege r iva r
cha rac ter *22 cva r(2)
iva r=1 234 56789
wri te(cva r,2) iva r,ivar
2 for mat (o2 2/o 22.15)
pri nt *,’ cvar(1 )=’,cv ar( 1)
pri nt *,’ cvar(2 )=’,cv ar(2)
end

The octal values in cvar are:

cvar(1 )=0 000 000000 000726 746425
cvar(2 )= 000 000726 746425

334 004– 2165– 002

CDC2CRAY ( 3F ) CDC2CRAY ( 3F )

NAME
CDC2CRAY, CRAY2CDC – Converts CDC data to Cray format and vice versa

SYNOPSIS
INTEGER CDC2CRAY
iret=CDC2CRAY(type, num, foreign, bitoff, cray[, strd[, craychar]])
INTEGER CRAY2CDC
iret=CRAY2CDC(type, num, foreign, bitoff, cray[, strd[, craychar]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
CDC2CRAY converts CDC data to Cray format. It accepts as input a bit string starting at the first element of
the array or variable foreign, at bit bitoff, and converts the data according to type, placing the converted data
in cray.
CRAY2CDC converts Cray data to CDC format. It accepts as input a bit string starting at the first element of
the array or variable cray(1) and converts the data according to type, placing the converted data in foreign at
bit bitoff.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
type Type integer. The variable type code used by the libraries. The following lists these codes and
shows the corresponding CDC and Cray formats (and the formats’ mapping to one another). In
the real, double, and complex conversions between CDC and the Cray format, all of the bits in
the mantissas are retained; neither rounding nor truncation are required.

Code CDC Cray CDC2CRAY CRAY2CDC

1 INTEGER(60-bit) INTEGER(64-bit)
2 REAL(60-bit) REAL(64-bit) Neither Neither
3 DOUBLE(120-bit) DOUBLE(128-bit) Neither Neither
4 COMPLEX(2x60-bit) COMPLEX(2x64-bit) Neither Neither
5 LOGICAL(60-bit) LOGICAL(64-bit)
6 CHARACTER CHAR (ASCII)(8-bit)
(Display code)
7 INTEGER(60-bit) INTEGER(24)(64-bit)

004– 2165– 002 335

CDC2CRAY ( 3F ) CDC2CRAY ( 3F )

num Type integer variable, array, or constant. Number of data items to convert.
foreign CDC2CRAY: Variable or array of any noncharacter type and of any length containing the CDC
format data to convert.
CRAY2CDC: Variable or array of any noncharacter type and of any length to receive the
converted CDC data.
bitoff Type integer variable, expression, or constant in the range 0 ≤ bitoff ≤ 63.
CDC2CRAY: Bit number within foreign to begin the conversion
CRAY2CDC: Bit number within foreign to place the converted data
Bits are numbered from 0, beginning at leftmost bit of foreign. (Bit 0 is the sign bit.)
cray Variable or array of any noncharacter type and of any length containing the Cray format data,
word-aligned.
strd Type integer variable, expression, or constant.
CDC2CRAY: Memory increment for storing the conversion results in cray. If strd = 1, the items
are placed in contiguous memory locations in cray. If strd > 1, the items are placed in cray in
memory locations at intervals specified by strd. For example, if strd = 3, the input items are
stored in cray at locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are taken from foreign in a continuous bit stream.
CRAY2CDC: Memory increment for loading the Cray items to be converted. If strd = 1, the
items are taken from contiguous memory locations in cray. If strd > 1, the items are taken from
cray memory locations at intervals specified by strd. For example, if strd = 3, the items are
taken from cray locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are placed in foreign in a continuous bit stream.
For double-word items, this is a stride of items, not of words. Default stride for complex input
is 1. For data of type character, strd must equal 1.
Default value is 1.
This is an optional argument.
craychar Type Character*N. Variable or array containing the Cray format data. Must be used instead of
cray when the variable type is character. If craychar is supplied, cray is ignored. This is an
optional argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

336 004– 2165– 002

CDC2CRAY ( 3F ) CDC2CRAY ( 3F )

RETURN VALUES
The returned function values are as follows:
=0 All values converted without error.
<0 Error. An error was detected in the input parameters.

EXAMPLES
Example 1: The following code converts LENGTH CDC REAL(60-bit) numbers in array ACDC to Cray
REAL(64-bit) numbers and places the results in array ACRAY.
INT EGER CDC2CR AY
IRET=C DC2 CRA Y(2,LE NGTH,A CDC,0, ACR AY)
IF( IRE T.LT.0 ) GOTO 99 ! err or

Example 2: The following code converts the LENGTH CRAY REAL(64-bit) numbers in array ACRAY from
the previous example back to CDC REAL(60-bit) numbers and places the results in array ACDC2.
INTEGE R CRA Y2C DC
IRE T=C RAY 2CDC(2,LE NGT H,A CDC2,0,AC RAY)
IF( IRET.L T.0) GOTO 99 ! err or

004– 2165– 002 337

CHCONV ( 3F ) CHCONV ( 3F )

NAME
CHCONV – Converts decimal ASCII numerals to an integer value

SYNOPSIS
CALL CHCONV(src, isb, num, ir)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
This routine converts decimal ASCII numerals to integer values.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine:
src A variable or array of type Hollerith containing ASCII data or blanks.
isb Starting character in the src string. Specify an integer variable, expression, or constant. Characters
are numbered from 1, beginning at the leftmost character position of src.
num Number of ASCII characters to convert. Specify an integer variable, expression, or constant.
ir Integer result.
Blanks in the input field are treated as zeros. A minus sign encountered anywhere in the input field
produces a negative result. Input characters other than blank, digits 0 through 9, a minus sign, or more than
one minus sign produce a fatal error.

338 004– 2165– 002

CHCONV ( 3F ) CHCONV ( 3F )

The CHCONV routine is an internal library routine that may not be available in future releases. Use an
internal file with a standard Fortran READ statement to convert the ASCII character representation to a
numeric value. An example of the READ statement with an internal file is:
pro gra m tes tf
rea l ava r
int ege r iva r
charac ter *22 cva r(2)
cva r(1 )=’123456 789 .01 2e0’
cva r(2 )=’123456 789 ’
rea d(c var,2) ivar,ivar
2 for mat (e2 2.1 0/i22)
pri nt *,’avar=’ ,av ar
pri nt *,’ivar=’ ,iv ar
end

The value for avar is 123456789.012 and the value for ivar is 123456789.

004– 2165– 002 339

CRI2CRAY ( 3F ) CRI2CRAY ( 3F )

NAME
CRI2CRAY, CRAY2CRI – Converts IEEE/MPP 64-bit data to Cray PVP 64-bit data and vice versa

SYNOPSIS
INTEGER CRI2CRAY, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) nativech
DIMENSION foreign(*), native(*)
ierr = CRI2CRAY(type, num, foreign, bitoff, native[, stride[, nativech]])
INTEGER CRAY2CRI, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) nativech
DIMENSION foreign(*), native(*)
ierr = CRAY2CRI(type, num, foreign, bitoff, native[, stride[, nativech]])

IMPLEMENTATION
UNICOS and UNICOS/mk systems (deferred on Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
CRI2CRAY converts Fortran data types on Cray MPP systems (using IEEE floating-point representation) to
Cray PVP systems Fortran data types.
CRAY2CRI converts Cray PVP systems Fortran data types to Cray MPP systems (using IEEE floating-point
representation) Fortran data types.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
ierr An integer giving the returned function value, as follows:
<0 Parameter error; no translation performed.
=0 Translation complete; no errors.
>0 Translation complete; return value is the number of values that completely overflowed
(CRAY2CRI only).
type An integer giving the data type code, as follows (all float-to-float conversions are rounded):
Code Description
0 Typeless (no translation)
1 Integer
CRI2CRAY: 64-bit twos complement to 64-bit twos complement; no translation.
CRAY2CRI: 64-bit twos complement to 64-bit twos complement; no translation.

340 004– 2165– 002

CRI2CRAY ( 3F ) CRI2CRAY ( 3F )

2 Real
CRI2CRAY: 64-bit IEEE floating point to 64-bit, single-precision, Cray real numbers.
CRAY2CRI: 64-bit, single-precision, Cray real numbers to 64-bit IEEE floating point.
3 Double Precision
CRI2CRAY: 64-bit IEEE floating point to 128-bit, double-precision, Cray floating point.
CRAY2CRI: 128-bit, double-precision, Cray floating point to 64-bit IEEE floating point.
4 Complex
CRI2CRAY: 2 x 64-bit, single-precision, IEEE floating point to 2 x 64-bit,
single-precision, Cray floating point.
CRAY2CRI: 2 x 64-bit, single-precision, Cray floating point to 2 x 64-bit IEEE floating
point.
5 Logical
CRI2CRAY: 64-bit logical to 64-bit Cray logical; all nonzero values are converted to
Cray logical trues and all zero values are converted to Cray logical falses.
CRAY2CRI: 64-bit Cray logical to 64-bit logical; all negative Cray values are converted
to a value of 1, all positive Cray values remain unchanged.
6 Character
ASCII to ASCII; no translation.
7 Short integer
CRI2CRAY: 32-bit twos complement to 64-bit twos complement.
CRAY2CRI: 64-bit twos complement to 32-bit twos complement.
num An integer giving the number of data items to convert.
foreign Variable or array of any noncharacter type or length containing Cray PVP systems or Cray MPP
systems data, whichever is not native to the current system. This variable or array either receives
the converted data or contains data to be converted.
bitoff An integer giving the bit offset within foreign to begin the conversion. Bits are numbers from 0 to
63, beginning at the leftmost bit of foreign. Normally, bitoff is zero.
native Variable or array of any noncharacter type or length containing Cray PVP systems or Cray MPP
systems data, whichever is native to the current system. This variable or array either receives the
converted data or contains data to be converted. This may be a strided array. This variable should
be of a type corresponding to the type argument.
stride An integer variable or constant giving the memory increment for loading or storing data to the
native array. For two and four-word items (complex and double-precision), this is a stride of
items, not of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
For 2-word items (complex and double precision), this is a stride of items, not of words. The
default value is 1.

004– 2165– 002 341

CRI2CRAY ( 3F ) CRI2CRAY ( 3F )

nativech Type Character.

CRI2CRAY: Optional character variable or array to receive the converted characters if type is 6
(character).
CRAY2CRI: Optional character variable or array containing the characters to be converted if type
is 6 (character).

CAUTION
The foreign and native variables should not be associated (aliased to each other).

342 004– 2165– 002

CRI2IBM ( 3F ) CRI2IBM ( 3F )

NAME
CRI2IBM, IBM2CRI – Converts Cray IEEE Fortran data types to IBM (360/370-style) Fortran data types

SYNOPSIS
INTEGER CRI2IBM, IBM2CRI
ierr= CRI2IBM(type, num, foreign, bitoff, native, stride, natlen, forlen [,nativech])
ierr= IBM2CRI(type, num, foreign, bitoff, native, stride, natlen, forlen [,nativech])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CRI2IBM converts Fortran data types for Cray MPP systems using IEEE into equivalent IBM
representation. The data consists of floating-point, integer, logical, and character representation.
IBM2CRI converts Fortran data types for Cray MPP systems using IEEE floating-point representation from
equivalent IBM representation.
A denormal is a signed value with the following magnitudes:
• 32-bit IEEE value: magnitude between 1.1 -38 and 0
• 64-bit IEEE value: magnitude between 2.2 -308 and 0
• 128-bit IEEE value: magnitude between 3.3 -4932 and 0
IBM2CRI converts input values which fall in the range of the denormal to zero.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk systems, the default kind is KIND=8 for
integer, real, complex, and logical arguments.
The following is a list of valid arguments for this routine.
type An integer giving the data type code, as follows:
1 Typeless (no translation): 32-bit, 64-bit, 128-bit, and 256-bit data items. natlen and forlen
must be equal. 32-bit typeless is not supported on Cray PVP systems and 256-bit typeless is
not supported on Cray MPP systems.
2 Integer
CRI2IBM: 32-bit or 64-bit twos complement to 64-bit, 32-bit, 16-bit or 8-bit twos
complement
IBM2CRI: 8-bit, 16-bit, 32-bit or 64-bit twos complement to 32-bit, or 64-bit twos
complement
3 Real

004– 2165– 002 343

CRI2IBM ( 3F ) CRI2IBM ( 3F )

CRI2IBM: 32-bit, 64-bit or 128-bit CRAY IEEE floating-point to 32-bit, 64-bit or 128-bit
IBM floating-point
IBM2CRI: 32-bit, 64-bit or 128-bit IBM floating-point to 32-bit, 64-bit or 128-bit CRAY
IEEE floating-point
4 Complex
CRI2IBM: 2 x 32-bit, 64-bit or 128-bit CRAY IEEE floating- point to 2 x 32-bit, 64-bit or
128-bit IBM floating-point
IBM2CRI: 2 x 32-bit, 64-bit or 128-bit IBM floating-point to 2 x 32-bit, 64-bit or 128-bit
CRAY IEEE floating-point
5 Logical
IBM2CRI: 32-bit or 64-bit zero/nonzero logical to 64-bit, 32-bit, 16-bit or 8-bit zero/nonzero
logical
CRI2IBM: 8-bit, 16-bit, 32-bit or 64-bit zero/nonzero logical to 32-bit or 64-bit
zero/nonzero logical
6 Character
CRI2IBM: ASCII to EBCDIC
IBM2CRI: EBCDIC to ASCII
The natlen and forlen arguments select the size of the data.
num The number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length containing IBM data. This variable or array
either receives the converted data or contains data to be converted.
bitoff An integer giving the bit offset within the foreign data variable or array to begin the conversion.
bitoff must be at least 0 and no more than 63. Bits are numbered from 0 to 63, beginning at the
leftmost bit of foreign.
native Variable or array that contains (or will contain) the native data. This variable or array either
receives the converted data or contains data to be converted. This variable should be of a type that
corresponds to the type argument. If type = 6 (character), this should be a dummy integer variable
and the optional nativech argument should be a character variable or array that contains (or will
contain) the native data. On Cray PVP systems which do not use Cray IEEE floating-point data,
native contains (or will contain) the Cray IEEE data.
stride An integer variable or constant giving the Memory increment for loading or storing data to the
native array. For two and four-word items (complex and double-precision) this is a stride of items,
not words. For typeless, stride is always in 64-bit words.
natlen Internal (native) storage length, in bits.
forlen External (foreign) storage length, in bits.

344 004– 2165– 002

CRI2IBM ( 3F ) CRI2IBM ( 3F )

nativech Optional character parameter specifying native ASCII character variable if it is of type 6. This
parameter is ignored if type is not character.

NOTES
Handling of IEEE denormalized numbers is controlled through a flag in the T@IEEE COMMON block (TASK
COMMON on Cray PVP systems). Setting the DENORM flag prevents any denormalized floating-point
numbers from being produced. The following example demonstrates this:
INT EGE R (KI ND=4) DENORM , OVE RFLOW
COM MON /T@IEE E/ DENORM , OVE RFLOW !MPP sys tems
TAS K COM MON /T@IEE E/ DEN ORM, OVERFL OW !PV P system s
DEN ORM =1 !Fl ush denormali zed number s to zer o
DEN ORM=0 !Pr ese rve /creat e denormali zed num bers

The CRI2IBM/IBM2CRI routines are provided on Cray floating-point systems as a convenience even though
neither input nor output data formats are native to those systems. For parameter identification, "CRI" can be
considered the "native" data format on those systems.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

RETURN VALUES
ierr is a returned function value, which can be as follows:
<0 Parameter error; no translation performed
-1 Parameter error; too few arguments or nativech not specified with type = 6
-2 Parameter error; invalid type
-3 Parameter error; invalid num
-4 Parameter error; invalid bitoff
-5 Parameter error; invalid natlen
-6 Parameter error; invalid forlen
-7 Unable to malloc() memory for translation
-8 Combination of natlen and forlen is invalid
-9 Parameter error; native must be 64-bit word-aligned (Cray MPP systems only)
-10 foreign must be 32-bit or 64-bit word-aligned (Cray MPP systems only)
0 Translation complete; no errors
>0 Translation complete; return value is the number of values that overflowed during translation.

004– 2165– 002 345

CRI2IEG ( 3F ) CRI2IEG ( 3F )

NAME
CRI2IEG, IEG2CRI – Converts Fortran data types between Cray IEEE and generic IEEE data types

SYNOPSIS
INTEGER CRI2IEG, IEG2CRI
ierr = CRI2IEG (type, num, foreign, bitoff, native, stride, natlen, forlen [,nativech])
ierr = IEG2CRI (type, num, foreign, bitoff, native, stride, natlen, forlen [,nativech])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CRI2IEG converts Cray IEEE Fortran data types for a system using 64-bit and 128-bit IEEE floating-point
representation (abbreviated as "CRI" in the following text) to data for systems that use generic 32-bit and
64-bit IEEE floating-point representation (abbreviated as "IEG" in the following text).
IEG2CRI converts generic 32-bit and 64-bit IEEE Fortran data types to 64-bit and 128-bit IEEE Fortran
data types.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
type An integer giving the data type code, as follows.
Code Description
1 Typeless (no translation; natlen and forlen must be equal and must be 64-, 128-, or
256-bits.)
2 Integer
IEG: 8-, 16-, 32- or 64-bit twos complement
CRI: 32- or 64-bit twos complement
3 Real
IEG: 32-, 64-bit, or 128-bit IEEE floating-point
CRI: 32-bit (Cray MPP systems only), 64- or 128-bit (Cray PVP systems only) IEEE
floating-point
4 Complex
IEG: 2 x 32-, 64-bit, or 128-bit floating-point
CRI: 2 x 32-bit (Cray MPP systems only), 64- or 128-bit (Cray PVP systems only)
floating-point

346 004– 2165– 002

CRI2IEG ( 3F ) CRI2IEG ( 3F )

5 Logical
IEG: 8-, 16-, 32- or 64-bit nonzero/zero logical
CRI: 32-, or 64-bit or minus/positive logical (Cray floating– point systems) or 32-bit or
64-bit nonzero/zero logical (Cray IEEE systems)
6 Character
ASCII to ASCII; no translation (Cray floating-point systems).
The natlen and forlen parameters select the size of the data.
num Number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length containing the data which is not native to the
current system. This variable or array either receives the converted data or contains data to be
converted.
bitoff Integer giving the bit offset within the foreign data variable or array to begin the conversion. bitoff
must be at least 0 and no more than 63.
native Variable or array of any noncharacter type or length containing the data which is native to the
current system. This variable or array either receives the converted data or contains data to be
converted. This may be a strided array.
This variable should be of a type that corresponds to the type argument. If type=6
(CHARACTER), native should be a dummy INTEGER variable and the optional nativech
argument should be a CHARACTER variable or array that contains or will contain the native data.
stride Integer variable or constant giving the memory increment for loading or storing data to the native
array. For two and four-word items (complex and double-precision), this is a stride of items, not
of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
natlen Native storage length of an item, in bits. For COMPLEX data, natlen counts the total size of the
real and imaginary component.
forlen Fortran storage length of an item, in bits. For COMPLEX data, forlen counts the total size of the
real and imaginary components.
nativech Optional character parameter specifying native target variable if it is of type CHARACTER (type =
6). This parameter is ignored if type is not CHARACTER.

NOTES
Handling of IEEE denormalized numbers is controlled through a flag in the T@IEEE COMMON block (TASK
COMMON on Cray PVP systems). Setting the DENORM flag prevents any denormalized floating-point
numbers from being produced. The following example demonstrates this:

004– 2165– 002 347

CRI2IEG ( 3F ) CRI2IEG ( 3F )

INTEGER (KIND= 4) DENORM, OVE RFL OW

COMMON /T@IEE E/ DEN ORM , OVE RFL OW !MP P system s
TASK COMMON /T@ IEEE/ DENORM , OVE RFL OW !PV P system s
DENORM =1 !Fl ush den ormali zed number s to zer o
DENORM =0 !Pr ese rve /cr eate denorm ali zed number s

The CRI2IEG/IEG2CRI routines are provided on Cray Research floating-point systems as a convenience
even though neither input nor output data formats are native to those systems. For parameter identification,
"CRI" can be considered the "native" data format on those systems.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
-1 Parameter error; too many arguments or nativech not specified with type = 6.
-2 Parameter error; invalid type.
-3 Parameter error; invalid num.
-4 Parameter error; invalid bitoff.
-5 Parameter error; invalid natlen.
-6 Parameter error; invalid forlen.
-7 Unable to malloc() memory for translation.
-8 Combination of natlen and forlen is invalid.
0 Translation complete; no errors.
>0 Translation complete; return value is the number of integer or real values that completely overflowed
during conversion.

348 004– 2165– 002

CRY2CRI ( 3F ) CRY2CRI ( 3F )

NAME
CRY2CRI, CRI2CRY – Converts Fortran data types between Cray floating-point and IEEE floating-point
systems

SYNOPSIS
INTEGER CRY2CRI, CRI2CRY
ierr = CRI2CRY(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])
ierr = CRY2CRI(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CRY2CRI converts Cray Fortran data types for a system using Cray floating-point representation
(abbreviated as "Cray" in the following text) to data for systems that use IEEE floating-point representation
(abbreviated as "IEEE" in the following text).
CRI2CRY converts IEEE Fortran data types to Cray Fortran data types.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid parameters for this routine.
type An integer giving the data type code, as follows.
Code Description
1 Typeless (no translation; natlen and forlen must be equal and must be 64-, 128-, or
256-bits.)
2 Integer
Cray: 64-bit twos complement
IEEE: 32- or 64-bit twos complement
3 Floating-point
Cray: 64- or 128-bit Cray floating-point
IEEE: 32-, 64-bit (available on all systems), or 128-bit IEEE floating-point (Cray T90
only)
4 Complex
IEEE: 2 x 32, 64-bit (all systems), or 128-bit floating-point (Cray T90 only)
Cray: 2 x 64 or 128-bit floating-point

004– 2165– 002 349

CRY2CRI ( 3F ) CRY2CRI ( 3F )

5 Logical
IEEE: 32- or 64-bit nonzero/zero logical
Cray: 64-bit minus/positive logical
6 Character
ASCII to ASCII; no translation.
The natlen and forlen parameters select the size of the data.
num Number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length containing Cray PVP systems or Cray MPP
systems data, whichever is not native to the current system. This variable or array either receives
the converted data or contain data to be converted.
bitoff Integer giving the bit offset within the foreign data variable or array to begin the conversion. bitoff
must be at least 0 and no more than 63.
native Variable or array of any noncharacter type or length containing Cray PVP systems or Cray MPP
systems data, whichever is native to the current system. This variable or array either receives the
converted data or contains data to be converted. This may be a strided array.
stride Integer variable or constant giving the memory increment for loading or storing data to the native
array. For two and four-word items (complex and double-precision), this is a stride of items, not
of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
natlen Native storage length of an item, in bits. For COMPLEX data, natlen counts the total size of the
real and imaginary component.
forlen Fortran storage length of an item, in bits. For COMPLEX data, forlen counts the total size of the
real and imaginary components.
nativech Optional character parameter specifying native target variable if it is of type character (type = 6).
This parameter is ignored if type is not character.

NOTES
CRI2CRY and IEC2CRAY are comparable functions.
CRY2CRI and CRAY2IEC are comparable functions.
These data conversion routines also correctly translate CRAY-2 data files with the exception of logical data.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

350 004– 2165– 002

CRY2CRI ( 3F ) CRY2CRI ( 3F )

RETURN VALUES
The returned function values are as follows:
-1 Parameter error; too few arguments or nativech not specified with type = 6.
-2 Parameter error; invalid type.
-3 Parameter error; invalid num.
-4 Parameter error; invalid bitoff.
-5 Parameter error; invalid natlen.
-6 Parameter error; invalid forlen.
-7 Unable to malloc() memory for translation.
0 Translation complete; no errors.
>0 Translation complete; return value is the number of integer or real values that completely overflowed
during conversion. Overflows and NaNs which exist before conversion, are not included.

004– 2165– 002 351

CRY2MIPS ( 3F ) CRY2MIPS ( 3F )

NAME
CRY2MIPS, MIPS2CRY – Converts Fortran data types between Cray Fortran data types and MIPS IEEE
Fortran data types

SYNOPSIS
INTEGER CRY2MIPS, MIPS2CRY
ierr = CRY2MIPS(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])
ierr = MIPS2CRY(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)
IRIX systems

DESCRIPTION
CRY2MIPS converts Cray Fortran data types (indicated as "Cray" in the following text) to data for systems
that use MIPS IEEE Fortran data types (abbreviated as "MIPS" in the following text).
MIPS2CRY converts MIPS IEEE Fortran data types to Cray Fortran data types.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS or IRIX systems, all
arguments must be of default kind unless documented otherwise. On UNICOS systems, the default kind is
KIND=8 for integer, real, complex, and logical arguments; on IRIX systems, the default kind is KIND=4.
The following is a list of valid parameters for this routine.
type An integer giving the data type code, as follows.
Code Description
1 Typeless (no translation; natlen and forlen must be equal and must be 64-, 128-, or
256-bits.)
2 Integer
Cray: 64-bit twos complement
MIPS: 8-, 16-, 32- or 64-bit twos complement
3 Real
Cray: 64- or 128-bit Cray real
MIPS: 32-, 64-, or 128-bit MIPS real
4 Complex
Cray: 2 x 64 bit or 128-bit floating-point
MIPS: 2 x 32, 64-bit, or 128-bit floating-point

352 004– 2165– 002

CRY2MIPS ( 3F ) CRY2MIPS ( 3F )

5 Logical
CRAY: 64-bit positive/negative logical
MIPS: 8-, 16-, 32-, or 64-bit zero/nonzero logical
6 Character
ASCII to ASCII; no translation.
The natlen and forlen parameters select the size of the data.
num Number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length to contain data which is not native to the
current system.
bitoff Integer variable, expression, or constant giving the bit offset within the foreign data variable or
array to begin the conversion. bitoff must be at least 0 and no more than 63.
native Variable or array of any noncharacter type or length to contain data which is native to the current
system. This variable or array should be of a type that corresponds to type. If type=6, use a
dummy integer variable and the nativech parameter (see description of nativech).
stride Integer variable or constant giving the memory increment for loading or storing data to the native
array. For two and four-word items (complex and double-precision), this is a stride of items, not
of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
natlen Native storage length of an item, in bits. For COMPLEX data, natlen counts the total size of the
real and imaginary component.
forlen Foreign storage length of an item, in bits. For COMPLEX data, forlen counts the total size of the
real and imaginary components.
nativech Optional character parameter specifying native target variable if it is of type character (type = 6).
This parameter is ignored if type is not character.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
<0 Parameter error; no translation performed.
-1 Parameter error; too few arguments or nativech not specified with type = 6. This error is not returned
on IRIX systems.
-2 Parameter error; invalid type.
-3 Parameter error; invalid num.

004– 2165– 002 353

CRY2MIPS ( 3F ) CRY2MIPS ( 3F )

-4 Parameter error; invalid bitoff.

-5 Parameter error; invalid natlen.
-6 Parameter error; invalid forlen.
-7 Unable to malloc() memory for translation.
-8 Combination of natlen and forlen is invalid.
-9 native must be 64-bit word-aligned (CRAY only)
-10 foreign must be 64-bit word-aligned.
0 Translation complete; no errors.
>0 Translation complete; return value is the number of integer or real values that completely overflowed
during conversion. Overflows and NaNs which exist before conversion are not included.

354 004– 2165– 002

DSASC ( 3F ) DSASC ( 3F )

NAME
DSASC, ASCDC – Converts CDC display code character to ASCII character and vice versa

SYNOPSIS
CALL DSASC(src, sc, dest, num)
CALL ASCDC(src, sc, dest, num)

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
DSASC converts CDC display code characters to ASCII characters. ASCDC converts ASCII characters to
CDC display code characters.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
src For DSASC, a variable or array of any noncharacter type and of any length containing CDC display
code characters (64-character set), left-justified in a 64-bit Cray word. Contains a maximum of 10
display code characters per word. If the input string is packed 6-bit characters, use U6064(3F) to
unpack characters 10 per word. For ASCDC, a variable or array of any type or length containing
ASCII data.
sc Display code or ASCII character position to begin the conversion. Leftmost position is 1.
dest For DSASC, a variable or array of any noncharacter type and of any length to contain the converted
ASCII data. Results are packed 8 characters per word. For ASCDC, a variable or array of any type
or length to contain the converted CDC display code characters (64-character set). Results are
packed 60 ASCII characters with 4 blank end bits per 64-bit word.
num Number of CDC display code or ASCII characters to convert. Specify an integer variable,
expression, or constant.

004– 2165– 002 355

ETA2CRAY ( 3F ) ETA2CRAY ( 3F )

NAME
ETA2CRAY, CRAY2ETA – Converts ETA/CYBER 205 data to Cray format and vice versa

SYNOPSIS
INTEGER ETA2CRAY
iret=ETA2CRAY(type, num, foreign, bitoff, cray[, strd[, craychar]])
INTEGER CRAY2ETA
iret=CRAY2ETA(type, num, foreign, bitoff, cray[, strd[, craychar]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
ETA2CRAY converts ETA/CYBER 205 data to Cray format. It accepts as input a bit string starting at
foreign(1) at bit bitoff, converts the data according to type, and places the converted data in cray.
CRAY2ETA converts Cray data to ETA/CYBER 205 format. It accepts as input a bit string starting at
cray(1), converts the data according to type, and places the converted data in foreign at bit bitoff.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine:
type Type integer. The variable type code used by the libraries. The following lists these codes and
shows the corresponding ETA/CYBER 205 and Cray formats (and the formats’ mapping to one
another).

Code ETA Cray

1 INTEGER INTEGER(64-bit)
2 REAL REAL(64-bit)
3 DOUBLE PRECISION DOUBLE(128-bit)
4 COMPLEX COMPLEX(2*64-bit)
5 LOGICAL LOGICAL(64-bit)
6 CHARACTER (ASCII) CHAR (ASCII)(8-bit)
7 Half-precision REAL REAL(64-bit)

num Type integer variable, array, or constant. Number of data items to convert.
foreign ETA2CRAY: Variable or array of any noncharacter type and of any length containing the
ETA/CYBER 205 format data to convert.

356 004– 2165– 002

ETA2CRAY ( 3F ) ETA2CRAY ( 3F )

CRAY2ETA: Variable or array of any type except CHARACTER and of any length to receive
the converted ETA/CYBER 205 data.
bitoff Type integer variable, expression, or constant in the range 0 ≤ bitoff ≤ 63.
ETA2CRAY: Bit number within foreign to begin the conversion.
CRAY2ETA: Bit number within foreign to place the converted data.
Bits are numbered from 0, beginning at leftmost bit of foreign. (Bit 0 is the sign bit.)
cray Variable or array of any noncharacter type and of any length containing the Cray format data,
word-aligned.
strd Type integer variable, expression, or constant.
ETA2CRAY: Memory increment for storing the conversion results in cray. If strd = 1, the items
are placed in contiguous memory locations in cray. If strd > 1, the items are placed in cray in
memory locations at intervals specified by strd. For example, if strd = 3, the input items are
stored in cray at locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are taken from foreign in a continuous bit stream.
CRAY2ETA: Memory increment for loading the Cray items to be converted. If strd = 1, the
items are taken from contiguous memory locations in cray. If strd > 1, the items are taken from
cray memory locations at intervals specified by strd. For example, if strd = 3, the items are
taken from cray locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are placed in foreign in a continuous bit stream.
For double-word items, this is a stride of items, not of words. Default stride for complex input
is 1. For data of type character, strd must equal 1.
Default value is 1.
This is an optional argument.
craychar Type Character*N. Variable or array containing the Cray format data. Must be used instead of
cray when the variable type is character. If craychar is supplied, cray is ignored. This is an
optional argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
=0 All values converted without error.
<0 Error. An error was detected in the input parameters.

004– 2165– 002 357

ETA2CRAY ( 3F ) ETA2CRAY ( 3F )

EXAMPLES
Example 1: The following code converts LENGTH ETA/CYBER 205 REAL numbers in array AETA to
Cray REAL(64-bit) numbers and places the results in array ACRAY.
INT EGE R ETA 2CRAY
IRET=E TA2CRA Y(2,LE NGTH,AETA ,0,ACR AY)
IF(IRE T.L T.0) GOTO 99 ! error

Example 2: The following code converts the LENGTH CRAY REAL(64-bit) numbers in array ACRAY from
the previous example back to ETA REAL numbers and places the results in array AETA2.
INT EGER CRAY2E TA
IRE T=CRAY 2ETA(2 ,LE NGTH,A ETA 2,0 ,ACRAY )
IF( IRET.L T.0 ) GOT O 99 ! error

358 004– 2165– 002

FP6064 ( 3F ) FP6064 ( 3F )

NAME
FP6064, FP6460 – Converts between CDC 60-bit and Cray 64-bit numbers

SYNOPSIS
CALL FP6064(fpn, dest, num)
CALL FP6460(fpn, dest, num)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
FP6064 converts CDC 60-bit single-precision numbers to Cray 64-bit single-precision numbers.
FP6460 converts Cray 64-bit single-precision numbers to CDC 60-bit single-precision numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn For FP6064, a variable or array of any type or length containing CDC 60-bit, single-precision
numbers, left-justified in a Cray 64-bit word. For FP6460, a variable or array of any length
and of type real containing Cray single-precision numbers.
dest Variable or array of type real to contain the converted Cray 64-bit, single-precision or CDC
60-bit single-precision numbers. (In FP6460, each floating-point number is left-justified in a
64-bit word.)
num Number of CDC or Cray single-precision numbers to convert. Specify an integer variable,
expression, or constant.

004– 2165– 002 359

IBM2CRAY ( 3F ) IBM2CRAY ( 3F )

NAME
IBM2CRAY, CRAY2IBM – Converts IBM data to Cray format and vice versa

SYNOPSIS
INTEGER IBM2CRAY
iret=IBM2CRAY(type, num, foreign, bitoff, cray [,strd [,craychar]])
INTEGER CRAY2IBM
iret=CRAY2IBM(type, num, foreign, bitoff, cray [,strd [,craychar]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
IBM2CRAY converts IBM data to Cray format. It accepts as input a bit string starting at the first element of
foreign at bit bitoff and converts the data according to type, placing the converted data in cray.
CRAY2IBM converts Cray data to IBM format. It accepts as input a bit string starting at the first element of
cray and converts the data according to type, placing the converted data in foreign at bit bitoff.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
type Type integer. The variable type code used by the libraries. The following lists these codes and
shows the corresponding IBM and Cray formats (and the formats’ mapping to one another). In
the conversion from Cray to IBM floating-point format for real, double, and complex data, the
mantissa is truncated rather than rounded.

Code IBM Cray CRAY2IBM IBM2CRAY

1 INTEGER*4 INTEGER(64-bit)
2 REAL*4 REAL(64-bit) Truncation Not applicable
3 REAL*8 DOUBLE(128-bit) Truncation Not applicable
4 COMPLEX*4 COMPLEX(2*64-bit) Truncation Not applicable
5 LOGICAL*4 LOGICAL(64-bit)
6 CHARACTER CHAR (ASCII)(8-bit)
(EBCDIC)
7 INTEGER*2 INTEGER(24)(64-bit)

num Type integer variable, array, or constant. Number of data items to convert.

360 004– 2165– 002

IBM2CRAY ( 3F ) IBM2CRAY ( 3F )

foreign IBM2CRAY: Variable or array of any noncharacter type and of any length containing the IBM
format data to convert.
CRAY2IBM: Variable or array of any noncharacter type and of any length to receive the
converted IBM data.
bitoff Type integer variable, expression, or constant in the range 0 ≤ bitoff ≤ 63.
IBM2CRAY: Bit number within foreign to begin the conversion.
CRAY2IBM: Bit number within foreign to place the converted data.
Bits are numbered from 0, beginning at leftmost bit of foreign. (Bit 0 is the sign bit.)
cray Variable or array of any noncharacter type and of any length containing the Cray format data,
word-aligned.
strd Type integer variable, expression, or constant.
IBM2CRAY: Memory increment for storing the conversion results in cray. If strd = 1, the items
are placed in contiguous memory locations in cray. If strd > 1, the items are placed in cray in
memory locations at intervals specified by strd. For example, if strd = 3, the input items are
stored in cray at locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are taken from foreign in a continuous bit stream.
CRAY2IBM: Memory increment for loading the Cray items to be converted. If strd = 1, the
items are taken from contiguous memory locations in cray. If strd > 1, the items are taken from
cray memory locations at intervals specified by strd. For example, if strd = 3, the items are
taken from cray locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are placed in foreign in a continuous bit stream.
For double-word items, this is a stride of items, not of words. Default stride for complex input
is 1. For data of type character, strd must equal 1.
Default value is 1.
This is an optional argument.
craychar Type Character*N. Variable or array containing the Cray format data. Must be used instead of
cray when the variable type is character. If craychar is supplied, cray is ignored. This is an
optional argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
=0 All values converted without error.
<0 Error. An error was detected in the input parameters.

004– 2165– 002 361

IBM2CRAY ( 3F ) IBM2CRAY ( 3F )

EXAMPLES
Example 1: The following code converts LENGTH IBM REAL*4 numbers in array AIBM to Cray
REAL(64-bit) numbers and places the results in array ACRAY.
INTEGE R IBM2CR AY
IRET=I BM2CRA Y(2,LE NGTH,AIBM ,0,ACR AY)
IF(IRE T.L T.0) GOTO 99 ! error

Example 2: The following code converts the LENGTH CRAY REAL(64-bit) numbers in array ACRAY from
the previous example back to IBM REAL*4 numbers and places the results in array AIBM2.
INTEGE R CRAY2I BM
IRE T=CRAY 2IBM(2 ,LE NGTH,A IBM 2,0 ,ACRAY )
IF( IRET.L T.0 ) GOT O 99 ! error

362 004– 2165– 002

IEG2CRAY ( 3F ) IEG2CRAY ( 3F )

NAME
IEG2CRAY, CRAY2IEG – Converts IEEE/Generic 32-bit data to Cray 64-bit data and vice versa

SYNOPSIS
INTEGER IEG2CRAY, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) craych
DIMENSION foreign(*), cray(*)
ierr = IEG2CRAY(type, num, foreign, bitoff, cray[, stride[, craych]])
INTEGER CRAY2IEG, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) craych
DIMENSION foreign(*), cray(*)
ierr = CRAY2IEG(type, num, foreign, bitoff, cray[, stride[, craych]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
IEG2CRAY converts Fortran data types on a generic 32-bit platform (using IEEE floating-point
representation) to Cray Fortran data types.
CRAY2IEG converts Cray Fortran data types to a generic 32-bit platform (using IEEE floating-point
representation) Fortran data types.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ierr An integer giving the returned function value, as follows:
<0 Parameter error; no translation performed.
=0 Translation complete; no errors.
>0 Translation complete; return value is the number of values that completely overflowed
(CRAY2IEG only).
type An integer giving the data type code, as follows (all float-to-float conversions are rounded):

004– 2165– 002 363

IEG2CRAY ( 3F ) IEG2CRAY ( 3F )

Code Description
0 Typeless (no translation)
1 Integer
IEG2CRAY: 32-bit twos complement to 64-bit twos complement.
CRAY2IEG: 64-bit twos complement to 32-bit twos complement.
2 Real
IEG2CRAY: 32-bit, single-precision, IEEE floating point to 64-bit, single-precision, Cray
real numbers.
CRAY2IEG: 64-bit, single-precision, Cray real numbers to 32-bit, single-precision, IEEE
floating point.
3 Double
IEG2CRAY: 64-bit, double-precision, IEEE floating point to 128-bit, double-precision,
Cray floating point.
CRAY2IEG: 128-bit, double-precision, Cray floating point to 64-bit, double-precision,
IEEE floating point.
4 Complex
IEG2CRAY: 2 x 32-bit, single-precision, IEEE floating point to 2 x 64-bit,
single-precision, Cray floating point.
CRAY2IEG: 2 x 64-bit, single-precision, Cray floating point to 2 x 32-bit,
single-precision, IEEE floating point.
5 Logical
IEG2CRAY: 32-bit generic logical to 64-bit Cray logical; all nonzero values are converted
to Cray logical trues and all zero values are converted to Cray logical falses.
CRAY2IEG: 64-bit Cray logical to 32-bit generic logical; all nonzero Cray values are
converted to a value of 1, all zero Cray values remain unchanged.
6 Character
ASCII to ASCII; no translation.
7 Short integer
IEG2CRAY: 16-bit twos complement to 32-bit twos complement.
CRAY2IEG: 32-bit twos complement to 16-bit twos complement.
8 Special
IEG2CRAY: 64-bit, double-precision, IEEE floating point to 64-bit, single-precision, Cray
real numbers.
CRAY2IEG: 64-bit, single-precision, Cray real numbers to 64-bit, double-precision, IEEE
floating point.
num An integer giving the number of data items to convert.

364 004– 2165– 002

IEG2CRAY ( 3F ) IEG2CRAY ( 3F )

foreign IEG2CRAY: Variable or array of any noncharacter type containing the data to be converted.
CRAY2IEG: Variable or array of any noncharacter type to receive the converted data.
bitoff An integer giving the bit offset within foreign to begin the conversion. Bits are numbers from 0 to
63, beginning at the leftmost bit of foreign.
stride Integer.
IEG2CRAY: Optional memory increment for storing the converted values into the cray array.
CRAY2IEG: Optional memory increment for loading the Cray values to be converted.
For 2-word items (complex and double-precision), this is a stride of items, not of words.
The default value is 1.
craych Type Character.
IEG2CRAY: Optional character variable or array to receive the converted characters if type is 6
(character).
CRAY2IEG: Optional character variable or array containing the characters to be converted if type
is 6 (character).
cray IEG2CRAY: Variable or array of any noncharacter type to receive the converted values.
CRAY2IEG: Variable or array of any noncharacter type containing the values to be converted.
This variable should be of a type corresponding to the type argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

SEE ALSO
CRY2CRI(3F)

004– 2165– 002 365

IEG2CRI_77 ( 3F ) IEG2CRI_77 ( 3F )

NAME
IEG2CRI_77, CRI2IEG_77 – Converts IEEE 32-bit data to Cray IEEE 64-bit data and vice versa

SYNOPSIS
INTEGER CRI2IEG_77, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) nativech
DIMENSION foreign(*), native(*)
ierr = IEG2CRI_77(type, num, foreign, bitoff, native[, stride[, nativech]])
INTEGER CRI2IEG_77, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) nativech
DIMENSION foreign(*), native(*)
ierr = CRI2IEG_77(type, num, foreign, bitoff, native[, stride[, nativech]])

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
IEG2CRI_77 converts from 32-bit generic IEEE floating-point representation to Cray IEEE 64-bit Fortran
data types.
CRI2IEG_77 converts from Cray IEEE 64-bit Fortran data types to 32-bit generic IEEE floating-point
representation.
When using the CF90 compiler on UNICOS/mk systems, all arguments must be of default kind unless
documented otherwise. On UNICOS/mk systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ierr An integer giving the returned function value, as follows:
<0 Parameter error; no translation performed. See IEG2CRI(3F).
=0 Translation complete; no errors.
>0 Translation complete; return value is the number of values that overflowed during
conversion(CRI2IEG_77 only). Infinities existing before conversion (and NaNs) are not
counted.

366 004– 2165– 002

IEG2CRI_77 ( 3F ) IEG2CRI_77 ( 3F )

type An integer giving the data type code, as follows (all float-to-float conversions are rounded):
Code Description
0 Typeless (no translation): 64-bit, 128-bit, and 256-bit data items.
1 Integer
IEG2CRI_77: 32-bit twos complement to 64-bit twos complement; sign extension.
CRI2IEG_77: 64-bit twos complement to 32-bit twos complement. Overflow results are
undefined.
2 Real
IEG2CRI_77: 32-bit IEEE floating point to 64-bit IEEE floating point. 32-bit IEEE
denormal values are converted.
CRI2IEG_77: 64-bit, IEEE floating point to 32-bit IEEE floating point. Overflows
result in signed infinity. 32-bit IEEE denormal values can result. Underflow results in
signed zero.
3 Double Precision
IEG2CRI_77: 64-bit IEEE floating point to 128-bit IEEE floating point (deferred).
CRI2IEG_77: 128-bit IEEE floating point to 64-bit IEEE floating point (deferred).
4 Complex
IEG2CRI_77: 2 x 32-bit, IEEE floating point to 2 x 64-bit, IEEE floating point.
CRI2IEG_77: 2 x 64-bit, IEEE floating point to 2 x 32-bit, IEEE floating point. Note
that two overflows can result from each item.
5 Logical
IEG2CRI_77: 32-bit logical to 64-bit Cray logical; all nonzero values are converted to
Cray logical trues and all zero values are converted to Cray logical falses.
CRI2IEG_77: 64-bit Cray logical to 32-bit logical; all nonzero values are converted to 1
and zero values are converted to zero.
6 Character
ASCII to ASCII; no translation.
7 Short integer
IEG2CRI_77: 16-bit twos complement to 32-bit twos complement.
CRI2IEG_77: 32-bit twos complement to 16-bit twos complement. Results are
undefined on overflow.
8 Special
IEG2CRI_77: 64-bit IEEE floating point to 64-bit Cray IEEE floating point. IEEE
denormal values become signed zero, other values are unchanged.
CRI2IEG_77: 64-bit, Cray IEEE floating point to 64-bit IEEE floating point. No
conversion.

004– 2165– 002 367

IEG2CRI_77 ( 3F ) IEG2CRI_77 ( 3F )

num An integer giving the number of data items to convert. A Fortran complex number is one item.
foreign IEG2CRI_77: Variable or array of any noncharacter type containing the data to be converted.
CRI2IEG_77: Variable or array of any noncharacter type to receive the converted data.
bitoff An integer giving the bit offset within foreign to begin the conversion. Bits are numbered from 0
to 63, beginning at the leftmost bit of foreign.
native IEG2CRI_77: Variable or array of any noncharacter type to receive the converted values.
CRI2IEG_77: Variable or array of any noncharacter type containing the values to be converted.
This variable should be of a type corresponding to the type argument.
stride An integer.
IEG2CRI_77: Optional memory increment for storing the converted values into the native array.
CRI2IEG_77: Optional memory increment for loading the Cray PVP systems values to be
converted from the native array.
For 2-word items (complex and double-precision), this is a stride of items, not of words.
The default value is 1.
nativech Type character.
IEG2CRI_77: Optional character variable or array to receive the converted characters if type is 6
(character).
CRI2IEG_77: Optional character variable or array containing the characters to be converted if
type is 6 (character).

CAUTION
The foreign and native variables should not be associated (aliased to each other).

SEE ALSO
IEG2CRI(3F)

368 004– 2165– 002

IEG2MIPS ( 3F ) IEG2MIPS ( 3F )

NAME
IEG2MIPS, MIPS2IEG – Converts generic IEEE data to MIPS IEEE data and vice versa

SYNOPSIS
INTEGER IEG2MIPS, MIPS2IEG
ierr = IEG2MIPS(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])
ierr = MIPS2IEG(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])

IMPLEMENTATION
IRIX systems

DESCRIPTION
IEG2MIPS converts generic IEEE data types (indicated as "IEEE" in the following text) to data for systems
that use MIPS IEEE data types (abbreviated as "MIPS" in the following text).
MIPS2IEG converts MIPS IEEE data types to IEEE data types.
When using the MIPSpro 7 Fortran 90 compiler on IRIX systems, all arguments must be of default kind
unless documented otherwise. On IRIX systems, the default kind is KIND=4.
The following is a list of valid parameters for this routine.
type An integer giving the data type code, as follows.
Code Description
1 Typeless (no translation; natlen and forlen must be equal and must be 8-, 16-, 32-, 64-,
128-, or 256-bits.)
2 Integer
IEEE: 64-, 32-, 16, or 8-bit twos complement
MIPS: 64-, 32-, 16, or 8-bit twos complement
3 Real
IEEE: 32-, 64-, or 128-bit IEEE floating-point
MIPS: 32-, 64-, or 128-bit MIPS IEEE floating-point
4 Complex
IEEE: 2 x 32-, 64-, or 128-bit IEEE floating-point
MIPS: 2 x 32-, 64-, or 128-bit MIPS IEEE floating-point
5 Logical
IEEE: 64-, 32-, 16-, or 8-bit zero/nonzero logical
MIPS: 64-, 32-, 16-, or 8-bit zero/nonzero logical
6 Character
ASCII to ASCII; no translation.

004– 2165– 002 369

IEG2MIPS ( 3F ) IEG2MIPS ( 3F )

The natlen and forlen parameters select the size of the data.
num Number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length to contain data which is not native to the
current system.
bitoff Integer variable, expression, or constant giving the bit offset within the foreign data variable or
array to begin the conversion. bitoff must be at least 0 and no more than 63.
native Variable or array of any noncharacter type or length to contain data which is native to the current
system. This variable or array should be of a type that corresponds to type. If type=6, use a
dummy integer variable and the nativech parameter (see description of nativech).
stride Integer variable or constant giving the memory increment for loading or storing data to the native
array. For two and four-word items (complex and double-precision), this is a stride of items, not
of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
natlen Native storage length of an item, in bits. For COMPLEX data, natlen counts the total size of the
real and imaginary component.
forlen Foreign storage length of an item, in bits. For COMPLEX data, forlen counts the total size of the
real and imaginary components.
nativech Optional character parameter specifying native target variable if it is of type character (type = 6).
This parameter is ignored if type is not character.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
<0 Parameter error; no translation performed.
-1 Parameter error; too few arguments or nativech not specified with type = 6. This error is not returned
on IRIX systems.
-2 Parameter error; invalid type.
-3 Parameter error; invalid num.
-4 Parameter error; invalid bitoff.
-5 Parameter error; invalid natlen.
-6 Parameter error; invalid forlen.
-7 Unable to malloc() memory for translation.

370 004– 2165– 002

IEG2MIPS ( 3F ) IEG2MIPS ( 3F )

-8 Combination of natlen and forlen is invalid.

-9 native must be 64-bit word-aligned.
-10 foreign must be 64-bit word-aligned.
0 Translation complete; no errors.
>0 Translation complete; return value is the number of integer or real values that completely overflowed
during conversion. Overflows and NaNs which exist before conversion are not included.

004– 2165– 002 371

IEU2CRAY ( 3F ) IEU2CRAY ( 3F )

NAME
IEU2CRAY, CRAY2IEU – Converts DEC ULTRIX/generic little-endian 32-bit data to Cray 64-bit data and
vice versa

SYNOPSIS
INTEGER IEU2CRAY, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) craych
DIMENSION foreign(*), cray(*)
ierr = IEU2CRAY(type, num, foreign, bitoff, cray[, stride[, craych]])
INTEGER CRAY2IEU, ierr, type, num, foreign, bitoff, stride
CHARACTER * (*) craych
DIMENSION foreign(*), cray(*)
ierr = CRAY2IEU(type, num, foreign, bitoff, cray[, stride[, craych]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
IEU2CRAY converts Fortran data types on a generic little-endian 32-bit platform with IEEE floating-point
representation to Cray Fortran data types.
CRAY2IEU converts Cray Fortran data types to a Fortran data type on a generic little-endian 32-bit platform
with IEEE floating-point representation.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ierr An integer giving the returned function value, as follows:
<0 Parameter error; no translation performed.
=0 Translation complete; no errors.
>0 Translation complete; return value is the number of values that completely overflowed
(CRAY2IEU only).

372 004– 2165– 002

IEU2CRAY ( 3F ) IEU2CRAY ( 3F )

type An integer giving the data type code, as follows (all float-to-float conversions are rounded).

Code Description
0 Typeless (no translation)
1 Integer
IEU2CRAY: 32-bit twos complement to 64-bit twos complement.
CRAY2IEU: 64-bit twos complement to 32-bit twos complement.
2 Real
IEU2CRAY: 32-bit, single-precision, IEEE floating point to 64-bit, single-precision, Cray
real numbers.
CRAY2IEU: 64-bit, single-precision, Cray real numbers to 32-bit, single-precision, IEEE
floating point.
3 Double
IEU2CRAY: 64-bit, double-precision, IEEE floating point to 128-bit, double-precision,
Cray floating point.
CRAY2IEU: 128-bit, double-precision, Cray floating point to 64-bit, double-precision,
IEEE floating point.
4 Complex
IEU2CRAY: 2 x 32-bit, single-precision, IEEE floating point to 2x64-bit, single-precision,
Cray floating point.
CRAY2IEU: 2 x 64-bit, single-precision, Cray floating point to 2 x 32-bit,
single-precision, IEEE floating point.
5 Logical
IEU2CRAY: 32-bit generic logical to 64-bit Cray logical; all nonzero values are converted
to Cray logical trues and all zero values are converted to Cray logical falses.
CRAY2IEU: 64-bit Cray logical to 32-bit generic logical; all nonzero Cray values are
converted to a value of 1, all zero Cray values remain unchanged.
6 Character
ASCII to ASCII; no translation.
7 Short integer
IEU2CRAY: 16-bit twos complement to 32-bit twos complement.
CRAY2IEU: 32-bit twos complement to 16-bit twos complement.
8 Special
IEU2CRAY: 64-bit, double-precision, IEEE floating point to 64-bit, single-precision, Cray
real numbers.
CRAY2IEU: 64-bit, single-precision, Cray real numbers to 64-bit, double-precision, IEEE
floating point.
num An integer giving the number of data items to convert.

004– 2165– 002 373

IEU2CRAY ( 3F ) IEU2CRAY ( 3F )

foreign IEU2CRAY: Variable or array of any noncharacter type containing the data to be converted.
CRAY2IEU: Variable or array of any noncharacter type to receive the converted data.
bitoff An integer giving the bit offset within foreign to begin the conversion. Bits are numbers from 0 to
63, beginning at the leftmost bit of foreign.
stride An integer.
IEU2CRAY: Optional memory increment for storing the converted values into the cray array.
CRAY2IEU: Optional memory increment for loading the Cray values to be converted.
For 2-word items (complex and double-precision), this is a stride of items, not of words.
The default value is 1.
cray IEU2CRAY: Variable or array of any noncharacter type to receive the converted values.
CRAY2IEU: Variable or array of any noncharacter type containing the values to be converted.
This variable should be of a type corresponding to the type argument.
craych Type Character.
IEU2CRAY: Optional character variable or array to receive the converted characters if type is 6
(character).
CRAY2IEU: Optional character variable or array containing the characters to be converted if type
is 6 (character).

NOTES
The IEU2CRAY and CRAY2IEU functions are little-endian versions of IEG2CRAY and CRAY2IEG. Most
generic IEEE systems use big-endian data representation and require the use of IEG2CRAY and CRAY2IEG.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

374 004– 2165– 002

INT6064 ( 3F ) INT6064 ( 3F )

NAME
INT6064 – Converts CDC 60-bit integers to Cray 64-bit integers

SYNOPSIS
CALL INT6064(src, idest, num)

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
INT6064 converts CDC 60-bit integer numbers to Cray 64-bit integer numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
src Variable or array of any noncharacter type and any length containing CDC 60-bit integers,
left-justified in a Cray 64-bit word.
idest Variable or array of type integer to receive the resultant Cray integer values. Each such integer
is left-justified and zero-filled.
num Number of CDC integers to convert. Specify an integer variable, expression, or constant.

NOTES
INT6460(3F) is the inverse of this routine.

004– 2165– 002 375

INT6460 ( 3F ) INT6460 ( 3F )

NAME
INT6460 – Converts Cray 64-bit integers to CDC 60-bit integers

SYNOPSIS
CALL INT6460(in, idest, num)

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
INT6460 converts Cray 64-bit integer numbers to CDC 60-bit integer numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
in Variable or array of any length and of type integer containing Cray integer numbers.
idest Variable or array of type integer to contain the converted values or CDC integer numbers. Each
such integer is left-justified and zero-filled.
num Number of Cray integers to convert. Specify an integer variable, expression, or constant.

NOTES
INT6064(3F) is the inverse of this routine.

376 004– 2165– 002

NVE2CRAY ( 3F ) NVE2CRAY ( 3F )

NAME
NVE2CRAY, CRAY2NVE – Converts NOS/VE data to Cray format and vice versa

SYNOPSIS
INTEGER NVE2CRAY
iret=NVE2CRAY(type, num, foreign, bitoff, cray[, strd[, craychar]])
INTEGER CRAY2NVE
iret=CRAY2NVE(type, num, foreign, bitoff, cray[, strd[, craychar]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
NVE2CRAY converts NOS/VE data to Cray format. It accepts as input a bit string starting at foreign at bit
bitoff and converts the data according to type, placing the converted data in cray.
CRAY2NVE converts Cray data to NOS/VE format. It accepts as input a bit string starting at the first
element in cray and converts the data according to type, placing the converted data in foreign at bit bitoff.
No precision is lost in either conversion.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
iret The returned function values are as follows:
=0 All values converted without error.
<0 Error. An error was detected in the input parameters.
type Type integer. The variable type code used by the libraries. The following table lists these
codes, shows the corresponding NOS/VE and Cray formats (and the formats’ mapping to one
another).

004– 2165– 002 377

NVE2CRAY ( 3F ) NVE2CRAY ( 3F )

Code NOS/VE Cray

1 INTEGER(64-bit) INTEGER(64-bit)
2 REAL(64-bit) REAL(64-bit)
3 DOUBLE(128-bit) DOUBLE(128-bit)
4 COMPLEX(2*64-bit) COMPLEX(2*64-bit)
5 LOGICAL(64-bit) LOGICAL(64-bit)
6 (no-op) CHARACTER (ASCII) CHAR (ASCII)(8-bit)
7 INTEGER(64-bit) INTEGER(24)(64-bit)

num Type integer variable, array, or constant. Number of data items to convert.
foreign NVE2CRAY: Variable or array of any noncharacter type and of any length containing the
NOS/VE format data to convert.
CRAY2NVE: Variable or array of any noncharacter type and of any length to receive the
converted NOS/VE data.
bitoff Type integer variable, expression, or constant in the range 0 ≤ bitoff ≤ 63.
NVE2CRAY: Bit number within foreign to begin the conversion.
CRAY2NVE: Bit number within foreign to place the converted data.
Bits are numbered from 0, beginning at leftmost bit of foreign. (Bit 0 is the sign bit.)
cray Variable or array of any noncharacter type or length containing the Cray format data,
word-aligned.
strd Type integer variable, expression, or constant.
NVE2CRAY: Memory increment for storing the conversion results in cray. If strd = 1, the items
are placed in contiguous memory locations in cray. If strd > 1, the items are placed in cray in
memory locations at intervals specified by strd. For example, if strd = 3, the input items are
stored in cray at locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are taken from foreign in a continuous bit stream.
CRAY2NVE: Memory increment for loading the Cray items to be converted. If strd = 1, the
items are taken from contiguous memory locations in cray. If strd > 1, the items are taken from
cray memory locations at intervals specified by strd. For example, if strd = 3, the items are
taken from cray locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are placed in foreign in a continuous bit stream.
For double-word items, this is a stride of items, not of words. Default stride for complex input
is 1. For character data, strd must equal 1.
Default value is 1.
This is an optional argument.

378 004– 2165– 002

NVE2CRAY ( 3F ) NVE2CRAY ( 3F )

craychar Type Character*N. Variable or array containing the Cray format data. This must be used in
place of cray when the variable type is character. If craychar is supplied, cray is ignored. This
is an optional argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

EXAMPLES
Example 1: The following code converts LENGTH NOS/VE REAL(64-bit) numbers in array ANVE to Cray
REAL(64-bit) numbers and places the results in array ACRAY.
INT EGER NVE2CRAY
IRE T=NVE2 CRAY(2 ,LE NGTH,A NVE,0,ACR AY)
IF(IRET.L T.0 ) GOT O 99 ! error

Example 2: The following code converts the LENGTH CRAY REAL(64-bit) numbers in array ACRAY from
the previous example back to NOS/VE REAL(64-bit) numbers and places the results in array ANVE2.
INT EGE R CRA Y2NVE
IRE T=C RAY 2NVE(2,LE NGT H,ANVE 2,0,ACRAY )
IF( IRET.L T.0) GOT O 99 ! err or

004– 2165– 002 379

RBN ( 3F ) RBN ( 3F )

NAME
RBN, RNB – Converts trailing blanks to nulls and vice versa

SYNOPSIS
INTEGER RBN, RNB, blanks, noblanks
noblanks=RBN(blanks)
blanks=RNB(noblanks)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
RBN converts trailing blanks to nulls; RNB converts trailing nulls to blanks. These routines convert 1 word
(up to 8 characters) for each invocation.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
blanks For RBN, the argument to be converted. For RNB, the argument after conversion.
noblanks For RBN, the argument after conversion. For RNB, the argument to be converted.

NOTES
Fortran programs using RBN or RNB must declare the function to be an integer.

380 004– 2165– 002

USCCTC ( 3F ) USCCTC ( 3F )

NAME
USCCTC, USCCTI – Converts EBCDIC character data to ASCII character data, and vice versa

SYNOPSIS
CALL USCCTC (src, isb, dest, num, npw [,val])
CALL USCCTI (src, dest, isb, num, npw [,val])

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libffio.so which is linked by default when compiling programs with
the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
USCCTC converts EBCDIC character data to ASCII character data; USCCTI converts ASCII character data
to EBCDIC character data. All non-printing characters are converted to blanks.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, the
arguments must be of type integer with KIND=8.
The following is a list of valid arguments for this routine.
src Variable or array of any type (except CHARACTER) containing the character data to be
converted.
isb An integer variable or constant containing the starting byte offset to begin the data conversion.
Bytes are numbered from left to right, with the leftmost byte as byte 1. The isb argument
applies to the src (USCCTC) or dest (USCCTI) argument.
dest Variable or array of any type (except CHARACTER) to receive the character data to be
converted.
num An integer variable or constant containing the number of characters to be converted.
npw An integer variable or constant containing the number of characters to be placed in each word of
dest (USCCTC) or obtained from each word of src (USCCTI). A positive value for npw (1 to 8)
indicates left-justification. A negative value (– 1 to – 8) indicates right-justification. For
USCCTC, left-justified output is also blank-filled. Note that npw values of 8 and – 8 are
equivalent.
val An optional integer or logical variable or constant which, if specified and nonzero (.TRUE.),
indicates that all lower case input is to be folded to upper case output. The default, if the
argument is not specified, is no case folding.

004– 2165– 002 381

USCCTC ( 3F ) USCCTC ( 3F )

NOTES
The following conditions must be met for any character data to be converted:
num ≥ 0
isb > 0
0 <  npw < 9
If num is not an even multiple of 8, the USCCTI routine will place the remaining converted characters in the
final word of dest while preserving the rest of the original contents of the word.

CAUTIONS
The same variable or array can be specified for src (input) and dest (output) if and only if isb is 1 and npw
is 8 (or – 8). The results of overlapping conversions using any other values for isb and npw are undefined.

EXAMPLES
The following Fortran code converts 800 characters from EBCDIC to ASCII. The ASCII characters are
placed one per word, right-justified.
INTEGE R EBC DIC(10 0)
INTEGE R ASC II (80 0)

CALL USCCTC (EBCDI C, 1, ASC II, 800 , –1, .FA LSE.)

382 004– 2165– 002

USDCTC ( 3F ) USDCTC ( 3F )

NAME
USDCTC – Converts IBM 64-bit floating-point numbers to Cray 64-bit, single-precision numbers

SYNOPSIS
CALL USDCTC(dpn, isb, dest, num[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
USDCTC converts IBM 64-bit floating-point numbers to Cray 64-bit, single-precision numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
dpn Variable or array of any noncharacter type and of any length containing IBM 64-bit
floating-point numbers to convert.
isb Byte number to begin the conversion. Specify an integer variable, expression, or constant.
Bytes are numbered from 1, beginning at the leftmost byte position of fpn or dpn.
dest Variable or array of type real to contain the converted values.
num Number of IBM 64-bit floating-point numbers to convert. Specify an integer variable,
expression, or constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
USDCTI(3F) is the inverse of this routine.
The conversion loses (truncates) 5 to 8 bits of precision from the coefficient. No rounding is performed.

004– 2165– 002 383

USDCTI ( 3F ) USDCTI ( 3F )

NAME
USDCTI – Converts Cray 64-bit single-precision, floating-point numbers to IBM 64-bit double-precision
numbers

SYNOPSIS
CALL USDCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
USDCTI converts Cray Research 64-bit single-precision, real numbers to IBM 64-bit double-precision,
floating-point numbers. USDCTC(3F) is the inverse of this routine.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and type real, containing Cray Research 64-bit single-precision, real
numbers to convert.
dest Variable or array of type real to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable, expression,
or constant. Bytes are numbered from 1, beginning at the leftmost byte position of dest.
num Number of Cray Research real numbers to convert. Integer variable, expression, or constant.
ier Overflow indicator of type integer. The value is 0 if all Cray Research values convert to IBM values
without overflow; the value is nonzero if one or more Cray Research values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument specified
as an integer variable, expression, or constant. The default value is 1.

Neither rounding nor truncation is required for the result. Precision is extended by introducing 8 more bits
into the rightmost byte of the fraction from the Cray Research number being converted. Numbers that
produce an underflow when converted to IBM format are converted to 64 binary 0’s. Numbers that produce
an overflow when converted to IBM format are converted to the largest IBM floating-point representation
with the sign bit set if negative. An error parameter returns nonzero to indicate that one or more numbers
converted produced an overflow. No such indication is given for underflow.

384 004– 2165– 002

USICTC ( 3F ) USICTC ( 3F )

NAME
USICTC, USICTI – Converts between IBM INTEGER*2/INTEGER*4 and Cray 64-bit integer numbers

SYNOPSIS
CALL USICTC(in, isb, dest, num, len[, inc])
CALL USICTI(in, dest, isb, num, len, ier[, inc])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
USICTC converts IBM INTEGER*2 and INTEGER*4 numbers to Cray 64-bit integer numbers.
USICTI converts Cray 64-bit integer numbers to IBM INTEGER*2 or INTEGER*4 numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
in Variable or array of any noncharacter type and of any length containing IBM INTEGER*2 or
INTEGER*4 numbers or Cray 64-bit integers to convert.
isb Byte number at which to begin the conversion or at which to begin storing the converted results.
Specify an integer variable, expression, or constant. Bytes are numbered from 1, beginning at
the leftmost byte position of in (dest in USICTI).
dest Variable or array of type integer to contain the converted values.
num Number of IBM numbers or Cray integers to convert. Specify an integer variable, expression, or
constant.
len Size of the IBM numbers to convert or of IBM result numbers. These values must be 2 or 4. A
value of 2 indicates that input or output integers are INTEGER*2 (16-bit). A value of 4
indicates that input or output integers are INTEGER*4 (32-bit). Specify an integer variable,
expression, or constant.
inc Memory increment for storing the conversion results in dest or for fetching the number to be
converted. This is an optional argument specified as an integer variable, expression, or constant.
The default value is 1.
ier Overflow indicator of type integer. The value is 0 if all Cray values converted to IBM values
without overflow. The value is not 0 if one or more Cray values overflowed in the conversion.

004– 2165– 002 385

USICTC ( 3F ) USICTC ( 3F )

Numbers that produce an overflow when converted to IBM format are converted to the largest IBM integer
representation, with the sign bit set if negative. An error parameter returns nonzero to indicate that one or
more of the numbers converted produced an overflow.

386 004– 2165– 002

USICTP ( 3F ) USICTP ( 3F )

NAME
USICTP – Converts a Cray 64-bit integer to an IBM packed-decimal field

SYNOPSIS
CALL USICTP(ian, dest, isb, num)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
USICTP converts a Cray 64-bit integer to an IBM packed-decimal field.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ian Cray integer to be converted to an IBM packed-decimal field. Specify an integer variable,
expression, or constant.
dest Variable or array of any noncharacter type and of any length to contain the packed field
generated.
isb Byte number within dest specifying the beginning location for storage. Specify an integer
variable, expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte
position of dest.
num Number of bytes to be stored. Specify an integer variable, expression, or constant.
If the input value contains more digits than can be stored in num bytes, the leftmost digits are not converted.

NOTES
USPCTC(3F) is the inverse of this routine.

004– 2165– 002 387

USLCTC ( 3F ) USLCTC ( 3F )

NAME
USLCTC, USLCTI – Converts between IBM LOGICAL*1/LOGICAL*4 and Cray 64-bit logical values

SYNOPSIS
CALL USLCTC(src, isb, dest, num, len[, inc])
CALL USLCTI(src, dest, isb, num, len[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
USLCTC converts IBM LOGICAL*1 and LOGICAL*4 values to Cray 64-bit logical values.
USLCTI converts Cray logical values to IBM LOGICAL*1 or LOGICAL*4 values.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
src Variable or array of any noncharacter type (type logical in USLCTI) and any length containing
IBM LOGICAL*1, LOGICAL*4, or Cray logical values to convert.
isb Byte number to begin the conversion or, in USLCTI, specifying the beginning location for
storage. Specify an integer variable, expression, or constant. Bytes are numbered from 1,
beginning at the leftmost byte position of src.
dest Variable or array of any noncharacter type and of any length to contain the converted values.
num Number of IBM or Cray logical values to be converted. Specify an integer variable, expression,
or constant.
len Size of the IBM logical values to convert or of the logical result value. These values must be 1
or 4. A value of 1 indicates that input or output logical values are LOGICAL*1 (8-bit). A
value of 4 indicates that input or output logical values are LOGICAL*4 (32-bit). Specify an
integer variable, expression, or constant.
inc Memory increment for storing the conversion results in dest or for fetching the number to be
converted. This is an optional argument specified as an integer variable, expression, or constant.
The default value is 1.
All arguments must be entered in the same order in which they appear in the SYNOPSIS section.

388 004– 2165– 002

USPCTC ( 3F ) USPCTC ( 3F )

NAME
USPCTC – Converts a specified number of bytes of IBM packed-decimal field to 64-bit integer field

SYNOPSIS
CALL USPCTC(src, isb, num, ian)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
USPCTC converts a specified number of bytes of IBM packed-decimal field to 64-bit integer field.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
src Variable or array of any noncharacter type and of any length containing a valid IBM
packed-decimal field.
isb Byte number to begin the conversion. Specify an integer variable, expression, or constant.
Bytes are numbered from 1, beginning at the leftmost byte position of src.
num Number of bytes to convert. Specify an integer variable, expression, or constant.
ian Returned integer result.
The input field must be a valid packed-decimal number less than 16 bytes long. Only the rightmost 15 digits
are converted.

NOTES
USICTP(3F) is the inverse of this routine.

004– 2165– 002 389

USSCTC ( 3F ) USSCTC ( 3F )

NAME
USSCTC – Converts IBM 32-bit floating-point numbers to Cray 64-bit single-precision numbers

SYNOPSIS
CALL USSCTC(fpn, isb, dest, num[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
USSCTC converts IBM real numbers to Cray real numbers. The result does not require rounding or
truncation.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any noncharacter type and of any length containing IBM 32-bit
floating-point numbers to convert.
isb Byte number to begin the conversion. Specify an integer variable, expression, or constant.
Bytes are numbered from 1, beginning at the leftmost byte position of fpn.
dest Variable or array of type real to contain the converted values.
num Number of IBM 32-bit floating-point numbers to convert. Specify an integer variable,
expression, or constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
USSCTI(3F) is the inverse of this routine.

390 004– 2165– 002

USSCTI ( 3F ) USSCTI ( 3F )

NAME
USSCTI – Converts Cray 64-bit single-precision, floating-point numbers to IBM 32-bit single-precision
numbers

SYNOPSIS
CALL USSCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
USSCTI converts Cray 64-bit single-precision, floating-point numbers to IBM 32-bit single-precision,
floating-point numbers. Numbers that produce an underflow when converted to IBM format are converted to
32 binary 0’s. Numbers that produce an overflow when converted to IBM format are converted to the
largest IBM floating-point representation, with the sign bit set if negative.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and type real, containing Cray 64-bit single-precision,
floating-point numbers to convert.
dest Variable or array of type real to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray floating-point numbers to convert. Specify an integer variable, expression, or
constant.
ier Overflow indicator of type integer. Value is 0 if all Cray values convert to IBM values without
overflow. Value is nonzero if one or more Cray values overflowed in the conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.
An error argument returns nonzero to indicate that one or more numbers converted produced an overflow.
No such indication is given for underflow.

004– 2165– 002 391

USSCTI ( 3F ) USSCTI ( 3F )

NOTES
USSCTC(3F) is the inverse of this routine. This routine truncates, rather than rounds, the result.

392 004– 2165– 002

VAX2CRAY ( 3F ) VAX2CRAY ( 3F )

NAME
VAX2CRAY, CRAY2VAX – Converts VAX data to Cray format and vice versa

SYNOPSIS
INTEGER VAX2CRAY
iret=VAX2CRAY(type, num, foreign, bitoff, cray[, strd[, craychar]])
INTEGER CRAY2VAX
iret=CRAY2VAX(type, num, foreign, bitoff, cray[, strd[, craychar]])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VAX2CRAY converts VAX data to Cray format. It accepts as input a bit string starting at foreign at bit bitoff
and converts the data according to type, placing the converted data in cray.
CRAY2VAX converts Cray data to VAX format. It accepts as input a bit string starting at cray and converts
the data according to type, placing the converted data in foreign at bit bitoff.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
iret The returned function values are as follows:
=0 All values converted without error.
<0 Error. An error was detected in the input parameters.
type Type integer. The variable type code used by the libraries. The following table lists these
codes, shows the corresponding VAX and Cray formats (and the formats’ mapping to one
another), and lists the rounding versus truncation strategy of the result.

004– 2165– 002 393

VAX2CRAY ( 3F ) VAX2CRAY ( 3F )

Code VAX Cray VAX2CRAY CRAY2VAX

1 INTEGER*4 INTEGER(64-bit)
2 REAL*4 REAL(64-bit) Neither Rounding
3 REAL*8 DOUBLE(128-bit) Neither Rounding
4 COMPLEX*4 COMPLEX(2*64-bit) Neither Rounding
5 LOGICAL*4 LOGICAL(64-bit)
6 (no-op) CHARACTER (ASCII) CHAR (ASCII)(8-bit)
7 INTEGER*2 INTEGER(24)(64-bit)

num Type integer variable, array, or constant. Number of data items to convert.
foreign VAX2CRAY: Variable or array of any noncharacter type and of any length containing the VAX
format data to convert.
CRAY2VAX: Variable or array of any noncharacter type and of any length to receive the
converted VAX data.
bitoff Type integer variable, expression, or constant in the range 0 ≤ bitoff ≤ 63.
VAX2CRAY: Bit number within foreign to begin the conversion.
CRAY2VAX: Bit number within foreign to place the converted data.
Bits are numbered from 0, beginning at leftmost bit of foreign. (Bit 0 is the sign bit.)
cray Variable or array of any noncharacter type and of any length containing the Cray format data,
word-aligned.
strd Type integer variable, expression, or constant.
VAX2CRAY: Memory increment for storing the conversion results in cray. If strd = 1, the items
are placed in contiguous memory locations in cray. If strd > 1, the items are placed in cray in
memory locations at intervals specified by strd. For example, if strd = 3, the input items are
stored in cray at locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are taken from foreign in a continuous bit stream.
CRAY2VAX: Memory increment for loading the Cray items to be converted. If strd = 1, the
items are taken from contiguous memory locations in cray. If strd > 1, the items are taken from
cray memory locations at intervals specified by strd. For example, if strd = 3, the items are
taken from cray locations cray(1), cray(4), cray(7), cray(10), and so on. Regardless of this
argument, the input bits are placed in foreign in a continuous bit stream.
For double-word items, this is a stride of items, not of words. Default stride for complex input
is 1. For character data, strd must equal 1.
Default value is 1.
This is an optional argument.

394 004– 2165– 002

VAX2CRAY ( 3F ) VAX2CRAY ( 3F )

craychar Type Character*n. Variable or array containing the Cray format data. Must be used instead of
cray when the variable type is character. If craychar is supplied, cray is ignored. This is an
optional argument.

CAUTION
The foreign and cray variables should not be associated (aliased to each other).

EXAMPLES
Example 1: The following code converts LENGTH VAX REAL*4 numbers in array AVAX to Cray
REAL(64-bit) numbers and places the results in array ACRAY.
INT EGER VAX2CRAY
IRE T=VAX2 CRAY(2 ,LE NGTH,A VAX,0,ACR AY)
IF(IRET.L T.0 ) GOT O 99 ! error

Example 2: The following code converts the LENGTH CRAY REAL(64-bit) numbers in array ACRAY from
the previous example back to VAX REAL*4 numbers and places the results in array AVAX2.
INTEGE R CRA Y2VAX
IRE T=CRAY 2VAX(2 ,LE NGTH,A VAX2,0,AC RAY )
IF(IRET.L T.0 ) GOT O 99 ! error

004– 2165– 002 395

VAX2MIPS ( 3F ) VAX2MIPS ( 3F )

NAME
VAX2MIPS, MIPS2VAX – Converts generic IEEE data to MIPS IEEE data and vice versa

SYNOPSIS
INTEGER VAX2MIPS, MIPS2VAX
ierr = VAX2MIPS(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])
ierr = MIPS2VAX(type, num, foreign, bitoff, native, stride, natlen, forlen[,nativech])

IMPLEMENTATION
IRIX systems

DESCRIPTION
VAX2MIPS converts VAX data types (abbreviated as "VAX" in the following text) to data for systems that
use MIPS data types (abbreviated as "MIPS" in the following text).
MIPS2VAX converts MIPS data types to VAX data types.
When using the MIPSpro 7 Fortran 90 compiler on IRIX systems, all arguments must be of default kind
unless documented otherwise. On IRIX systems, the default kind is KIND=4.
The following is a list of valid parameters for this routine.
type An integer giving the data type code, as follows.
Code Description
1 Typeless (no translation; natlen and forlen must be equal and must be 8-, 16-, 32-, 64-,
128-, or 256-bits.)
2 Integer
VAX: 64-, 32-, 16, or 8-bit twos complement
MIPS: 64-, 32-, 16, or 8-bit twos complement
3 Real
VAX: 32- (F), 64- (D), or 128-bit (G) VAX floating-point
MIPS: 32-, 64-, or 128-bit MIPS floating-point
4 Complex
VAX: 2 x 32-, 64-, or 128-bit Ifloating-point
MIPS: 2 x 32-, 64-, or 128-bit MIPSfloating-point
5 Logical
VAX: 64-, 32-, 16-, or 8-bit zero/nonzero logical
MIPS: 64-, 32-, 16-, or 8-bit zero/nonzero logical
6 Character
ASCII to ASCII; no translation.

396 004– 2165– 002

VAX2MIPS ( 3F ) VAX2MIPS ( 3F )

The natlen and forlen parameters select the size of the data.
num Number of data items to convert. Type integer variable, expression, or constant.
foreign Variable or array of any noncharacter type or length to contain data which is not native to the
current system.
bitoff Integer variable, expression, or constant giving the bit offset within the foreign data variable or
array to begin the conversion. bitoff must be at least 0 and no more than 63.
native Variable or array of any noncharacter type or length to contain data which is native to the current
system. This variable or array should be of a type that corresponds to type. If type=6, use a
dummy integer variable and the nativech parameter (see description of nativech).
stride Integer variable or constant giving the memory increment for loading or storing data to the native
array. For two and four-word items (complex and double-precision), this is a stride of items, not
of words. For typeless, stride is always in words.
This parameter is ignored for CHARACTER (type = 6). Data in the foreign array is loaded or
stored in a continuous bit stream regardless of this parameter.
natlen Native storage length of an item, in bits. For COMPLEX data, natlen counts the total size of the
real and imaginary component.
forlen Foreign storage length of an item, in bits. For COMPLEX data, forlen counts the total size of the
real and imaginary components.
nativech Optional character parameter specifying native target variable if it is of type character (type = 6).
This parameter is ignored if type is not character.

CAUTION
The foreign and native variables should not be associated (aliased to each other).

RETURN VALUES
The returned function values are as follows:
<0 Parameter error; no translation performed.
-1 Parameter error; too few arguments or nativech not specified with type = 6. This error is not returned
on IRIX systems.
-2 Parameter error; invalid type.
-3 Parameter error; invalid num.
-4 Parameter error; invalid bitoff.
-5 Parameter error; invalid natlen.
-6 Parameter error; invalid forlen.
-7 Unable to malloc() memory for translation.

004– 2165– 002 397

VAX2MIPS ( 3F ) VAX2MIPS ( 3F )

-8 Combination of natlen and forlen is invalid.

-9 native must be 64-bit word-aligned.
-10 foreign must be 64-bit word-aligned.
0 Translation complete; no errors.
>0 Translation complete; return value is the number of integer or real values that completely overflowed
during conversion. Overflows and NaNs which exist before conversion are not included.

398 004– 2165– 002

VXDCTC ( 3F ) VXDCTC ( 3F )

NAME
VXDCTC – Converts VAX 64-bit, D-format numbers to Cray 64-bit single-precision numbers

SYNOPSIS
CALL VXDCTC(dpn, isb, dest, num[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
dpn Variable or array of any noncharacter type and of any length containing VAX D-format numbers
to convert.
isb Byte number within dpn at which to begin the conversion. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn.
dest Variable or array of type real to contain the converted values.
num Number of VAX D-format numbers to convert. Specify an integer variable, expression, or
constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
VXDCTI(3F) is the inverse of this routine. This routine truncates, rather than rounds, the result.

004– 2165– 002 399

VXDCTI ( 3F ) VXDCTI ( 3F )

NAME
VXDCTI – Converts Cray 64-bit single-precision, floating-point (real) numbers to VAX D-format, 64-bit,
double-precision, floating-point numbers

SYNOPSIS
CALL VXDCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and type real containing Cray 64-bit single-precision, real
numbers to convert.
dest Variable or array of type real to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray real numbers to convert. Specify an integer variable, expression, or constant.
ier Overflow indicator of type integer. The value is 0 if all Cray values convert to VAX values
without overflow. The value is nonzero if one or more Cray values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant.
Numbers that produce an underflow when converted to VAX format are converted to 64 binary 0’s.
Numbers that are in overflow on the Cray system are converted to a "reserved" floating-point representation,
with the sign bit set if negative. Numbers that are valid on the Cray system, but overflow on the VAX
system, are converted to the most positive possible number or most negative possible number, depending on
the sign.
An error argument returns nonzero to indicate that one or more numbers converted produced an overflow.
(Deferred implementation. At present, you must supply the argument, which is always returned as 0.) No
such indication is given for underflow.

400 004– 2165– 002

VXDCTI ( 3F ) VXDCTI ( 3F )

NOTES
VXDCTC(3F) is the inverse of this routine. This routine rounds, rather than truncates, the result.

004– 2165– 002 401

VXGCTC ( 3F ) VXGCTC ( 3F )

NAME
VXGCTC – Converts VAX 64-bit G-format numbers to Cray 64-bit single-precision numbers

SYNOPSIS
CALL VXGCTC(dpn, isb, dest, num[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXGCTC converts VAX 64-bit G-format numbers to Cray 64-bit single-precision numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
dpn Variable or array of any noncharacter type and of any length containing VAX G-format numbers
to convert.
isb Byte number within dpn at which to begin the conversion. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn.
dest Variable or array of type real to contain the converted values.
num Number of VAX G-format numbers to convert. Specify an integer variable, expression, or
constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
VXGCTI(3F) is the inverse of this routine. This routine truncates, rather than rounds, the result.

402 004– 2165– 002

VXGCTI ( 3F ) VXGCTI ( 3F )

NAME
VXGCTI – Converts Cray 64-bit single-precision, floating-point (real) numbers to VAX G-format, 64-bit,
single-precision, floating-point numbers

SYNOPSIS
CALL VXGCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXGCTI converts Cray 64-bit single-precision real numbers to VAX G-format single-precision, floating-point
numbers. The result fits entirely in the target data structure, so neither rounding nor truncation is required.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and type real, containing Cray 64-bit single-precision,
floating-point numbers to convert.
dest Variable or array of type real to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray real numbers to convert. Specify an integer variable, expression, or constant.
ier Overflow indicator of type integer. The value is 0 if all Cray values convert to VAX values
without overflow. The value is nonzero if one or more Cray values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.
Numbers that produce an underflow when converted to VAX format are converted to 64 binary 0’s.
Numbers that are in overflow on the UNICOS system are converted to a "reserved" floating-point
representation, with the sign bit set if negative. Numbers that are valid on the UNICOS system, but
overflow on the VAX system, are converted to the most positive possible number or the most negative
possible number, depending on the sign.

004– 2165– 002 403

VXGCTI ( 3F ) VXGCTI ( 3F )

An error argument returns nonzero to indicate that one or more numbers converted produced an overflow.
(Deferred implementation. At present, you must supply the parameter, which is always returned as 0.) No
such indication is given for underflow.

NOTES
VXGCTC(3F) is the inverse of this routine.

404 004– 2165– 002

VXICTC ( 3F ) VXICTC ( 3F )

NAME
VXICTC – Converts VAX INTEGER*2 (16 bits) or INTEGER*4 (32 bits) to Cray 64-bit integers

SYNOPSIS
CALL VXICTC(in, isb, dest, num, len[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXICTC converts VAX INTEGER*2 (16 bits) or INTEGER*4 (32 bits) to Cray 64-bit integers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
in Variable or array of any noncharacter type and of any length containing VAX 16-bit or 32-bit
integers.
isb Byte number at which to begin the conversion. Specify an integer variable, expression, or
constant. Bytes are numbered from 1, beginning at the leftmost byte position of in.
dest Variable or array of type integer to contain the converted values.
num Number of VAX integers to convert. Specify an integer variable, expression, or constant.
len Size of the VAX numbers to convert. This value must be 2 or 4. A value of 2 indicates that
input integers are 16-bit integers. A value of 4 indicates that input integers are 32-bit integers.
Specify an integer variable, expression, or constant.
inc Memory increment for storing conversion results in dest. This is an optional argument specified
as an integer variable, expression, or constant. The default value is 1.

NOTES
Instead of using the VXICTC routine, use the newer VAX2CRAY routine. Select a type of 7 for an
INTEGER*2 conversion and 1 for an INTEGER*4 conversion.
VXICTI(3F) is the inverse of this routine.

SEE ALSO
VAX2CRAY(3F)

004– 2165– 002 405

VXICTI ( 3F ) VXICTI ( 3F )

NAME
VXICTI – Converts Cray 64-bit integers to VAX INTEGER*2 (16 bit) or INTEGER*4 (32 bit) numbers

SYNOPSIS
CALL VXICTI(in, dest, isb, num, len, ier[, inc])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
VXICTI converts Cray 64-bit integers to VAX INTEGER*2 (16-bit) or INTEGER*4 (32-bit) numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
in Variable or array of any length and type integer, containing Cray integers to convert.
dest Variable or array of type integer to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray integers to convert. Specify an integer variable, expression, or constant.
len Size of the VAX result numbers. This value must be 2 or 4. A value of 2 indicates that output
integers are INTEGER*2 (16-bit). A value of 4 indicates that output integers are INTEGER*4
(32-bit). Specify an integer variable, expression, or constant.
ier Overflow indicator of type integer. The value is 0 if all Cray values are converted to VAX
values without overflow. The value is nonzero if one or more Cray values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.
Numbers that produce an overflow when converted to VAX format are converted to the largest VAX integer
representation, with the sign bit set if negative.
An error argument returns nonzero to indicate that one or more numbers converted produced an overflow.
(Deferred implementation. At present, you must supply the parameter, which is always returned as 0.) No
such indication is given for underflow.

406 004– 2165– 002

VXICTI ( 3F ) VXICTI ( 3F )

NOTES
Instead of using the VXICTI routine, use the newer CRAY2VAX routine, which is documented on the
VAX2CRAY man page. Select a type of 7 for an INTEGER*2 conversion and 1 for an INTEGER*4
conversion.
VXICTC(3F) is the inverse of this routine.

SEE ALSO
VAX2CRAY(3F)

004– 2165– 002 407

VXLCTC ( 3F ) VXLCTC ( 3F )

NAME
VXLCTC – Converts VAX 32-bit logical numbers to Cray 64-bit logical numbers

SYNOPSIS
CALL VXLCTC(src, isb, dest, num, len[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXLCTC converts VAX 32-bit logical values to Cray 64-bit logical values.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
src Variable or array of any noncharacter type and of any length containing VAX logical values to
convert.
isb Byte number at which to begin the conversion. Specify an integer variable, expression, or
constant. Bytes are numbered from 1, beginning at the leftmost byte position of src.
dest Variable or array of type logical to contain the converted values.
num Number of VAX logical values to be converted. Specify an integer variable, expression, or
constant.
len Size of the VAX logical values to convert. At present, this argument must be set to 4,
indicating that 32-bit logical values are to be converted. Specify an integer variable, expression,
or constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
Instead of using the VXLCTC routine, use the newer VAX2CRAY routine. Select a type of 5. VXLCTI(3F)
is the inverse of this routine.

SEE ALSO
VAX2CRAY(3F)

408 004– 2165– 002

VXLCTI ( 3F ) VXLCTI ( 3F )

NAME
VXLCTI – Converts Cray 64-bit logical numbers to VAX 32-bit logical numbers

SYNOPSIS
CALL VXLCTI(in, dest, isb, num, len, ier[,inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXLCTI converts Cray 64-bit logical numbers to VAX 32-bit logical numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
in Variable or array of any length and type logical, containing Cray logical numbers to convert.
dest Variable or array of type integer to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray integers to convert. Specify an integer variable, expression, or constant.
len Size of the VAX result. You must specify this as 4 (32-bit logical numbers).
ier A 0 is always returned (stored into) for this parameter. The parameter is required for
consistency with similar subroutines.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
Instead of using the VXLCTI routine, use the newer CRAY2VAX routine, which is documented on the
VAX2CRAY man page. Select a type of 5.
VXLCTC(3F) is the inverse of this routine.

SEE ALSO
VAX2CRAY(3F)

004– 2165– 002 409

VXSCTC ( 3F ) VXSCTC ( 3F )

NAME
VXSCTC – Converts VAX 32-bit floating-point numbers to Cray 64-bit single-precision real numbers

SYNOPSIS
CALL VXSCTC(fpn, isb, dest, num [,inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXSCTC converts VAX 32-bit floating-point numbers to Cray 64-bit single-precision real numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any noncharacter type containing VAX 32-bit floating-point numbers to
convert.
isb Byte number at which to begin the conversion. Specify an integer variable, expression, or
constant. Bytes are numbered from 1, beginning at the leftmost byte position of fpn.
dest Variable or array of type real to contain the converted values.
num Number of VAX floating-point numbers to convert. Specify an integer variable, expression, or
constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

NOTES
Instead of using the VXSCTC routine, use the newer VAX2CRAY routine. Select a type of 2. VXSCTI(3F)
is the inverse of this routine.
The resulting data structure is large enough to contain the whole number, so neither rounding nor truncation
is required.

SEE ALSO
VAX2CRAY(3F)

410 004– 2165– 002

VXSCTI ( 3F ) VXSCTI ( 3F )

NAME
VXSCTI – Converts Cray 64-bit single-precision, floating-point (real) numbers to VAX F format, 32-bit,
single-precision, floating-point numbers

SYNOPSIS
CALL VXSCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXSCTI converts Cray 64-bit single-precision, floating point (real) to VAX F format, 32-bit,
single-precision, floating point.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and type real, containing Cray 64-bit real numbers to convert.
dest Variable or array of type real to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray real numbers to convert. Specify an integer variable, expression, or constant.
ier Overflow indicator of type integer. The value is 0 if all Cray values convert to VAX values
without overflow. The value is nonzero if one or more Cray values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.
Numbers that produce an underflow when converted to VAX format are converted to 32 binary zeros.
Numbers that are in overflow on the Cray system are converted to a "reserved" floating-point representation,
with the sign bit set if negative. Numbers that are valid on the Cray system, but overflow on the VAX
system, are converted to the most positive possible number or the most negative possible number, depending
on the sign.
An error argument returns nonzero to indicate that one or more numbers converted produced an overflow
(Deferred implementation. At present you must supply the argument, which is always returned as 0.) No
such indication is given for underflow.

004– 2165– 002 411

VXSCTI ( 3F ) VXSCTI ( 3F )

NOTES
Instead of using the VXSCTI routine, use the newer CRAY2VAX routine, which is documented on the
VAX2CRAY man page. Select a type of 2.
VXSCTC(3F) is the inverse of this routine.
This routine rounds, rather than truncates, the result.

SEE ALSO
VAX2CRAY(3F)

412 004– 2165– 002

VXZCTC ( 3F ) VXZCTC ( 3F )

NAME
VXZCTC – Converts VAX 64-bit complex numbers to Cray 128-bit complex numbers

SYNOPSIS
CALL VXZCTC(dpn, isb, dest, num[, inc])

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
VXZCTC converts VAX 64-bit complex numbers to Cray 128-bit complex numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
dpn Variable or array of any noncharacter type and of any length containing complex numbers to
convert.
isb Byte number within dpn at which to begin the conversion. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn.
dest Variable or array of type complex to contain the converted values.
num Number of complex numbers to convert. Specify an integer variable, expression, or constant.
inc Memory increment for storing the conversion results in dest. This is an optional argument
specified as an integer variable, expression, or constant. Default value is 1.

NOTES
Instead of using the VXZCTC routine, use the newer VAX2CRAY routine. Select a type of 4. VXZCTI(3F)
is the inverse of this routine.
This routine truncates rather than rounds the result.

SEE ALSO
VAX2CRAY(3F)

004– 2165– 002 413

VXZCTI ( 3F ) VXZCTI ( 3F )

NAME
VXZCTI – Converts Cray 128-bit complex numbers to VAX 64-bit complex numbers

SYNOPSIS
CALL VXZCTI(fpn, dest, isb, num, ier[, inc])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
VXZCTI converts Cray 128-bit complex numbers to VAX 64-bit complex numbers.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
fpn Variable or array of any length and of type complex, containing Cray complex numbers to
convert.
dest Variable or array of any noncharacter type to contain the converted values.
isb Byte number at which to begin storing the converted results. Specify an integer variable,
expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position of
dest.
num Number of Cray complex numbers to convert. Specify an integer variable, expression, or
constant.
ier Overflow indicator of type integer. The value is 0 if all Cray values convert to VAX values
without overflow. The value is nonzero if one or more Cray values overflowed in the
conversion.
inc Memory increment for fetching the number to be converted. This is an optional argument
specified as an integer variable, expression, or constant. The default value is 1.

Numbers that produce an underflow when converted to VAX format are converted to two words of 32 binary
zeros. Numbers that are in overflow on the Cray system are converted to a "reserved" floating-point
representation, with the sign bit set if negative. Numbers that are valid on the Cray system but overflow on
the VAX system are converted to the most positive possible number or the most negative possible number,
depending on the sign.
An error argument returns nonzero to indicate that one or more numbers converted produced an overflow.
(Deferred implementation. At present, you must supply the argument, which is always returned as 0.) No
such indication is given for underflow.

414 004– 2165– 002

VXZCTI ( 3F ) VXZCTI ( 3F )

NOTES
Instead of using the VXZCTI routine, use the newer CRAY2VAX routine, which is documented on the
VAX2CRAY(3F) man page. Select a type of 4.
VXZCTC(3F) is the inverse of this routine.
This routine rounds rather than truncates the result.

SEE ALSO
VAX2CRAY(3F)

004– 2165– 002 415

416 004– 2165– 002
INTRO_INTERFACE ( 3F ) INTRO_INTERFACE ( 3F )

NAME
INTRO_INTERFACE – Introduction to system interface routines

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION
System interface routines are grouped into the following categories:
• Job control routines
• Floating-point interrupt routines
• Special-purpose interface routines
• Miscellaneous routines

JOB CONTROL ROUTINES

Job control routines perform functions relating to program termination, either causing a termination or
instructing the system on how to handle a termination. Control is not returned.
The ABORT routine requests abort with traceback. The EXIT routine exits from a Fortran program. The
ERREXIT routine requests an abort.

FLOATING-POINT INTERRUPT ROUTINES

Floating-point interrupt routines allow you to test, set, and clear the Floating-point Interrupt Mode flag.
Subroutine linkage is call-by-address.
The CLEARFI routine temporarily prohibits floating-point interrupts; the SETFI routine temporarily permits
floating-point interrupts; the SENSEFI routine determines if floating-point interrupts are permitted or
prohibited. These routines are documented on the CLEARFI man page. These routines are not available on
Cray T90 systems that support IEEE arithmetic.

SPECIAL-PURPOSE INTERFACE ROUTINES

The following routines are used for special-purpose interfaces:
• GETCWD: returns the current working directory.
• GETHOST: gets name of host mainframe.
• GETARG: returns a command-line argument (documented on the IARGC man page).
• GETOARG: gets command-line arguments.
• GETOARGC: gets command-line arguments.
• GETVARG: gets command-line arguments, allowing blanks or commas as delimiters.

004– 2165– 002 417

INTRO_INTERFACE ( 3F ) INTRO_INTERFACE ( 3F )

• GETVARGC: gets command-line arguments, allowing blanks or commas as delimeters.

• IARGC: returns the number of command-line arguments.
• ISHELL: executes a shell command.
• NLIMIT: sets or obtains resource limit values.
• REMARK: enters a message (preceded by a message prefix) in the stderr file.
• REMARK2: enters a message in the stderr file.
• REMARKF: enters a formatted message in the stderr file.
• UNAME: gets name of current operating system.

MISCELLANEOUS ROUTINES
The CLEARBT routine disables bidirectional memory transfers.
The SETBT routine enables bidirectional memory transfers.
The GETHOST routine returns name of host mainframe.
The SAMEFILE routine checks to see if two files have the same inode number.
The SENSEBT routine checks if bidirectional memory transfer is enabled or disabled.

418 004– 2165– 002

ABORT ( 3F ) ABORT ( 3F )

NAME
ABORT – Requests abort with traceback

SYNOPSIS
CALL ABORT[(msg)]

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
ABORT requests an abort with traceback and provides an optional message written to the stderr file and
creates a core dump.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
msg Optional message of type character for stderr file.

004– 2165– 002 419

CLEARBT ( 3F ) CLEARBT ( 3F )

NAME
CLEARBT, SETBT – Temporarily disables or enables bidirectional memory transfers

SYNOPSIS
CALL CLEARBT
CALL SETBT

IMPLEMENTATION
UNICOS systems

DESCRIPTION
CLEARBT temporarily disables bidirectional memory transfers and SETBT temporarily enables bidirectional
memory transfers.
These routines are local to a current process (such as a program). The system restores the most recent mode
setting at the start of the next process. No arguments are required or returned.

420 004– 2165– 002

CLEARFI ( 3F ) CLEARFI ( 3F )

NAME
CLEARFI, SENSEFI, SETFI – Modifies floating-point interrupt status

SYNOPSIS
INTEGER modefi
CALL CLEARFI
CALL SENSEFI(modefi)
CALL SETFI

IMPLEMENTATION
UNICOS systems (except Cray T90 systems that support IEEE arithmetic)

DESCRIPTION
These Fortran-callable routines let you modify the floating-point interrupt status.
SETFI sets the interrupt bit.
CLEARFI clears the interrupt bit.
SENSEFI returns the current interrupt status in modefi.
modefi Returns a 1 if floating-point interrupts are enabled; if floating-point interrupts are disabled, it
returns a 0.

NOTES
Under the UNICOS operating system, CLEARFI and SETFI are local to a current process. The system
restores the most recent mode setting at the start of the next process. No arguments or parameters are
required.

004– 2165– 002 421

ERREXIT ( 3F ) ERREXIT ( 3F )

NAME
ERREXIT – Requests abort

SYNOPSIS
CALL ERREXIT

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
ERREXIT calls the abort function and provides an error exit from a Fortran program.

422 004– 2165– 002

EXIT ( 3F ) EXIT ( 3F )

NAME
EXIT – Exits from a Fortran program

SYNOPSIS
UNICOS and UNICOS/mk systems:
CALL EXIT[(istat)]
IRIX systems:
CALL EXIT(istat)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, the information on this man page is valid only for programs compiled with the MIPSpro 7
Fortran 90 compiler.
EXIT ends the execution of a Fortran program.
istat EXIT ends the execution of a Fortran program. On UNICOS/mk systems, it terminates
execution on the local processing element (PE). The integer status istat is optional on UNICOS
systems and is required on IRIX systems. The default exit status is 0.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.

NOTES
UNICOS and UNICOS/mk only: The single parameter to EXIT is optional. Because EXIT is
predeclared, any explicit call to it can optionally include a parameter. However, if EXIT is passed as an
actual parameter corresponding to a dummy parameter that is a procedure, and if the corresponding dummy
parameter is then called, one of the following must be done:
• The dummy procedure parameter must be declared in an interface block as having an optional integer
parameter
• The call to the dummy procedure parameter (that is, the indirect call to EXIT) must include an actual
parameter corresponding to the optional one for EXIT.

004– 2165– 002 423

GETCWD ( 3F ) GETCWD ( 3F )

NAME
GETCWD – Returns the current working directory

SYNOPSIS
CHARACTER cwd*n
CALL GETCWD(cwd)
or
CHARACTER cwd*n
INTEGER GETCWD, i
i = GETCWD(cwd)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GETCWD returns the current working directory of the process in a character string. It can be called as either
a subroutine or a function. PXFGETCWD(3F) provides similar functionality.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The arguments are as follows:
cwd Character variable to receive the current working directory. The cwd argument must be of type
character and must be at least 1 character larger than the current working directory. Extra characters
are set to blanks.
i Integer return value (when called as a function); i can have the following values:
-2 GETCWD called with no argument or with a non-character argument
-1 The getcwd(3C) request failed, probably because the cwd variable was not long enough to
contain the complete path name (cwd will be set to all blanks)
>0 Number of characters in the name of the current working directory

SEE ALSO
getcwd(3C) in the UNICOS System Libraries Reference Manual

424 004– 2165– 002

GETHOST ( 3F ) GETHOST ( 3F )

NAME
GETHOST – Returns name of host mainframe

SYNOPSIS
CHARACTER host*n
INTEGER GETHOST, i
...
i = GETHOST(host)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GETHOST returns the name of the host mainframe in a character string. It can be called either as a
subroutine or a function.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
GETHOST has the following arguments:
host Variable of type character to receive the host name. It should be at least as large as the host name.
Extra characters will be set to blanks.
i Return value of type integer (when called as a function); i can have the following values:
-2 GETHOST was called with no argument or with an argument of non-character type.
-1 The gethostname(2) request failed. host will be set to all blanks.
>0 Number of characters in the name of the host.

SEE ALSO
hostname(1) in the UNICOS User Commands Reference Manual
gethostname(2) in the UNICOS System Calls Reference Manual

004– 2165– 002 425

GETOARG ( 3F ) GETOARG ( 3F )

NAME
GETOARG – Gets command-line arguments

SYNOPSIS
INTEGER GETOARG
iret=GETOARG(cbuf [,length])

IMPLEMENTATION
UNICOS systems (except Cray T90 series)

DESCRIPTION
GETOARG places the next command-line argument in cbuf. Each call to GETOARG selects the next
argument. The GETOARGC(3F) routine provides similar functionality and is available on UNICOS and
UNICOS/mk systems, including the Cray T90 series.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
cbuf Variable, array, or array element of any type to receive the argument. If cbuf is character, it is
blank-padded; otherwise, cbuf is null-padded.
length The number of words available in cbuf if cbuf is not a character variable.
iret The return value; iret can have the following values:
1 If successful
0 If there are no more command-line arguments

426 004– 2165– 002

GETOARGC ( 3F ) GETOARGC ( 3F )

NAME
GETOARGC – Gets command-line arguments

SYNOPSIS
INTEGER GETOARGC
CHARACTER cbuf*m
iret=GETOARGC(cbuf)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GETOARGC places the next command-line argument in cbuf. Each call to GETOARGC selects the next
argument.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
cbuf Variable, array, or array element of type character to receive the argument. If the argument is
shorter than cbuf, it is blank padded.
iret The return value; iret can have the following values:
1 If successful
0 If there are no more command-line arguments

004– 2165– 002 427

GETVARG ( 3F ) GETVARG ( 3F )

NAME
GETVARG – Gets command-line arguments, allowing blanks or commas as delimiters

SYNOPSIS
INTEGER GETVARG
iret=GETVARG(cbuf [,length])

IMPLEMENTATION
UNICOS systems (except Cray T90 series)

DESCRIPTION
GETVARG places the next command-line argument in cbuf. Each call to GETVARG selects the next
argument. The GETVARGC(3F) routine provides similar functionality and is available on UNICOS and
UNICOS/mk systems, including the Cray T90 series.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
cbuf Variable, array, or array element of any type to receive the argument. If cbuf is character, it is
blank-padded. Otherwise, cbuf is null-padded.
length The number of words available in cbuf if cbuf is not a character variable.
iret Return value; iret can have the following values:
1 If successful
0 If there are no more command-line arguments

428 004– 2165– 002

GETVARGC ( 3F ) GETVARGC ( 3F )

NAME
GETVARGC – Gets command-line arguments, allowing blanks or commas as delimiters

SYNOPSIS
INTEGER GETVARGC
CHARACTER cbuf*m
iret=GETVARGC(cbuf)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GETVARGC places the next command-line argument in cbuf. Each call to GETVARGC selects the next
argument. The PXFGETARG(3F) routine provides similar functionality.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
cbuf Variable, array, or array element of type character to receive the argument. If the argument is
shorter than cbuf, it is blank-filled.
iret Return value; iret can have the following values:
1 If successful
0 If there are no more command-line arguments

004– 2165– 002 429

IARGC ( 3F ) IARGC ( 3F )

NAME
IARGC, GETARG – Returns number of command-line arguments or the argument itself

SYNOPSIS
iargs= IARGC( )
INTEGER GETARG
ichars = GETARG(i,c)
ichars = GETARG(i,c,size)

IMPLEMENTATION
GETARG is available on UNICOS systems (except Cray T90 series)
IARGC is available on UNICOS and UNICOS/mk systems

DESCRIPTION
These routines return the ith command-line argument of the current process. In addition, PXFGETARG(3F)
provides similar functionality and is available on UNICOS and UNICOS/mk systems, including the
Cray T90 series.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following are valid arguments for this routine.
iargs An integer specifying the number of command-line arguments passed to the program.
ichars An integer specifying the number of nonnull characters in the string returned.
i Integer specifying the number of the argument to return.
c Character variable or integer array in which to return the command-line argument.
size If c is an array, an integer giving the number of elements in that array.
If a program is invoked with the following command line, IARGC returns 3:
foo arg 1 arg 2 arg 3

SEE ALSO
GETOPT(3) in the UNICOS System Libraries Reference Manual

430 004– 2165– 002

ISHELL ( 3F ) ISHELL ( 3F )

NAME
ISHELL – Executes a UNICOS shell command

SYNOPSIS
ISTAT = ISHELL(command)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libffio.so which is linked by default when compiling programs with
the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
ISHELL executes a UNICOS shell command. ISHELL has the following argument:
command Command to be given to the shell; can be of type character or some numeric type. If it is a
noncharacter type, the command should consist of packed characters terminated by a null byte.
On IRIX systems, this argument must be of type character.
ISHELL passes command to the shell sh(1) as input, as if command were entered at a terminal.

RETURN VALUES
ISHELL returns the termination status filled in by the waitpid(2) system call, which is used to wait for
the child shell process. Unless the command was interrupted by a signal, its exit status is contained in bits 8
through 15 (bit 0 being the least significant bit) of the value returned by ISHELL (see the waitpid(2) man
page for more information). However, if any errors occur in running the shell or collecting its exit status,
ISHELL returns a negative number; this number is the negative value of errno corresponding to the error.

EXAMPLES

WRITE( TPM NT, 500) DTV , XDT, VOL , XVOL, DSN, PDN , MBSV
CALL ISH ELL(TP MNT)
500 FORMAT (’t pmnt -l sl -F U -T -g ’,a 6,’ -x ’,a 6,
+ ’-v ’,a6,’=’,a6, ’ -P ’,a 8,’ -f ’,a , ’ -b ’,a )

SEE ALSO
pshell(1) in the UNICOS User Commands Reference Manual
system(3C) in the UNICOS System Libraries Reference Manual

004– 2165– 002 431

NLIMIT ( 3F ) NLIMIT ( 3F )

NAME
NLIMIT – Provides an interface to setting or obtaining resource limit values

SYNOPSIS
INTEGER id, rsarray(10), errstat
CALL NLIMIT(id, rsarray, errstat)
or
iret=NLIMIT(id, rsarray, errstat)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems, the default kind is KIND=8 for integer, real, complex, and
logical arguments.
This library interface provides a means to establish or view resource limit information from the kernel based
on the following arguments:
id The pid, sid, or uid corresponding to the rsarray(2) field. A 0 indicates the current pid, sid, or
uid.
rsarray An integer array that matches the resclim structure defined in
/usr/include/sys/resource.h. The array elements and their possible values are as
follows:
Array Element Values
rsarray(1) Specified resource. Valid options are as follows:
1 – CPU time limits (see CAUTIONS)
rsarray(2) Resource category. Valid options are as follows:
1 – Process
3 – Session
4 – User ID
6 – Session process
rsarray(3) Resource type. Valid options are as follows:
0 – Absolute limit
1 – Hard limit
2 – Soft limit

432 004– 2165– 002

NLIMIT ( 3F ) NLIMIT ( 3F )

rsarray(4) Resource action. Valid options are:

1 – Terminate
2 – Checkpoint and terminate
rsarray(5) Resource used. The accumulated resource used for the resource category. For
CPU time, this value is in seconds (see CAUTIONS).
rsarray(6) Resource limit value for the absolute limit type. Used for setting the absolute
resource limit value (super user only) or for returning the absolute resource
limit value.
rsarray(7) Resource limit value for the hard limit type. Used for setting the hard
resource limit value or for returning the hard resource limit value.
rsarray(8) Resource limit value for the soft limit type. Used for setting the soft resource
limit value or for returning the soft resource limit value.
rsarray(9) Reserved for future use.
rsarray(10) Reserved for future use.
errstat An integer that contains the error status as defined in /usr/include/sys/errno.h.
errstat is set if an error has occurred with either setting a limit or returning limit information.
Typical Use
The rsarray argument contains fields used to establish or view resource limits. NLIMIT calls the
nlimit(3C) routine to set up the resclim structure according to the rsarray passed to it. nlimit then
calls getlim(2) to obtain information about resource limit values or setlim(2) to change limit values.
Obtaining Information about Resource Limits
The rsarray elements rsarray(1) and rsarray(2) must be set in order to return limit values. Element
rsarray(1) represents the resource to be queried. Currently, only CPU resources are supported, so the value
of rsarray(1) must be 1.
Element rsarray(2) identifies the category of resource to be queried. rsarray(2) determines if the id
argument is a pid, sid, or a uid. An rsarray(2) value of 6 (session process) requires an sid. Acceptable
values are as follows:
Value Return Information
1 Process limits
3 Session limits
4 User limits
6 Default process limits for the session
If the call succeeds, NLIMIT fills in the missing information in elements rsarray(4) through rsarray(10).
This includes the following elements:
Array Return Information

004– 2165– 002 433

NLIMIT ( 3F ) NLIMIT ( 3F )

rsarray(4) Resource action. Returns a value of 1 for terminate or 2 for checkpoint and terminate.
This value determines whether, when a hard limit is reached, the process is checkpointed
before termination.
rsarray(5) Resource used. Returns the amount of resource currently accumulated at the time of the
call. For CPU time, this value is the amount of CPU seconds accumulated.
rsarray(6) Absolute resource limit. Returns the absolute resource limit for the specified resource. For
CPU time, this value is in seconds.
rsarray(7) Hard resource limit. Returns the hard resource limit for the specified resource. For CPU
time, this value is in seconds.
rsarray(8) Soft resource limit. Returns the soft resource limit for the specified resource. For CPU
time, this value is in seconds.
rsarray(9) Reserved for future use.
rsarray(10) Reserved for future use.

Setting Resource Limits

To set a limit value, all rsarray elements must be set to either a value or 0.
Element rsarray(1) represents the resource for which a limit is to be established. Currently, only CPU
resources are supported, so the value of rsarray(1) must be 1.
Element rsarray(2) identifies the category of resource to be set. rsarray(2) determines if the id argument is
a pid, sid, or uid. An rsarray(2) value of 6 (session process) requires an sid. Acceptable values are as
follows:
Value Limits to be Set
1 Process limits
3 Session limits
4 User limits
6 Default process limits for the session
Element rsarray(3) identifies the type of limit to be set. Acceptable values are as follows:
Value Limit Type to be Set
0 Absolute limit
1 Hard limit
2 Soft limit

434 004– 2165– 002

NLIMIT ( 3F ) NLIMIT ( 3F )

Element rsarray(4) determines whether or not the process is checkpointed before termination when a hard
limit is reached. By default, when a hard limit is reached, the process is terminated. For the core file to be
restartable, the environment variable TRACEBK should be set to 0 prior to running the application.
Acceptable values are as follows:
Value Determination
0 No change
1 Terminate
2 Checkpoint then terminate
In order to set rsarray(4), rsarray(3) must be set to limit type of hard (1).
Element rsarray(5), resource accumulated element, is not used when setting limits.
Based on the value in rsarray(3) (limit type), the corresponding rsarray(6) (absolute limit value), rsarray(7)
(hard limit value), or rsarray(8) (soft limit value) must be set. Only the super user can set absolute limits.
Only one limit value can be set with each NLIMIT call.
The NLIMIT library call fails and no information is updated in the rsarray array or no resource limits are
set if one or more of the following error conditions occur:
Error code Description
[EFAULT] The address specified for rptr was invalid.
[EINVAL] One of the arguments contains an invalid value.
[EPERM] The user ID of the requesting process is not that of a super user.
[EPERM] An attempt was made to change a limit on a system process; this is not allowed.
[ESRCH] No processes were found that matched the request.

RETURN VALUES
On successful completion, a value of 0 indicates that the call succeeded and either the rsarray array was
filled in with appropriate returned values or a new limit was set. An unsuccessful completion returns a value
of – 1 and errstat is set to indicate the error. See intro(2) for an explanation of error numbers.

CAUTIONS
The CPU time limit does not apply when running as root.

EXAMPLES
Following is sample Fortran code sequence that sets the current process CPU hard limit to 500 seconds and
the hard limit action to checkpoint and terminate.

004– 2165– 002 435

NLIMIT ( 3F ) NLIMIT ( 3F )

intege r id, rsa rr(10) , err

id =0
rsarr( 1) = 1
rsarr( 2) = 1
rsarr( 3) = 1
rsarr( 4) = 2
rsarr( 5) = 0
rsarr( 6) = 0
rsarr( 7) = 500
rsarr( 8) = 0
rsarr( 9) = 0
rsarr( 10) = 0

ire t=n limit( id,rsa rr, err)

if (ir et .EQ . -1) the n
write (0,*)’ nli mit cal l fai led’
write (0, *)’ errno = ’,e rr
end if

SEE ALSO
nlimit(1) in the UNICOS User Commands Reference Manual, for an overview of resource limits
intro(2), getlim(2), setlim(2) in the UNICOS System Calls Reference Manual
nlimit(3C) in the UNICOS System Libraries Reference Manual

436 004– 2165– 002

REMARK ( 3F ) REMARK ( 3F )

NAME
REMARK, REMARK2 – Enters a message in the stderr file

SYNOPSIS
CALL REMARK(message)
CALL REMARK2(message)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
REMARK and REMARK2 send a message to the stderr file.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
message Character entity sent to the stderr file. The character entity must be of type character or a
string of characters terminated by a null byte.
Maximum message length: (REMARK): 71 characters; (REMARK2): 79 characters.

004– 2165– 002 437

REMARKF ( 3F ) REMARKF ( 3F )

NAME
REMARKF – Enters a formatted message in the stderr file

SYNOPSIS
CALL REMARKF(var, fvar, [ fvar2, . . . fvar13])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
REMARKF enters a formatted message in the stderr file.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
var Variable containing the address of a format statement for ENCODE.
fvar Address of variable.
Up to 12 variables can be passed in arguments 2 through 13. The variables must be of type integer, real, or
logical, so that they each occupy only 1 word. The message is prefixed by ’UT009 - ’ unless you supply
a prefix. To supply the prefix, the characters ’b-b’ (b equals blank) must appear in columns 6 through 8 of
the formatted message.

CAUTIONS
Variables are passed without any data type information. Because of this, variables printed with the A data
edit descriptor print as integer Hollerith variables. Variables printed with the D edit descriptor print as a
single-precision variable. Variables printed with the G edit descriptor print as octal (typeless) variables.

438 004– 2165– 002

REMARKF ( 3F ) REMARKF ( 3F )

EXAMPLES
Sample Fortran calling sequences with user-supplied prefixes:
10030 FORMAT (’C A001 - ’, I4, ’ errors ’)
ASSIGN 100 30 TO LAB EL
CAL L REMARK F (LABEL , IERRCN T)

107 70 FORMAT (’P D00 1 - ACC ESS ’, A8,A7, ’ ED=’, I4, ’;’ )
ASSIGN 107 70 TO LAB EL
CALL REM ARK F (LABEL , DN( 1), DN( 2), ED)

Sample Fortran calling sequence without prefix:

105 50 FOR MAT (’LOOP EXECUT ED ’, I4, ’ TIMES’ )
ASS IGN 10550 TO LAB EL
CALL REM ARKF (LA BEL, LOO PCNT)

004– 2165– 002 439

SAMEFILE ( 3F ) SAMEFILE ( 3F )

NAME
SAMEFILE – Checks to see whether two files have the same inode number

SYNOPSIS
LOGICAL SAMEFILE
i=SAMEFILE(path1, path2)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SAMEFILE returns .TRUE. if two file names point to the same inode; otherwise, it returns .FALSE.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.

EXAMPLES
In this example, F1 and F2 represent the path names of files to be tested. The names must start at a word
boundary and be null terminated. On UNICOS/mk systems and Cray T90 series systems, a character
variable may not be used.
IF (SAMEF ILE(F1 ,F2)) PRINT* ,’file s are the same!’

440 004– 2165– 002

SENSEBT ( 3F ) SENSEBT ( 3F )

NAME
SENSEBT – Determines if bidirectional memory transfer is enabled or disabled

SYNOPSIS
CALL SENSEBT(mode)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SENSEBT determines if bidirectional memory transfer is enabled or disabled.
mode Transfer mode:
=1 Bidirectional memory transfer is enabled
=0 Bidirectional memory transfer is disabled

004– 2165– 002 441

UNAME ( 3F ) UNAME ( 3F )

NAME
UNAME – Returns name of current operating system (Fortran interface to uname(2))

SYNOPSIS
The uname(2) system call can be called from Fortran as a function:
CHARACTER sys*n1, node*n2, rel*n3, ver*n4, mach*n5
INTEGER UNAME, i
i = UNAME(sys, node, rel, ver, mach)

IMPLEMENTATION
UNICOS systems (except Cray T90 series)

DESCRIPTION
UNAME returns information identifying the current operating system. It can be called as either a subroutine
or a function.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The arguments are as follows:
sys Character or integer variable to receive the name of the current operating system.
node Character or integer variable to receive the name by which this system is known on a
communications network.
rel Character or integer variable to receive the name of the operating system release.
ver Character or integer variable to receive the name of the operating system release version.
mach Character or integer variable to receive the name of the hardware on which this system is running.
i Return value, of type integer (when called as a function):
-2 UNAME called with too many parameters (the first 5 parameters remain)
-1 The uname(2) system call failed
0 UNAME called with no parameters
1-5 UNAME returned 1 to 5 values
The character variables receive as much of the selected field as will fit. If the field is longer it will be
truncated; if shorter, the character variable will be padded with blanks.

442 004– 2165– 002

UNAME ( 3F ) UNAME ( 3F )

The integer variables receive no more than the first 8 characters of the appropriate field, left-justified and
zero-filled.
The PXFUNAME(3F) routine provides similar functionality and is available on UNICOS and UNICOS/mk
systems.

NOTES
PXFUNAME(3F) provides similar functionality and is available on UNICOS and UNICOS/mk systems.

SEE ALSO
uname(2) in the UNICOS System Calls Reference Manual for a description of the content and length of the
various uname fields

004– 2165– 002 443

444 004– 2165– 002
INTRO_HEAP ( 3F ) INTRO_HEAP ( 3F )

NAME
INTRO_HEAP – Introduction to heap, table, and data segment management

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION
The heap routines let you manage a block of memory (the heap) within your program area, manipulate
tables, and manage the secondary data segment (SDS). The management routines are divided into three
categories: heap management, table management, and SDS management.

HEAP MANAGEMENT ROUTINES

The heap management routines provide dynamic storage allocations by managing a block of memory, called
the heap, within your job area. Each job has its own heap. The functions of the heap management routines
include allocating a block of memory, returning a block of memory to the heap’s list of available space, and
changing the length of a block of memory. Heap management routines may also move a heap block to a
new location if there is no room to extend it, return part of the heap to the operating system, check the
integrity of the heap, and report heap statistics.
The heap management routines keep various statistics on the use of the heap. These statistics include values
used to tune heap parameters specified by the loader for your compiler and information used in debugging.
The following routines are used for heap management:
• HPALLOC(3F): allocates a block of memory from the heap
• HPCHECK(3F): checks the integrity of the heap
• HPCLMOVE(3F): extends a block or copies block contents into a larger block
• HPDEALLC(3F): returns a block of memory to the heap
• HPDUMP(3F): dumps the address and size of each heap block
• HPNEWLEN(3F): changes the size of an allocated heap block
• HPSHRINK(3F): returns memory from the heap to the operating system
• IHPLEN(3F): returns the length of a heap block
• IHPSTAT(3F): returns statistics about the heap
• IHPVALID(3F): returns validity of block address

004– 2165– 002 445

INTRO_HEAP ( 3F ) INTRO_HEAP ( 3F )

TABLE MANAGEMENT ROUTINES

The following list describes each Fortran-callable table management routine:
• TMADW: adds a word to a table
• TMAMU: reports table management operation statistics
• TMATS: allocates table space
• TMINIT: initializes table
• TMMSC: searches the table with a mask to locate a field within an entry
• TMMVE: moves memory
• TMPTC: processes table collisions
• TMPTS: presets table space
• TMSRC: searches the table with or without a mask to locate a field within an entry and an offset
• TMVS: searches a vector table for the search argument
The Fortran-callable versions of these routines use default BTAB and LTAB definitions from a common area
in the library.
TMINIT zeroes all elements of the LTAB table length vector. You must preset each element of BTAB to
contain the desired interspace value for the corresponding table (for example, s1 in the following example
determines the interspace value for table 1). Interspace values determine how many words are added to a
table when more room is needed for that table or for any table with a lower number.
INT EGER BTAB(6 4), LTAB(6 4)
COMMON /TM/ BTAB(6 4), LTAB(6 4)
DATA BTA B /s1 ,s2 ,s3,.. .,s64/
.
.
CALL TMI NIT

After the call to TMINIT, BTAB should not be changed. LTAB is only used to pass new table lengths from
the user to the table manager.
You can use statements such as the following to access each table. In this example, TABLEi is accessed.
EQU IVALEN CE (BT AB(i), PTR i)
INTEGE R PTR i, TAB LEi (0: 0)
POINTE R (PT Ri, TABLEi )
.
.
TABLEi (subsc rip t) = ...

446 004– 2165– 002

INTRO_HEAP ( 3F ) INTRO_HEAP ( 3F )

TM Common Block Name

The common block name TM is reserved for use by the Table Manager and must always contain 64 LTAB
words.
COM MON /TM/ BTAB(6 4), LTAB(64)
The following program uses Cray pointers to access tables.
PRO GRA M TES T
IMP LIC IT INT EGE R (A-Z)
COMMON /TM / BTA B (64 ), LTAB (64 )
COM MON /PT RS/ PTR1, PTR2, PTR63
POI NTER (PTR1, TAB1 (1))
POI NTER (PTR2, TAB2 (1))
POI NTE R (PT R63, TAB 63 (1))
DAT A BTA B/6 4*10/

C Ini tia lize table manage r

CAL L TMI NIT

C Alloca te space for fir st, second and last table of 40,
C 40 and 60 wor ds

CAL L TMA TS ( 1, 40)

CAL L TMA TS ( 2, 40)
CAL L TMA TS (63, 60)

C Def ine CRA Y POI NTERS

PTR 1 = BTA B ( 1)
PTR 2 = BTA B ( 2)
PTR 63 = BTA B (63)

C Zer o tab les

DO I = 1, 40
TAB 1 (I) = 0
TAB 2 (I) = 0
TAB 63(I) = 0
END DO

DO I = 41, 60
TAB 63( I) = 0
END DO

004– 2165– 002 447

INTRO_HEAP ( 3F ) INTRO_HEAP ( 3F )

C Ass ign val ues and pre set to eac h hal f of the first tab le.

DO I = 1, 10
TAB 1(I) = I
ENDDO

CAL L TMPTS( PTR1 + 10, 10, 11)

CAL L TMPTS( PTR 1 + 20, 0, 22)
CALL TMP TS(PTR 1 + 30, 1, 33)
CAL L TMP TS( PTR1 + 31, 9, 44)

C Mov e the fir st 20 wor ds of the fir st tab le to the fir st

C 20 words of the sec ond tab le.

CAL L TMMVE (PT R1, PTR 2, 20)

C Pre set las t 20 ele ments of the 63rd table.

CALL TMP TS (PT R63 + 40, 20, 12)

C Mov e the last 20 words of the 63r d tab le to the las t

C 20 wor ds of the sec ond tab le.

CAL L TMMVE (PTR63 + 40, PTR2 + 20, 20)

END

SDS MANAGEMENT ROUTINES

The SDS management routines, SDSALLOC, SDSREALC, and SDSFREE, let you allocate, reallocate, and
deallocate blocks of the SDS. They manage units of 4096 bytes and are described on the SDSALLOC man
page.

448 004– 2165– 002

CRAYDUMP ( 3F ) CRAYDUMP ( 3F )

NAME
CRAYDUMP – Dump arrays of memory

SYNOPSIS
DIMENSION ARRAY(1000)
CALL CRAYDUMP(ARRAY(10), ARRAY(812), 101)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
CRAYDUMP is a Fortran-callable routine to dump arrays of memory. Four words of memory are displayed
per line of output. Each word is displayed in octal (hexadecimal on UNICOS/mk systems) and ASCII. No
line will exceed 132 characters in length.
The first and second arguments are the first and last words of memory to be dumped. If the last word
address is greater than the first word address, no memory is dumped. The third argument is the Fortran unit
number to which the dump is to be written. The unit should be 101 (stdout) or any unit which is (or can
be) opened for sequential, formatted output.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.

NOTES
On UNICOS systems, memory dumps are formatted in octal. On UNICOS/mk systems, memory dumps are
formatted in hexadecimal.
CAUTIONS
On UNICOS/mk systems, care should be taken such that only contiguous regions of memory (only memory
with a single array or common block) should be dumped.

004– 2165– 002 449

HPALLOC ( 3F ) HPALLOC ( 3F )

NAME
HPALLOC – Allocates a block of memory from the heap

SYNOPSIS
CALL HPALLOC(addr, length, errcode, abort)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
HPALLOC allocates a block of memory from the program’s heap that is greater than or equal to the size
requested. If the request cannot be satisfied from the free blocks currently in the heap, it will try to allocate
more memory from the system.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
addr First word address of the allocated block (output).
length Number of words of memory requested (input).
errcode Error code is 0 if no error was detected; otherwise, it is a negative integer code for the type of
error (output).
abort Abort code; nonzero requests abort on error; 0 requests an error code (input).
By using the Fortran POINTER mechanism in the following manner, you can use array A to refer to the
block allocated by HPALLOC.
POI NTER (ad dr, A(1 ))
Error conditions are as follows:
Error code Condition
-1 Length is not an integer greater than 0.
-2 No more memory is available from the system (checked if the request cannot be satisfied
from the available blocks on the heap).
-8 The memory arena has been truncated by a user’s sbreak(2) call with a negative value.

SEE ALSO
HPCHECK(3F), HPCLMOVE(3F), HPDEALLC(3F), HPDUMP(3F), HPNEWLEN(3F), HPSHRINK(3F)

450 004– 2165– 002

HPCHECK ( 3F ) HPCHECK ( 3F )

NAME
HPCHECK – Checks the integrity of the heap

SYNOPSIS
CALL HPCHECK(errcode)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION

HPCHECK checks the integrity of the heap. Each control word is examined to ensure that it was not
overwritten.
errcode The error code is 0 if no error was detected; otherwise, it is a negative integer code for the type
of error (output).
The error conditions are as follows:
Error code Condition
-7 Memory arena has been corrupted.

004– 2165– 002 451

HPCLMOVE ( 3F ) HPCLMOVE ( 3F )

NAME
HPCLMOVE – Extends a block or copies the contents of the block into a larger block

SYNOPSIS
CALL HPCLMOVE(addr, length, status, abort)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine extends a block if it is followed by a large enough free block or copies the contents of the
existing block to a larger block and returns a status code indicating that the block was moved. It can also
reduce the size of a block if the new length is less than the old length. In this case, HPCLMOVE has the
same effect as HPNEWLEN(3F).
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
addr On entry, first word address of the block to change; on exit, the new address of the block if it was
moved.
length Requested new total length (input).
status Status is 0 if the block was extended in place, 1 if it was moved, and a negative integer for the
type of error detected (output).
abort Abort code. Nonzero requests abort on error; 0 requests an error code (input). Error conditions are
as follows:
-1 Length is not an integer greater than 0.
-2 No more memory is available from the system (checked if the block cannot be
extended and the free space list does not include a large enough block).
-3 Address is outside the bounds of the heap.
-4 Block is already free.
-5 Address is not at the beginning of a block.

452 004– 2165– 002

HPDEALLC ( 3F ) HPDEALLC ( 3F )

NAME
HPDEALLC – Returns a block of memory to the list of available space (the heap)

SYNOPSIS
CALL HPDEALLC(addr, errcode, abort)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
HPDEALLC returns a block of memory to the list of available space (the heap).
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
addr First word address of the block to deallocate (input).
errcode Error code is 0 if no error was detected; otherwise, it is a negative integer code for the type of
error (output).
abort Abort code. Nonzero requests abort on error; 0 requests an error code (input).
Error conditions are as follows:
Error code Condition
-3 Address is outside the bounds of the heap.
-4 Block is already free.
-5 Address is not at the beginning of the block.

004– 2165– 002 453

HPDUMP ( 3F ) HPDUMP ( 3F )

NAME
HPDUMP – Dumps the address and size of each heap block

SYNOPSIS
CALL HPDUMP(code, dsname)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
HPDUMP dumps the address and size of each heap block.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
code Code for the type of dump requested, as follows:
Code Meaning
1 Dumps all heap blocks in storage order
dsname Name of the file to which the dump should be written; dsname may be in left-justified, Hollerith
form, or it may be a Fortran character variable.

454 004– 2165– 002

HPNEWLEN ( 3F ) HPNEWLEN ( 3F )

NAME
HPNEWLEN – Changes the size of an allocated heap block

SYNOPSIS
CALL HPNEWLEN(addr, length, status, abort)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine changes the size of an allocated heap block. If the new length is less than the allocated length,
the portion starting at addr + length is returned to the heap. If the new length is greater than the allocated
length, the block is extended when followed by a free block. A status is returned, indicating if the change
was successful.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
addr First word address of the block to change (input).
length Requested new total length of the block (input).
status Status is 0 if the change in length was successful, 1 if the block could not be extended in place,
and a negative integer for the type of error detected (output).
abort Abort code. Nonzero requests abort on error; 0 requests an error code (input).
Error conditions are as follows:
Error code Condition
-1 Length is not an integer greater than 0.
-3 Address is outside the bounds of the heap.
-4 Block is already free.
-5 Address is not at the beginning of the block.

004– 2165– 002 455

HPSHRINK ( 3F ) HPSHRINK ( 3F )

NAME
HPSHRINK – Returns memory from the heap to the operating system

SYNOPSIS
CALL HPSHRINK

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This is a Fortran interface to the _memfree memory manager routine. The unused portion of the heap is
returned to the operating system if the blocks closest to the break value are free.

SEE ALSO
utilities(3C) in UNICOS System Libraries Reference Manual for more information about _memfree
and ememmgr

456 004– 2165– 002

IHPLEN ( 3F ) IHPLEN ( 3F )

NAME
IHPLEN – Returns the length of a heap block

SYNOPSIS
length=IHPLEN(addr, errcode, abort)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
IHPLEN returns the length of a heap block.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
length Length of the block starting at addr (output).
addr First word address of the block (input).
errcode Error code is 0 if no error was detected; otherwise, it is a negative integer code for the type of
error (output).
abort Abort code. Nonzero requests abort on error; 0 requests an error code (input).
Error conditions are as follows:
Error code Condition
-3 Address is outside the bounds of the heap.
-4 Block is already free.
-5 Address is not at the beginning of the block.

004– 2165– 002 457

IHPVALID ( 3F ) IHPVALID ( 3F )

NAME
IHPVALID – Returns validity of block address

SYNOPSIS
ret=IHPVALID(addr)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
IHPVALID returns the validity of a block address.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
ret Return code.
=0 Block pointed to by addr is not a valid block in the heap.
≠0 Block pointed to by addr is a valid block in the heap.
addr First word address of the block (input).

458 004– 2165– 002

TMADW ( 3F ) TMADW ( 3F )

NAME
TMADW – Adds a word to a table

SYNOPSIS
index=TMADW(number, entry)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TMADW adds a word to a table.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
index Zero-based index of the added word
number Table number
entry Entry for the table

004– 2165– 002 459

TMAMU ( 3F ) TMAMU ( 3F )

NAME
TMAMU – Reports table management operation statistics

SYNOPSIS
CALL TMAMU(len, tabnum, tabmov, tabmar, nword)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TMAMU reports on table management operation statistics.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
This routine defines the following values:
len Allocated length of the tables
tabnum Number of tables used
tabmov Number of tables moved
tabmar Maximum mark of the tables in memory
nword Number of words moved

460 004– 2165– 002

TMATS ( 3F ) TMATS ( 3F )

NAME
TMATS – Allocates table space

SYNOPSIS
index=TMATS(number, incre)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TMATS allocates table space.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
index Zero-based index of the new area in the table
number Table number
incre Table increment (number of words to be added to the size of the table)

004– 2165– 002 461

TMINIT ( 3F ) TMINIT ( 3F )

NAME
TMINIT – Initializes table descriptor vector and zeroes table length vector

SYNOPSIS
CALL TMINIT

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TMINIT initializes the table manager, Table Base Address table (BTAB), and zeroes out all of the elements
of the Table Length table (LTAB).
The BTAB array should contain the desired interspace value for the corresponding array before calling
TMINIT. On exit, BTAB will contain the base address for the corresponding table.
Call TMINIT before accessing the table manager.

SEE ALSO
INTRO_HEAP(3F)

462 004– 2165– 002

TMMSC ( 3F ) TMMSC ( 3F )

NAME
TMMSC – Searches the table by using a mask to locate a specific field within an entry using an optional
offset

SYNOPSIS
index=TMMSC(tabnum, mask, sword, nword [,offset])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine searches a table using a mask to locate a specific field.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
index Zero-based table index of the match, if found; – 1 returned if no match is found.
tabnum Table number.
mask Mask defining a field within a word.
sword Search word.
nword Number of words per entry group.
offset Offset into the table. No offset is used if this argument is not specified. Optional argument.

004– 2165– 002 463

TMMVE ( 3F ) TMMVE ( 3F )

NAME
TMMVE – Moves memory (words)

SYNOPSIS
CALL TMMVE(from, to, count)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine moves memory.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
from Address from which words are to be moved
to Address of the location to which words are to be moved
count Number of words to be moved

NOTES
The TMMVE routine expects indirect addresses to be passed for the from and to arguments. These can be
obtained by specifying Cray pointers, using the LOC function, or by using the TBAB table manager array
elements.

464 004– 2165– 002

TMPTC ( 3F ) TMPTC ( 3F )

NAME
TMPTC – Processes table collisions

SYNOPSIS
CALL TMPTC

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine checks all managed tables to ensure that the current size of the pad area is not less than zero
and is not greater than the specified pad. Any tables in violation of this are adjusted so that they have
proper interspace.

004– 2165– 002 465

TMPTS ( 3F ) TMPTS ( 3F )

NAME
TMPTS – Presets table space

SYNOPSIS
CALL TMPTS(start, len, preset)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine presets table space.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
start Starting address
len Length to preset
preset Preset value

NOTES
The TMPTS routine requires an indirect address for the start argument. An indirect address can be a Cray
pointer, a BTAB table array element, or the result of a LOC function.

466 004– 2165– 002

TMSRC ( 3F ) TMSRC ( 3F )

NAME
TMSRC – Searches the table by using optional mask to locate specific field within entry and offset

SYNOPSIS
index=TMSRC(tabnum, arg[, nword[, offset[, mask]]])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine searches a table using an optional mask.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
index Zero-based table index of the match, if a match is found; – 1 returned if no match is found.
tabnum Table number to search.
arg Search argument or key.
nword Optional argument; number of words per entry. Default is 1.
offset Optional argument; offset into the entry group. Default is 0.
mask Optional argument; mask for field within entries. Default is a mask of all 1’s.

004– 2165– 002 467

TMVSC ( 3F ) TMVSC ( 3F )

NAME
TMVSC – Searches a vector table for the search argument

SYNOPSIS
index=TMVSC(tabnum, arg, nword)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This routine searches a vector table for a search argument.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
index Zero-based table index of the match, if a match is found; – 1 returned if no match is found.
tabnum Table number.
arg Search argument.
nword Number of words per entry group.

468 004– 2165– 002

INTRO_PROGAIDS ( 3F ) INTRO_PROGAIDS ( 3F )

NAME
INTRO_PROGAIDS – Introduction to programming aids

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION
Programming aids consist of the following types of routines:
• Tracing and timing routines
• Watchpointing routines
• Traceback routines
• Symbolic dump routines
• Exchange package processing routines
• Signal routines
• Character functions
• Byte and bit manipulation routines
In addition to these routines, this section includes the reprieve(3F) man page, which describes the
traceback procedure after an error.

TRACING AND TIMING ROUTINES

Tracing and timing of user programs is enabled on the f90 command with the Flowtrace option (-ef).
When these options are specified, the Fortran compiler automatically places calls to the trace libraries at the
beginning and end of each routine. If default libraries are loaded, your program will be enabled for
Flowtracing. This trace library times individual routines. After your program completes normally, you may
execute the flowview command to view and study the timing results.
If you load a traced program with libperf.a by using f90 -lperf, this library will generate Perftrace,
instead of Flowtrace, data. This trace library times individual routines, but it does so using the Hardware
Performance Monitor (HPM), which is available only on UNICOS systems. The HPM provides such
performance statistics as megaflop ratings of each routine. After your program completes normally, you can
execute the perfview command to view and study the statistical timing results.
The Flowtrace library contains routines with names that start with the letters ZZZF0 and IZZF0. You
should avoid naming any routine in your program that starts with this prefix.
The Perftrace library contains routines with names that start with the letters ZZZP0 and IZZP0. You
should avoid these prefixes when naming routines in your program. You should also avoid naming a routine
SECOND in your program, if you are using either of the tracing tools.

004– 2165– 002 469

INTRO_PROGAIDS ( 3F ) INTRO_PROGAIDS ( 3F )

You can control individual routine event tracing by calling the library routine SETPLIMQ(3F). This routine
only provides meaningful results under Flowtrace. However, for compatibility, it is also available as a
dummy entry in Perftrace. You can time individual sections of your program by calling the FLOWMARK
routine, which is available under both Flowtrace and Perftrace.
WATCHPOINTING ROUTINES
As a debugging aid, you can control watchpointing of any variables or memory areas in your program.
Watchpointing is enabled on the f90 command with the Flowtrace option -ef. You must specify the
special watchpoint library libwatch.a when you load your program.
In addition, you must include calls to the watchpointing facility in your program, specifying which variables
are to be checked at every routine entry and exit. You should avoid beginning any routine names with the
letters WATCH when you use this facility.

TRACEBACK ROUTINES
The traceback routines list all subroutines active in the current calling sequence (using TRBK(3F)) and return
information for the current level of the calling sequence (with TRBKLVL(3F)). TRACEBK(3F) is also
available. It prints a traceback on stdout.
Traceback routines return unpredictable results when subroutine linkage does not use standard calling
sequences.

DUMP ROUTINES
The symbolic dump routines produce a symbolic dump of a running program. SYMDUMP(3F) is
recommended for use on the UNICOS operating system because it has an interface designed for the
UNICOS operating system.

EXCHANGE PACKAGE PROCESSING ROUTINES

The exchange package processing routine (XPFMT(3F)) provides a printable image of an exchange package,
which is a 16-word block of memory associated with a particular program. This routine is available on
UNICOS systems only.

SIGNAL ROUTINES
Signals are an asynchronous process control and interprocess communication mechanism in the UNICOS
operating system. As a control mechanism, signals can notify or terminate a process when certain hardware
conditions occur. For instance, if a process gets a floating-point error or operand range error, the kernel
sends that process a SIGFPE (floating-point exception) or SIGORE (operand range error), respectively. In
addition, users can send certain signals to their processes by pressing <CONTROL-C> or <CONTROL-\>,
which generate SIGINT and SIGQUIT, respectively.

470 004– 2165– 002

INTRO_PROGAIDS ( 3F ) INTRO_PROGAIDS ( 3F )

Each signal has a default action associated with it that normally terminates its process, with or without a
core dump. Processes may also choose to catch a signal; that is, jump to a user-defined signal handler
routine when the signal is sent to the process. A signal may also be ignored by a process, in which case the
delivery of the signal has no effect on the process.
See FSIGCTL(3F) for a list of the signals and a brief description of the meaning of each signal.
The SHUTDSAV routine sets up calling programs to be checkpointed on system shutdown.
The SIGOFF routine prevents receipt of all signals currently being caught. The SIGON routine allows
receipt of signals after a SIGOFF or within a signal handler.

CHARACTER FUNCTIONS
The following routines are used for character functions:
• CHAR: converts integer to character.
• ICHAR: converts character to integer.
• INDEX: determines index location of a character substring within a string.
• LEN: determines the length of a character string.
• LGE, LGT, LLE, LLT: compares strings lexically.

PACKING ROUTINES
The packing routines provide alternative ways to pack and unpack data into or out of Cray words. The
following routines are used for packing:
• P32: packs 32-bit words into Cray 64-bit words.
• U32: unpacks 32-bit words from Cray 64-bit words.
• P6460: packs 60-bit words into Cray 64-bit words.
• U6064: unpacks 60-bit words from Cray 64-bit words.
• PACK: compresses stored data.
• UNPACK: expands stored data.

BYTE AND BIT MANIPULATION ROUTINES

Byte and bit manipulation routines move bytes and bits between variables and arrays, compare bytes,
perform searches with a byte count as a search argument, and perform conversion on bytes.
The following routines are used for bit manipulation:
• PUTBYT: replaces a byte in a variable or an array with a specified value
• IGTBYT: extracts a byte from a variable
• MOV: moves bytes between variables or arrays

004– 2165– 002 471

INTRO_PROGAIDS ( 3F ) INTRO_PROGAIDS ( 3F )

• MOVBIT: moves bits between variables or arrays

• MVC: moves characters between memory areas
TIMING ROUTINES
Timing routines include time and date routines, which produce the time and/or date in specified forms. The
following are date and time routines:
• CLOCK: returns the current system clock time
• DATE: returns the current date
• JDATE: returns the current Julian date
• ICPUSED: gets CPU time in real-time clock values
• RTC, IRTC: returns real-time clock values
• SECOND: returns the elapsed CPU time (in seconds of real numbers) since the start of a program
• SECONDR: returns real-time clock values
• TIMEF: returns the elapsed wall-clock time since the initial call to TIMEF
• TREMAIN: returns the CPU time (in seconds of real numbers) remaining for the program

MISCELLANEOUS ROUTINES
The following routines are available on UNICOS systems only, with the exception of TRIMLEN(3F), which
is available on all UNICOS or UNICOS/mk systems.
• DTTS: converts ASCII date and time to time stamp
• MTTS: converts machine time to time stamp
• TRIMLEN: returns the length of a character argument without counting trailing blanks
• TSDT: converts time stamps to ASCII date and time strings
• TSMT: converts time stamps to real-time clock values
• UNITTS: returns time-stamp units in specified standard time units

OTHER ROUTINES
AUXSTAT specifies the number of reads and writes to secondary data segments (SDS) that have occurred
while accessing auxiliary array variables.
ICEIL returns the integer ceiling of a rational number.
LOC returns the memory address of a variable or an array.

472 004– 2165– 002

AUXSTAT ( 3F ) AUXSTAT ( 3F )

NAME
AUXSTAT – Gives the number of reads and writes to SDS that have occurred while accessing auxiliary array
variables

SYNOPSIS
CALL AUXSTAT( )

IMPLEMENTATION
UNICOS systems

DESCRIPTION
AUXSTAT prints to stderr the number of reads and writes to secondary data segments (SDS) that occurred
while accessing auxiliary array variables.

004– 2165– 002 473

BITVEC ( 3F ) BITVEC ( 3F )

NAME
BITVEC – Generates a bit mask corresponding to integer or real arrays according to a specified condition

SYNOPSIS
INTEGER BITVEC
INTEGER np, type, nbits, bits(*), npop, incv1, incv2
INTEGER v1(*), v2(*)
or
REAL v1(*), v2(*)
INTEGER s
or
REAL s
np = BITVEC(type, nbits, bits, npop, v1, incv1, s)
or
np = BITVEC(type, nbits, bits, npop, v1, incv1, v2, incv2)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
BITVEC efficiently creates a bit mask that results from a comparison of elements of one vector with those of
another vector or a scalar.
The resulting bit mask is padded with zeros to a word boundary.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following arguments are passed to BITVEC:
type Integer value, variable, or array element containing the zero-padded Hollerith-type code that
defines the type of vector comparison that will be used to generate the bit mask.
If type begins with V, a vector-to-vector compare is implied. If type begins with S, a vector-to-scalar
compare is implied.
The following values are valid for type:
type Value
’VFEQ’L v1.EQ.v2 FLOATING-POINT
’VFNE’L v1.NE.v2 FLOATING-POINT
’VFGT’L v1.GT.v2 FLOATING-POINT
’VFGE’L v1.GE.v2 FLOATING-POINT

474 004– 2165– 002

BITVEC ( 3F ) BITVEC ( 3F )

’VFLT’L v1.LT.v2 FLOATING-POINT

’VFLE’L v1.LE.v2 FLOATING-POINT
’VIEQ’L v1.EQ.v2 INTEGER
’VINE’L v1.NE.v2 INTEGER
’VIGT’L v1.GT.v2 INTEGER
’VIGE’L v1.GE.v2 INTEGER
’VILT’L v1.LT.v2 INTEGER
’VILE’L v1.LE.v2 INTEGER
’SFEQ’L v1.EQ.s FLOATING-POINT
’SFNE’L v1.NE.s FLOATING-POINT
’SFGT’L v1.GT.s FLOATING-POINT
’SFGE’L v1.GE.s FLOATING-POINT
’SFLT’L v1.LT.s FLOATING-POINT
’SFLE’L v1.LE.s FLOATING-POINT
’SIEQ’L v1.EQ.s INTEGER
’SINE’L v1.NE.s INTEGER
’SIGT’L v1.GT.s INTEGER
’SIGE’L v1.GE.s INTEGER
’SILT’L v1.LT.s INTEGER
’SILE’L v1.LE.s INTEGER
nbits Vector length. This defines the size of the input vectors in words and the output bit mask in
bits.
bits Output bit mask. Must be word-aligned and be of size (nbits+63)/64 words.
npop Output number of bits set in bit mask. This parameter is assigned – 1 if BITVEC was not called
with correct parameters.
v1 Real or integer array that contains the first vector.
inv1 Memory stride in words for array v1. This stride may be negative.
v2 REAL or INTEGER array that contains the second vector if doing a vector-to-vector compare.
inv1 Memory stride for array v2 in words. This stride may also be negative, and is used only if a
vector-to-vector compare is requested.
s REAL or INTEGER constant, variable, or array element containing the second vector if doing a
vector-to-scalar compare.

004– 2165– 002 475

BITVEC ( 3F ) BITVEC ( 3F )

RETURN VALUES
Equivalent to npop. The number of bits set in the bit mask, or – 1 if BITVEC was not called with correct
parameters.

476 004– 2165– 002

BITVECM ( 3F ) BITVECM ( 3F )

NAME
BITVECM – Generates a bit mask corresponding to masked integer arrays according to a specified condition

SYNOPSIS
INTEGER BITVECM
INTEGER np, type, nbits, bits(*), npop, incv1, incv2
INTEGER v1(*), v2(*)
or
INTEGER s
np = BITVECM(type, nbits, bits, npop, v1, incv1, mask1, shift1, s [, incv2, mask2, shift2])
or
np = BITVECM(type, nbits, bits, npop, v1, incv1, mask1, shift1, v2, incv2, mask2, shift2)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
BITVECM efficiently creates a bit mask that results from a comparison of elements of one vector with those
of another masked and shifted vector or a scalar.
The resulting bit mask is padded with zeros to a word boundary.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following arguments are passed to BITVECM:
type Integer value, variable, or array element containing the zero-padded Hollerith type code that
defines the type of vector comparison that will be used to generate the bit mask.
If type begins with V, a vector-to-vector compare is implied. If type begins with S, a vector-to-
scalar compare is implied.
The following values are valid for type:
type Value
’VIEQ’L v1.EQ.v2 INTEGER
’VINE’L v1.NE.v2 INTEGER
’VIGT’L v1.GT.v2 INTEGER
’VIGE’L v1.GE.v2 INTEGER
’VILT’L v1.LT.v2 INTEGER
’VILE’L v1.LE.v2 INTEGER

004– 2165– 002 477

BITVECM ( 3F ) BITVECM ( 3F )

’SIEQ’L v1.EQ.s INTEGER

’SINE’L v1.NE.s INTEGER
’SIGT’L v1.GT.s INTEGER
’SIGE’L v1.GE.s INTEGER
’SILT’L v1.LT.s INTEGER
’SILE’L v1.LE.s INTEGER
nbits Vector length. This defines the size of the input vectors in words and the output bit mask in
bits.
bits Output bit mask. Must be word-aligned and be of size (nbits+63)/64 words.
npop Output number of bits set in bit mask. This argument is assigned a value of – 1 if BITVECM
was not called with correct parameters.
v1 INTEGER array that contains the first vector.
incv1 Memory stride in words for array v1. This stride can be negative.
mask1 Mask used to perform a bitwise-OR on the elements of v1 after the shift.
shift1 Number of bits to right shift the elements of v1 before masking.
v2 INTEGER array that contains the second vector if doing a vector-to-vector compare.
s INTEGER constant, variable, or array element containing the second vector if doing a vector-to-
scalar compare.
incv2 Memory stride for array v2 in words. This stride can also be negative, and is used only if a
vector-to-vector compare is requested.
mask2 Mask used to perform a bitwise-OR on the elements of v2 or s after the shift.
shift2 Number of bits to right shift the elements of v2 or s before masking.

RETURN VALUES
Equivalent to npop. The number of bits set in the bit mask, or – 1 if BITVECM was not called with correct
parameters.

478 004– 2165– 002

BYT ( 3F ) BYT ( 3F )

NAME
PUTBYT, IGTBYT – Replaces a byte in a variable or an array

SYNOPSIS
value=PUTBYT(string, position, value)
byte=IGTBYT(string, position)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
PUTBYT replaces a specified byte in a variable or an array with a specified value. IGTBYT extracts a
specified byte from a variable or an array.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
string The address of a variable or array. The variable or array may be of any type, except character.
position The number of the byte to be replaced or extracted. This argument must be an integer ≥ 1. If
position is ≤ 0, no change is made to the destination string; value returned is – 1. For IGTBYT,
if position is ≥ 0, value is an integer between 0 and 255.
value The new value to be stored into the byte. This argument must be an integer with a value
between 0 and 255.
If PUTBYT is called as an integer function (having been properly declared in the user program), the value of
the function is the value of the byte stored.
The high-order 8 bits of the first word of the variable or array are called byte 1.
The value of the byte returned by IGTBYT is an integer value between 0 and 255.

004– 2165– 002 479

DTTS ( 3F ) DTTS ( 3F )

NAME
DTTS – Converts ASCII date and time to time stamp

SYNOPSIS
INTEGER dtts
ts=DTTS(date, time, ts)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
DTTS converts ASCII date and time to time stamp.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ts Time stamp corresponding to date and time (type integer). On return, if ts=0, an incorrect
parameter was passed to DTTS. The routine returns a positive value for dates and times in the
proper format and between 01/01/73 00:00:01 and 12/31/99 23:59:59, inclusive.
date On entry, ASCII date in mm/dd/yy format. This may not be a Fortran character variable.
time On entry, ASCII time in hh:mm:ss format. This may not be a Fortran character variable.

NOTES
Time stamp routines are invalid for dates later than 1999.

480 004– 2165– 002

FSIGCTL ( 3F ) FSIGCTL ( 3F )

NAME
FSIGCTL – Specifies action on receipt of signal

SYNOPSIS
INTEGER FSIGCTL, oldact
CHARACTER*(*) action, sig
EXTERNAL func
oldact = FSIGCTL(action, sig, func)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
FSIGCTL is the Fortran-callable interface to the sigctl(2) system call.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
FSIGCTL lets you choose one of six ways to handle the receipt of a specific signal, as specified by the
following arguments:
oldact If fsigctl completes successfully, it returns the previous action for the specified signal;
otherwise – 1 is returned.
action Character string that determines the action taken on receipt of the signal. Valid character string
values for action are as follows:
’DUMPCORE’ When signal sig arrives, terminate the program and generate a core file (see
signal(2)).
’IGNORE’ Ignore signal sig.
’KILL’ When signal sig arrives, terminate the program.
’REGISTER’ When signal sig arrives, transfer control to subroutine func to handle the
signal, then return back to the point of interrupt.
’STOP’ When signal sig arrives, stop the program.
’CONTINUE’ When signal sig arrives, continue the program.
sig Character string that defines the signal to catch. Valid values are defined in the
<sys/signal.h> file; the strings are the same as the signal names (for example, ’SIGHUP’,
’SIGABRT’, and so on).

004– 2165– 002 481

FSIGCTL ( 3F ) FSIGCTL ( 3F )

func If action is ’REGISTER’, func is the user’s signal-handling routine; otherwise, func should be 0.
Usually, the name of the signal-handling routine must be declared as EXTERNAL, as in the
EXAMPLES section.

NOTES
On UNICOS systems (excluding the Cray T90 series), action and sig can be integer values instead of
character strings. Valid integer values for action are defined in <sys/signal.h> and on the sigctl(2)
man page. Valid integer values for sig are the signal numbers defined in signal(2).
To promote portability, it is recommended that the sigctl function be called if you want to pass integer
values for the action and sig arguments.

RETURN VALUES
FSIGCTL returns an integer value corresponding to the previous signal action for the specified signal. It
returns – 1 if an improper action or sig argument is given, or if any other errors occur.

EXAMPLES
A frequent use of FSIGCTL is to catch the shutdown signal, as shown in the following example:
EXTERNAL CHE CKP T
CALL FSI GCTL(’REG IST ER’,’SIGSHUT DOWN’,CHECKP T)

CHECKPT is a user-supplied routine that tells the running program to write a checkpoint file at the next
possible time.

SEE ALSO
SIGOFF(3F)
sigctl(2), signal(2) in the UNICOS System Calls Reference Manual

482 004– 2165– 002

GETCALLERINFO ( 3F ) GETCALLERINFO ( 3F )

NAME
GETCALLERINFO – Returns the name and line number of the calling routine

SYNOPSIS
INTEGER ilen, lineno, ierror
CHARACTER*n, name
CALL GETCALLERINFO(name, ilen, lineno, ierror)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
The GETCALLERINFO subroutine returns the name of the subroutine and the line number from which the
current routine was called.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine:
ilen An integer variable that will receive the actual number of characters in the caller’s name
lineno An integer variable that will receive the line number of the calling subroutine
ierror An integer variable that will contain the exit status as defined in the EXIT STATUS section
name A variable of type CHARACTER that will receive the name of the calling subroutine

EXIT STATUS
Upon successful completion of this routine, ierror is set to 0. If any of the following conditions occur,
ierror is set to the corresponding value:
EINVAL An internal error prevented recovery of the caller information.
ETRUNC The caller’s name was longer than the length of the character variable provided by the user. As
much of the caller’s name as will fit is returned.

004– 2165– 002 483

GETCALLERINFO ( 3F ) GETCALLERINFO ( 3F )

EXAMPLES

PROGRA M MAI N_PROG RAM

CAL L SUB _ROUTI NE
END
SUBROU TINE SUB_RO UTINE
CHARAC TER * 50, NAM E
CALL GETCAL LERINF O(NAME, ILE N, LIN ENO , IER ROR )
IF (IE RRO R .EQ . 0) THE N
PRINT *,’Cal led from lin e ’, LIN ENO, ’ of ’, NAM E(1:IL EN)
END IF
RET URN
END

Execution of this program results in the following output:

Called from line 2 of MAIN_P ROG RAM

484 004– 2165– 002

GETPMC ( 3F ) GETPMC ( 3F )

NAME
GETPMC, GETTMC, GETHMC – Returns 128-word output array describing machine characteristics

SYNOPSIS
INTEGER GETPMC
INTEGER PMCTABLE(128)
INTEGER PMTNAME
i = GETPMC(pmctable, pmtname)
CALL GETHMC(pmctable)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
GETPMC returns a 128– word output array that describes the machine characteristics of pmtname.
GETHMC returns a 128– word output array that describes the machine characteristics of the machine (CPU)
you are currently using.
If pmtname is HOST, then pmctable contains information about the machine (CPU) you are running on. If
pmtname is TARGET and if the TARGET environment variable is not set, pmctable will contain the
information provided by a target system call with the first parameter equal to MC_GET_TARGET.
If the TARGET environment variable is set, its form is the following:
TARGET=[cpuname]{,[charac]}
For example, the following are all valid TARGET environment variables:
TAR GET =cray- ts
TAR GET=cr ay- ts,iee e
TAR GET=,m ems ize=33 554432

If the TARGET environment variable contains a cpuname, then pmctable will contain default information for
that machine, modified by any characteristics specified in the TARGET environment variable. If the TARGET
environment variable is set, but does not contain a machine name, or if the machine name is host, then
pmctable will contain information about the machine you are running on, modified by any characteristics
specified in the environment variable. See target(1) for more information about machine characteristics.
If pmtname is a valid machine name, then pmctable will contain default information about that machine.
When default information is returned, some of the fields in the target structure in <sys/target.h> may
not contain values.

004– 2165– 002 485

GETPMC ( 3F ) GETPMC ( 3F )

GETPMC returns 0 on error, – 1 on success.

The following is a list of valid arguments for this routine.
pmtname Input variable containing the primary machine name. The name must be left justified, and zero
terminated.
Valid values for pmtname include:
TAR GET
HOS T
CRA Y-C 90
CRA Y-T 3D
CRA Y-T S
CRA Y-T 3E
CRA Y-J 90
CRA Y-J SE

pmctable Output variable. The 128– word output array will contain the characteristics of the primary
machine type specified by pmtname. For a description of this array, see the target structure
defined in <sys/target.h>.
Both GETHMC and GETPMC are in libtarget.a. This library is not linked by default.

SEE ALSO
target(1), target(2)

486 004– 2165– 002

ICEIL ( 3F ) ICEIL ( 3F )

NAME
ICEIL – Returns integer ceiling of a rational number

SYNOPSIS
i=ICEIL(j, k)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
ICEIL is an integer function that returns the integer ceiling of a rational number formed by two integer
parameters.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
j The numerator of a rational number.
k The denominator of a rational number.
The value of function i is the smallest integer larger than or equal to j/k.

004– 2165– 002 487

ICPUSED ( 3F ) ICPUSED ( 3F )

NAME
ICPUSED – Gets task CPU time in real-time clock (RTC) ticks

SYNOPSIS
INTEGER itotalcp
itotalcp = ICPUSED( )

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
ICPUSED gets the user CPU time used by the calling task in real-time clock ticks.
The accuracy of ICPUSED is not affected by system interrupts.
This function is equivalent to the TSECND(3F) function except this returns the time in RTC ticks rather than
seconds; it returns the elapsed CPU time of the calling task.
For Cray T90 and Cray C90 series, CPU times returned by ICPUSED include wait-semaphore time. For all
other systems, CPU times returned by ICPUSED do not include wait-semaphore time.

SEE ALSO
cpused(3C) in the UNICOS System Libraries Reference Manual

488 004– 2165– 002

MOV ( 3F ) MOV ( 3F )

NAME
STRMOV, MOVBIT, MOVBITZ – Moves bytes or bits from one variable or array to another

SYNOPSIS
CALL STRMOV(src, isb, num, dest, idb)
CALL MOVBIT(src, isb, num, dest, idb)
CALL MOVBITZ(src, isb, num, dest, idb)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
STRMOV moves bytes from one variable or array to another. MOVBIT moves bits from one variable or array
to another.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
src Variable or array of any type except character, and of any length, containing the bytes or string
of bits to be moved.
isb Starting byte or bit in the src string. Specify an integer variable, expression, or constant greater
than 0. Bytes and bits are numbered from 1, beginning at the leftmost byte or bit position of
src. isb is one-based for STRMOV and MOVBIT and zero-based for MOVBITZ.
num An integer variable, expression, or constant that contains the number of bytes or bits to be
moved; it must be greater than 0.
dest Variable or array of any type except character, and of any length, that contains the starting byte
or bit to receive the data.
idb An integer variable, expression, or constant that contains the starting byte or bit to receive the
data; must be greater than 0. Bytes and bits are numbered from 1, beginning at the leftmost byte
or bit position of dest. idb is one-based for STRMOV and MOVBIT and zero-based for
MOVBITZ.

NOTES
These routines handle overlapping moves correctly.

004– 2165– 002 489

MOV ( 3F ) MOV ( 3F )

EXAMPLES

PROGRA M TES T
INTEGE R IBU FA(3),IA( 3)
DATA
+ IA/ 491856 866475 613494 8,
+ 493834 668028 464540 0,
+ 468 855566 164743 181 6/
* MOV BIT 1: Mov e 129 bit s from off set 8 to off set 5
IBUFA= 0
CAL L MOV BIT(IA(1) ,8, 129,IB UFA ,5)

* MOVBIT 2: Mov e 100 bits fro m off set 35 to offset 10

DO 202 J=1 ,3
202 IBU FA( J)= 0
CALL MOV BIT(IA (1) ,35 ,100,I BUFA,1 0)
* STRMOV 1: Mov e 8 bytes from byt e 5 to byt e 1
IBUFA= 0
CALL STR MOV(IA (1),5, 8,IBUF A,1)
* STRMOV 2: Mov e 8 bytes from off set 2 to offset 10
IBUFA= 0
CALL STR MOV(IA (1) ,2, 8,IBUF A,10)
END

The results:
MOVBIT 1:
IA= 042 102210 220221 202204 4
042 210420 220500 610403 0
040 421061 042021 104421 0
IBUFA= 001022 102202 212022 044 2
022104 202205 006104 030 2
004 000000 000000 000000 0

MOVBIT 2:
IA= 042102 210220 221202 204 4
042210 420220 500610 403 0
040421 061042 021104 421 0
IBU FA= 000 044240 441104 221042 0
044 120142 100604 000000 0
000000 000000 000000 000 0

490 004– 2165– 002

MOV ( 3F ) MOV ( 3F )

STRMOV 1:
IA= 042 102210 220221 202 2044
042 210420 220500 610 4030
040 421061 042021 104 4210
IBU FA= 011050 110 221 044 210404 4
000 000 000000 000 000 000 0
000 000 000000 000 000 000 0

STRMOV 2:
IA= 042102 210 220221 202 204 4
042210 420 220500 610 403 0
040421 061 042021 104 421 0
IBU FA= 000000 000000 000 000 0000
000102 210 220 221202 2044
042000 000 000 000000 0000

004– 2165– 002 491

MTTS ( 3F ) MTTS ( 3F )

NAME
MTTS – Converts machine time (real-time clock value) to time stamp

SYNOPSIS
INTEGER MTTS, ts, irtc, cptype, cpcycl
ts=MTTS(irtc [, cptype, cpcycl])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
MTTS converts machine time (real-time clock value) to a time stamp.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ts 64-bit integer result containing a time stamp in nanoseconds.
irtc 64-bit integer real-time clock value to be converted to a time stamp in nanoseconds.
cptype CPU type (not implemented under the UNICOS operating system). The CPU type is the host
machine.
cpcycl Integer specifying the CPU cycle time in picoseconds.
The integer function MTTS converts a real-time clock value irtc to a time stamp ts using cpcycl. If cpcycl is
not present, MTTS uses the clock cycle time for the system on which the executable is running.
The input ts and the result irtc may be larger than 48 bits.

NOTES
Time stamp routines are invalid for dates later than 1999.

SEE ALSO
dtts(3F), tsdt(3F), tsmt(3F), unitts(3F)

492 004– 2165– 002

MVC ( 3F ) MVC ( 3F )

NAME
MVC – Moves characters from one memory area to another

SYNOPSIS
CALL MVC(s1, j1, s2, j2, k)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
MVC moves characters from one memory area to another.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
s1 Word address of the source string.
j1 Byte offset from the source string word address of the first byte of the source string (the high-order
byte of the first word of the source string is byte 1).
s2 Word address of the destination string.
j2 Byte offset from the destination string word address of the first byte of the destination string (the
high-order byte of the first word of the destination string is byte 1).
k Number of bytes to be moved.
Source and destination strings can occur on any byte boundary. The move is performed 1 character at a
time, from left to right, so MVC is optimal only for certain types of overlapping moves.

EXAMPLES
To copy the first byte of an array throughout the array, invoke the routine as follows, where K is the length
of the array in bytes:
CALL MVC(AR RAY ,1,ARR AY,2,K -1)

004– 2165– 002 493

PACK ( 3F ) PACK ( 3F )

NAME
PACK – Compresses stored data

SYNOPSIS
CALL PACK(p, nbits, u, count)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
PACK takes partial word items and packs them into 64-bit words.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
p On exit, vector of packed data.
nbits Number of rightmost bits of data in each partial word; must be 1, 2, 4, 8, 16, or 32.
u Vector of partial words to be compressed.
count Number of partial word items to be compressed.
PACK takes the 1, 2, 4, 8, 16, or 32 rightmost bits of several partial words and concatenates them into 64-bit
words. The following equation gives the number of full words:

(count .nbits )
n =
64

n Number of resulting full words

count Number of partial words
nbits Number of rightmost bits of each partial word that contains useful data

494 004– 2165– 002

PACK ( 3F ) PACK ( 3F )

If count .nbits is not a multiple of 64, the final partial word items will be left-justified, zero-filled.

SEE ALSO
UNPACK(3F)

004– 2165– 002 495

P32 ( 3F ) P32 ( 3F )

NAME
P32, U32 – Packs or unpacks 32-bit words into or from Cray 64-bit words

SYNOPSIS
CALL P32(src, dest, num)
CALL U32(src, dest, num)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
P32 packs 32-bit words into Cray 64-bit words. U32 unpacks 32-bit words from Cray 64-bit words. The
PACK(3F) and UNPACK(3F) routines provide similar functionality.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
src For P32, a variable or array of any noncharacter type and of any length containing 32-bit words,
left-justified in a Cray 64-bit word. For U32, a variable or array of any type or length
containing 32-bit words as a continuous stream of data. Unpacking always starts with the
leftmost bit of src.
dest For P32, a destination array of any type to contain the packed 32-bit words as a continuous
stream of data. For U32, a destination array of any type to contain the unpacked 32-bit words,
left-justified and sign-filled in a Cray 64-bit word.
num Number of 32-bit words to pack or unpack. The routine reads this many elements of src or
generates this many elements of dest. Specify an integer variable, expression, or constant.

SEE ALSO
PACK(3F), UNPACK(3F)

496 004– 2165– 002

P6460 ( 3F ) P6460 ( 3F )

NAME
P6460, U6064 – Packs or unpacks 60-bit words into or from Cray 64-bit words

SYNOPSIS
CALL P6460(src, dest, isb, num [,stride])
CALL U6064(src, isb, dest, num [,stride])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
P6460 packs 60-bit words into Cray 64-bit words. U6064 unpacks 60-bit words from Cray 64-bit words.
Arguments must be addressed in the same order in which they appear in the SYNOPSIS section.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following arguments are used with this routine:
src Variable or array of any noncharacter type and of any length containing 60-bit words,
left-justified in a Cray 64-bit word. For U6064, words are accepted as a continuous stream of
data.
dest For P6460, a destination array of any type to contain the packed 60-bit words as a continuous
stream of data. For U6064, a destination array of any type to contain the unpacked 60-bit
words, left-justified and sign-filled in a Cray 64-bit word.
isb Bit location that is the leftmost storage location for the 60-bit words. Bit position is counted
from the left to right, with the leftmost bit 0. Specify an integer variable, expression, or
constant.
num Number of 60-bit words to pack or unpack. The routine reads this many elements of src or
generates this many elements of dest. Specify an integer variable, expression, or constant.
stride Optional stride parameter for the dest array (U6064) or the src array (P6460). If not specified,
a stride of 1 is used.

004– 2165– 002 497

REPRIEVE ( 3F ) REPRIEVE ( 3F )

NAME
REPRIEVE – Describes error handling under the UNICOS and UNICOS/mk operating system

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
On UNICOS and UNICOS/mk systems, program errors (like floating-point errors, operand range errors, and
so on) can be handled by two mechanisms: core files or tracebacks. By default, all programs that use
Fortran I/O are loaded with the traceback code, and all other programs do not contain this code.
If the traceback code is loaded with a program, error conditions that would normally cause a fatal signal to
be sent are caught by a tracer routine. This tracer routine prints out the error condition and then gives a
traceback before aborting the program with a core dump. If the enhanced traceback mechanism is used (only
on UNICOS systems), the tracer routine prints out a more complete error status (including the P, A, S, VM,
and VL registers at the point of interrupt) and a traceback that includes routine arguments. It then flushes
buffers and ends execution of the program without a core dump (so no post-mortem debugging is available).
The following environment variables are available to change the characteristics of the traceback mechanism:
TRACEBK If set to 0, errors will cause a core dump but no traceback. If you intend to use a debugger to
debug your applications, or if you want to restart your core files, you should set this variable
to 0.
TRACEBK2 If set to nonzero (and TRACEBK is not set to 0), programs on UNICOS systems will use the
enhanced traceback mechanism.
The variables below are used to customize an enhanced traceback and are available only on UNICOS
systems if the TRACEBK2 variable is also set:
TRBKCORE If set to nonzero, it will give both a traceback and a core dump on encountering an error.
TRBKVEC If set to nonzero, the vector registers will be printed along with the other registers.
TRBKSIGS This variable can be used to alter the set of signal numbers that will cause a traceback to
occur. Its format is a list of numbers separated by commas; positive numbers in the list will
be added to the set of signal numbers, and negative numbers will be removed from the set of
signal numbers.

NOTES
The reprieve mechanism goes through all of the clean-up routines that would be run under abort(3C)
processing, including all of the routines registered by atabort(3C). Because all open files are flushed and
closed during this time, restarting a core file that is the result of reprieve processing will not work. For a
checkpoint/restart mechanism that is controllable by a signal, see SHUTDSAV(3F).

498 004– 2165– 002

REPRIEVE ( 3F ) REPRIEVE ( 3F )

EXAMPLES
Example 1: To get the enhanced traceback mechanism working for a C program, follow this example:
cc -c pro g.c
seg ldr -D’har dre f=_reprin it’ prog.o
env TRA CEBK2= 1 a.o ut

Example 2:
f90 pro g.f
seg ldr prog.o
a.o ut
<Tr acebac k+c oredum p pro duced>

env TRA CEB K=0 a.o ut

<No traceb ack pro duc ed, just a cor e dum p>

TRA CEBK2= 1; export TRACEBK2

<CR AY Y-MP sys tems onl y, to get an enhanced tra ceback>

a.o ut
<Enhan ced sty le tra ceback , no cor e file pro duced>

env TRB KCORE= 1 a.out

<Gets a tra ceback and a core fil e>

env TRB KVEC=1 a.o ut

<Pr int s out vec tor regist ers with tra ceback>

env TRB KSIGS= 8,- 7 a.out

<Ad ds signal 8, removes sig nal 7 from the set of
tra ceback sig nals>

SEE ALSO
TRACEBK(3F) (the Fortran interface), signal(2) for a list of signals
abort(3C), SHUTDSAV(3F)

004– 2165– 002 499

SECOND ( 3F ) SECOND ( 3F )

NAME
SECOND – Returns elapsed CPU time

SYNOPSIS
All systems:
second=SECOND()
UNICOS systems:
CALL SECOND(second)

IMPLEMENTATION
UNICOS, UNICOS/mk and IRIX systems

DESCRIPTION
SECOND returns the elapsed user CPU time as a real number in seconds (a default REAL*4) since the start
of a program, including time accumulated by all processes in a multitasking program.
SECOND returns execution time only for the current program. For example, a script runs a 50-second
program 10 times. A SECOND call at the end of the 10th run (or 1st or 3rd or 7th) returns 50 seconds.
On UNICOS systems, SECOND is not appropriate for timing small timed regions. If the timed region is
fewer than 4000 clock periods (CPs) in duration, the variation in the accuracy of SECOND can be 10% or
more on one processor. On multiple processors, the variation can be on the order of 10,000 to 400,000 CPs.
The second argument is the result, or CPU time (in type real seconds) accumulated by all processes in a
program.

NOTES
On UNICOS systems, the initial call to SECOND may take longer than subsequent calls due to certain
initializations performed by the routine. If the cost of calling SECOND is important, ignore the initial call
when computing SECOND’s time. The calculation of OVERHEAD in the second example, following, serves
this purpose. On UNICOS systems, the CPU times gathered by SECOND include wait-semaphore time.

WARNINGS
If you are trying to time your entire program, and you are using Autotasking, the CPU time returned by
SECOND may not reflect all of the CPU time used by your program. This is due to the fact that slave CPUs
may be still active when your program terminates (for instance, with a STOP or END statement). Depending
on the number of active CPUs on your machine, the extra time needed to terminate the slaves may be
substantial compared with your program time. Thus, if you use SECOND to time your program, and you are
also using time(1) or ja(1), the time reported by these other utilities could be much higher than that
reported by SECOND.

500 004– 2165– 002

SECOND ( 3F ) SECOND ( 3F )

Because of the large variation on multiple processors, SECOND should be used cautiously in multitasked
routines. On IRIX systems, the presence of multitasking does not affect the accuracy of SECOND.

EXAMPLES
Example 1: This example calculates the CPU time used in DOWORK:
BEFORE = SEC OND ( )
CALL DOW ORK( )
AFT ER = SECOND ( )
CPU TIME = AFTER - BEFORE

Example 2: If the CPU time is small enough that the overhead for calling SECOND may be significant, the
following example is more accurate:
T0 = SEC OND ( )
OVERHE AD = SEC OND ( ) - T0
BEF ORE = SECOND ( )
CAL L DOW ORK ( )
AFTER = SECOND ( )
CPUTIM E = (AF TER - BEF ORE ) - OVE RHE AD

SEE ALSO
RTC(3I), SECONDR(3F), TIMEF(3F), TSECND(3F)
ja(1), time(1) in the UNICOS User Commands Reference Manual

004– 2165– 002 501

SECONDR ( 3F ) SECONDR ( 3F )

NAME
SECONDR – Returns elapsed wall-clock time in seconds

SYNOPSIS
All systems:
REAL (KIND=8) SECONDR
time=SECONDR( )
UNICOS systems:
CALL SECONDR(time)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libffio.so which is linked by default when compiling programs with
the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
SECONDR can be called several times during the execution of a program to determine the amount of elapsed
wall-clock time.
time is the real-time clock values in floating-point seconds. If the value of the real-time clock exceeds 48
bits, some accuracy may be lost during the conversion to float. The argument must be of type real with
KIND=8.
On UNICOS/mk systems, the real-time clocks on processing elements are not synchronized with each other.
Therefore, a SECONDR() value should not be compared to a previous SECONDR() taken on a different
processing element.
EXAMPLES
This example calculates the elapsed wall-clock time from the first call to SECONDR until the second call to
SECONDR.
BEFORE = SECOND R( )
CALL DOW ORK ( )
AFTER = SECOND R( )
WALTIM = AFT ER - BEF ORE

SEE ALSO
RTC(3I), SECOND(3F), TIMEF(3F), TSECND(3F)

502 004– 2165– 002

SETPLIMQ ( 3F ) SETPLIMQ ( 3F )

NAME
SETPLIMQ – Initiates a detailed tracing of each call and return

SYNOPSIS
SETPLIMQ(lines)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SETPLIMQ writes trace lines to stderr. Calling this routine only affects flowtracing. Perftrace contains
this routine name, but calling it has no effect.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
lines Integer specifying the number of traces to display. Passing a negative number gives
unpredictable results.

004– 2165– 002 503

SHUTDSAV ( 3F ) SHUTDSAV ( 3F )

NAME
SHUTDSAV – Sets up the calling program to be checkpointed on system shutdown

SYNOPSIS
CALL SHUTDSAV(path, flags)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SHUTDSAV establishes a signal handler that catches the SIGSHUTDN signal, indicating that the system is
going to shut down soon. The signal handler, upon receipt of the SIGSHUTDN signal, checkpoints the
program using the chkpnt(2) system call, creating a restart file with the specified name.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
SHUTDSAV has the following arguments:
path Character string path name of the file to be created as the restart file. The path argument must
not refer to a file that already exists, since the chkpnt(2) system call that performs the actual
checkpoint work will not overwrite an existing file. If path does not designate an absolute path
name, then the restart file will be created relative to the current working directory of the calling
program at the time that the SIGSHUTDN signal is received. Finally, the directory in which the
restart file is to be created must be writable by the caller for the checkpoint to be successful.
flags Control options. Specify an integer variable or constant. If the least-significant bit of flags is 0,
the calling program will not checkpoint itself upon a system shutdown if it is running as part of
an Network Queuing System (NQS) batch job. This is important because, by default, NQS
checkpoints all of the jobs under its control upon a system shutdown, making any additional
checkpoint work by the program unnecessary. Alternatively, if the least-significant bit of flags is
set, the calling program will try to checkpoint itself, even when running as part of an NQS batch
job. In all other cases, the calling program will try to checkpoint itself upon the receipt of a
SIGSHUTDN signal. Finally, all bits other than the least-significant bit of flags are reserved for
future use, and they should be set to 0.

NOTES
Certain conditions must be satisfied for a process to be successfully checkpointed. See chkpnt(2) in the
UNICOS System Calls Reference Manual, for a discussion of the restrictions placed on a process that is to be
checkpointed.

504 004– 2165– 002

SHUTDSAV ( 3F ) SHUTDSAV ( 3F )

SEE ALSO
chkpnt(1), restart(1) in the UNICOS User Commands Reference Manual
chkpnt(2), restart(2), sigctl(2) in the UNICOS System Calls Reference Manual

004– 2165– 002 505

SIGOFF ( 3F ) SIGOFF ( 3F )

NAME
SIGOFF, SIGON – Controls receipt of signals

SYNOPSIS
INTEGER oldstat
CALL SIGOFF
CALL SIGON

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SIGOFF and SIGON allow signals to be deferred without issuing a system call. SIGOFF prevents the
receipt of all signals that have a signal handler registered for them; however, all signals that terminate or
cause a core dump of the process will be delivered.
Use these routines for coding critical sequences. Both routines return the previous signal status; a nonzero
value means signals are deferred.
SIGON allows receipt of signals after a SIGOFF or within a signal handler.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.

EXAMPLES

INT EGER OLDSTA T, SIG OFF, SIG ON

OLD STAT = SIG OFF()
C < Cri tical reg ion of code>
IF(OLD STAT .EQ. 0) CAL L SIG ON

SEE ALSO
sigoff(3C) in the UNICOS System Libraries Reference Manual
signal(2), pause(2) in the UNICOS System Calls Reference Manual

506 004– 2165– 002

STOP_ALL ( 3F ) STOP_ALL ( 3F )

NAME
STOP_ALL – Stops all PEs in an application

SYNOPSIS
CHARACTER*n message
CALL STOP_ALL([message])
CALL STOP_ALL_DISABLE()
CALL STOP_ALL_ENABLE()

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
The STOP_ALL subroutine causes a program to run all cleanup routines (including flushing I/O buffers),
print out a message (saying where it was called from), and exit. If called from a single processing element
(PE), STOP_ALL causes all PEs in a multi-PE application to run their cleanup routines and exit, even if
called from a parallel region. This differs from the STOP intrinsic in that STOP causes all PEs to exit if
called from a master region, but will only cause the calling PE to exit if called from a parallel region.
Many library routines may not safely be interrupted by a STOP_ALL request from another PE; unexpected
results might occur if they are interrupted. The user can call STOP_ALL_DISABLE to block any
STOP_ALL requests on the calling PE; when STOP_ALL_ENABLE is called, any pending or new
STOP_ALL requests will be acted on.
The STOP_ALL function has the following optional argument:
message String to be printed as part of the STOP_ALL message line

RETURN VALUES
STOP_ALL returns no value.

SEE ALSO
exit(3C)

004– 2165– 002 507

SYMDEBUG ( 3F ) SYMDEBUG ( 3F )

NAME
SYMDEBUG – Produces a symbolic snapshot of a running process

SYNOPSIS
CALL SYMDEBUG(’param{,param}.’)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SYMDEBUG is a library routine that produces the same sort of output as debug. SYMDEBUG is provided on
the UNICOS operating system primarily to ease migration of applications from COS; new code should use
SYMDUMP(3F), which is designed for use with the UNICOS operating system.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems, the default kind is KIND=8 for integer, real, complex, and
logical arguments.
This routine takes the following arguments:
param SYMDEBUG parameters. param may be entered in either uppercase or lowercase.
Some SYMDEBUG parameters allow you to specify a value along with the parameter. In these
cases, param=value substitutes for param. In param=value, in which value is a symbol, value is
case-sensitive.
SYMDEBUG uses the following parameters:
S=sfile Specifies the file containing the Debug Symbol tables. The default is a.out.
L=lfile Specifies the file to receive the listing output from the symbolic debug routine. By default,
SYMDEBUG output is written to stdout.
CALLS=n Number of routine levels to be looked at in a symbolic dump. For each known task,
SYMDEBUG traces back through the active subprograms the number of levels specified by n.
Routines for which no symbol table information is available are not counted for purposes of the
CALLS count. If this parameter is omitted, or if CALLS is specified without a value, the default
is 50.
SYMS=sym{:sym}
List of symbols to be dumped by SYMDEBUG. Up to 20 symbols (syms) can be specified, and
there is no limit on the length of the symbol names. Separate individual syms with a colon.
SYMS applies to all blocks dumped; by default, all symbols are dumped.
With regard to case, syms must be entered in exactly the way the symbol names appear in the
Debug Symbol table. Symbol names might not appear in the Debug Symbol table in the same
way they appear in your program. Fortran and Pascal always convert names to uppercase.

508 004– 2165– 002

SYMDEBUG ( 3F ) SYMDEBUG ( 3F )

NOTSYMS=nsym{:nsym}
List of symbols to skip. Up to 20 symbols (nsyms) can be specified, and there is no limit on the
length of the symbol names. Separate individual nsyms with a colon. The default skips no
symbols. This parameter takes precedence over the SYMS parameter.
With regard to case, nsyms must be entered in exactly the way the symbol names appear in the
Debug Symbol table. Symbol names might not appear in the Debug Symbol table in the same
way they appear in your program. Fortran and Pascal always convert names to uppercase.
MAXDIM=dim{:dim}
Maximum number of elements from each dimension of the arrays to be dumped. MAXDIM lets
you sample the contents of arrays without creating huge amounts of output. When MAXDIM is
specified, arrays are dumped in storage order (row, column for Pascal; column, row for Fortran).
MAXDIM applies to all blocks dumped. The default is MAXDIM=20:5:2:1:1:1:1. No more
than 7 dimensions can be specified.
BLOCKS=blk{:blk}
List of Fortran common blocks to be included from the symbolic dump. A maximum of 20
blocks can be specified. Separate the blks with colons. All symbols (qualified by the SYMS and
NOTSYMS parameters) in the named blocks are dumped. Default is no common blocks dumped;
if you specify BLOCKS without any blks, all common blocks declared in routines to be dumped
are included in the symbolic dump.
blk must be entered in uppercase.
NOTBLKS=nblk{:nblk}
List of Fortran common blocks to be excluded in the symbolic dump. A maximum of 20 blocks
can be specified. Separate the nblks with colons. This parameter is used in conjunction with
BLOCKS and takes precedence over the BLOCKS parameter.
nblk must be entered in uppercase.
RPTBLKS Repeat blocks; when this option is used, the contents of Fortran common blocks specified with
the BLOCKS and NOTBLKS parameters are displayed for each subroutine in which they are
declared. The default displays common blocks only once.
PAGES=np Page limit for the symbolic dump routine. Under the UNICOS operating system, SYMDEBUG
does not format output in pages. However, this parameter can still be used to regulate the
amount of output that SYMDEBUG generates. Each page is worth 45 lines of output from
SYMDEBUG. The default np is 70.

NOTES
Specify library libdb.a, which contains SYMDEBUG, on the -l option when you load your program. See
the examples on loading in the NOTES section of the SYMDUMP(3F) man page.

004– 2165– 002 509

SYMDEBUG ( 3F ) SYMDEBUG ( 3F )

EXAMPLES
The following are example calls from Fortran to SYMDEBUG:
CALL SYMDEB UG(’CA LLS=40,RP TBLKS. ’)

CAL L SYM DEBUG( ’BL OCKS=A A:BB:C C.’)

SEE ALSO
SYMDUMP(3F)

510 004– 2165– 002

SYMDUMP ( 3F ) SYMDUMP ( 3F )

NAME
SYMDUMP – Produces a symbolic snapshot dump of a running program

SYNOPSIS
CALL SYMDUMP (’-b blklist -B -c calls -d dimlist -l lfile -r -s symfile -V -y symlist -Y’,
abort_flag)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SYMDUMP is a library routine that produces the same sort of output as debug. It accepts C character
descriptors, Fortran Hollerith strings, and Pascal packed character arrays.
The method of calling library routines differs from language processor to language processor, but SYMDUMP
accepts the same arguments regardless of the language processor. The argument string, if provided, must be
enclosed in parentheses, and the options (excluding the Abort flag) must be enclosed in quotation marks.
When calling SYMDUMP from Fortran or Pascal, the quotation marks must be single; when calling from C,
the quotation marks must be double. All arguments are optional.
The options indicate the type and extent of information to be dumped by SYMDUMP. The options string is
passed to SYMDUMP in one of the following forms:
• As a character descriptor, produced by Fortran and C for defined character strings
• As an address of a null-terminated string, such as an integer, Hollerith, or Pascal packed character array
The argument string can contain a maximum of 4096 characters. All options are optional, and they may
appear in any order.
Unlike command lines, SYMDUMP option-arguments may not be grouped after one hyphen on the SYMDUMP
call. That is, SYMDUMP(’-V -r’) is permitted, but SYMDUMP(’-Vr’) is not permitted.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems, the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following are valid options and arguments:
-b blklist
-B These options control the displaying of Fortran common block symbols and may occur anywhere
in the option string in any order. The symbols to be displayed from any particular common
block depends on the use of the -Y and -y symlist options.

004– 2165– 002 511

SYMDUMP ( 3F ) SYMDUMP ( 3F )

If neither option is specified, no Fortran common blocks are included in the symbolic dump.
This is the default. If -B is specified, all Fortran common blocks are included in the symbolic
dump. If -b blklist is specified, only the Fortran common blocks named in blklist are included
in the symbolic dump. If both options are specified, all Fortran common blocks are included in
the symbolic dump, except those in blklist.
blklist may have up to 20 Fortran common blocks named. There is no limit on the length of a
common block name. The common blocks named in blklist must be separated by commas (for
example: -b c,d).
The common blocks named by blklist must be entered in uppercase letters.
-c calls An integer that specifies the number of routine levels to be displayed in the symbolic dump. For
each known task, SYMDUMP traces back through active routines the number of levels specified
by calls. Routines for which no symbol table information is available are not counted for
purposes of the routine level count. The default is 50.
-d dimlist A list of integers that specifies the maximum number of elements from each dimension of the
arrays to be dumped. SYMDUMP can dump array elements from up to seven dimensions. The
dimensions must be specified by integer values, and the values must be separated by commas
(for example: -d 4,6).
This option lets you sample the contents of an array without creating huge amounts of output.
dimlist applies to all blocks dumped, and the arrays are dumped in storage order. The default is
20,5,2,1,1,1,1.
-l lfile Names an output file. Specifying -l file directs SYMDUMP to write output to the specified file.
If you call SYMDUMP more than once, and you specify -l with the same file each time,
SYMDUMP output will be appended to the file each time. By default, SYMDUMP output is written
to stdout.
-r Repeat blocks. When this option is used, SYMDUMP displays the contents of Fortran common
blocks specified with -B and -b blklist for each subroutine in which they are declared. The
default displays common blocks only once.
-s symfile Names a file containing the Debug Symbol tables. There is no limit on the length of the symfile
file name, and it may include a path name to the desired file. segldr puts both the symbol
table information and the executable binary in the same file. By default, Debug Symbol tables
are written to a.out.
-V With -V specified, SYMDUMP generates SYMDUMP release statistics.
-y symlist
-Y These options control the displaying of symbols and may occur anywhere in the option string in
any order.
If neither option is specified, all symbols are displayed. This is the default. If only the -Y
option is specified, no symbols are displayed. If only the -y option is specified, all symbols
except those named in symlist are displayed. If both options are specified, only the symbols
named in symlist are displayed.

512 004– 2165– 002

SYMDUMP ( 3F ) SYMDUMP ( 3F )

The symlist variable may contain up to 20 named symbols, and there is no limit to the length of
the symbol names. The symbols named in symlist must be separated by commas (for example:
-y a, b).
Enter the symbols in the same case in which they appear in the symbol table. Names may not
always appear in the symbol table in the same way they appear in your program. Fortran and
Pascal always convert names to uppercase.
abort_flag An optional abort_flag variable indicates to SYMDUMP whether or not to abort if it finds an error
when parsing the SYMDUMP statement. An abort_flag with a value of 0 indicates no abort; an
abort_flag with a nonzero value indicates abort.
You cannot enter an abort_flag variable if you have not entered any options.
By default, SYMDUMP examines all options, reports errors found, and generates a dump based on
the options it could understand; the program does not abort.
Note that the abort_flag variable is not allowed when the option string is a Pascal variant array.

NOTES
Specify library libdb.a, which contains SYMDUMP, on the -l option when you load your program.
The following three examples show how to load programs that call SYMDUMP.
Example 1: If you are not expanding blank common and do not need to specify a segldr
HEAP directive on the segldr command line for any other reason, you do not need to specify a segldr
HEAP or STACK directive. The following example shows a segldr command line without HEAP or
STACK directives:
seg ldr -l db. a *.o

Example 2: If you are expanding blank common, you need to specify stack and heap sizes to segldr. The
following example shows a segldr command line that can be used if the program expands blank common.
seg ldr -l db. a -D "STACK =30 00+0;H EAP=10000 +0" *.o

This example shows settings that should provide enough stack and heap space for SYMDUMP to run,
assuming that your program is an average large application that has as many as 1000 blocks. For
applications with more blocks, 6 to 7 words per block over 1000 should be added to the heap setting.
Optimal heap settings depend on the specific application.
If running the application causes SYMDUMP to exit with the following error message, the value on the HEAP
directive is too small:
HPA LLOC failed ; ret urn status = i

004– 2165– 002 513

SYMDUMP ( 3F ) SYMDUMP ( 3F )

Example 3: If a segldr DYNAMIC directive is used, the stack and heap cannot expand, so a segldr
STACK or HEAP directive may also be needed. See the previous example for information about expanding
the stack and heap. To load the heap prior to blank common, use DYNAMIC=// on segldr’s -D option,
as shown in the following example:
segldr -l db.a -D "DY NAM IC= //" *.o

Both libdb.a and libp.a are required if ld(1) or cc(1) is used.

EXAMPLES
Example 1: The following example shows how to call SYMDUMP from a Fortran program when passing a
character descriptor:
charac ter *30 str ing
intege r abt fl
.
.
str ing = ’-s tes t -B -b STR ING’
abt fl = 1
.
.
C CHARAC TER VARIAB LE
call sym dump (strin g, abt fl)
.
.
C CHARAC TER CON STANT
call symdum p (’- l out fil e -V’ )

Example 2: The following example shows how to call SYMDUMP from C:

extern voi d SYM DUM P( );

int abt_fl ag = 1;
cha r *strin g;

string = "-s a.o ut -V" ;

SYMDUMP (strin g, &ab t_f lag );

514 004– 2165– 002

SYMDUMP ( 3F ) SYMDUMP ( 3F )

Example 3: The following example shows how to call SYMDUMP from Pascal when passing a conformant
array:
type
str ing_ty pe = pac ked arr ay [1. .30 ] of cha r;
var
abo rt_fla g: boo lea n;

pro cedure sym dump (va r str ing : str ing_ty pe; var flag: boolea n);
import ed (SY MDU MP);

abort_ flag := tru e;

string [1. .20] := ’-s test -y STR ING -Y’;
str ing [21 ] := chr (0) ; (* mus t nul l ter minate the str ing *)
symdum p (strin g, abo rt_fla g);

SEE ALSO
SYMDEBUG(3F)
For more information on segldr, see Segment Loader (SEGLDR) and ld Reference Manual.

004– 2165– 002 515

SYSCLOCK ( 3F ) SYSCLOCK ( 3F )

NAME
SYSCLOCK – Returns real-time clock value and number of wraps

SYNOPSIS
INTEGER ICOUNT, IWRAP
CALL SYSCLOCK (icount, iwrap)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
SYSCLOCK returns the same real-time clock count returned by the count argument to the Fortran 90
SYSTEM_CLOCK intrinsic subroutine.
On systems with default 32-bit integer data type, the real-time clock value for SYSTEM_CLOCK reaches
count_max and wraps around to 0 occasionally. The number of times that the clock has wrapped is returned
in iwrap. By using iwrap, you can reliably time intervals during which the clock may have wrapped one or
more times.
Use the count_rate argument on the SYSTEM_CLOCK intrinsic subroutine to determine the clock rate for
SYSCLOCK.
When using the CF90 compiler on UNICOS or UNICOS/mk system, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, default kind is KIND=8 for integer, real,
complex, and logical arguments.

RETURN VALUES
iwrap always returns 0 on 64-bit systems.

SEE ALSO
IRTC(3I), SYSTEM_CLOCK(3I), TIMEF(3F)

516 004– 2165– 002

TIMEF ( 3F ) TIMEF ( 3F )

NAME
TIMEF – Returns elapsed wall-clock time in milliseconds since the previous call to TIMEF

SYNOPSIS
REAL (KIND=8) TIMEF
timef=TIMEF()
UNICOS systems:
CALL TIMEF(timef)

IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
On IRIX systems, this routine is in libffio.so which is linked by default when compiling programs with
the MIPSpro 7 Fortran 90 compiler or when compiling programs with the -craylibs option to the
MIPSpro F77 compiler.
TIMEF returns the elapsed wall-clock time since a call to TIMEF.
The following is a list of valid arguments for this routine.
timef Elapsed wall-clock time (a real number in milliseconds) since the initial call to TIMEF. This
argument must be of type real. The initial call to TIMEF returns 0.0.

NOTES
If TIMEF calculates a negative value for the elapsed wall-clock time, it resets the initial value of the clock to
the current value of the lock and returns 0.0.

004– 2165– 002 517

TRACEBK ( 3F ) TRACEBK ( 3F )

NAME
TRACEBK – Prints a traceback

SYNOPSIS
CALL TRACEBK
or
INTEGER idepth
CALL TRACEBK(idepth)
or INTEGER idepth
CHARACTER*n filenm
CALL TRACEBK(idepth, filenm)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TRACEBK prints (on stdout) a traceback beginning with its caller and ending at "Start-up," or when idepth
is reached. The traceback includes the arguments and their values and some data about the run-time stack.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
TRACEBK has the following optional arguments:
idepth Integer expression containing trace depth; if no argument is used, or idepth is not in the range 3
to 50, 25 is used. idepth can have the following values:
<0 Trace depth equals 25
0 Print one line "Where am I" message
1 Print one line trace (caller’s name and line number)
2 Print "Where am I" and one line trace
>2 Trace depth (25 if above 50)
filenm Character variable containing the name of a file in which to write the traceback. idepth must be
present if filenm is present.
The optional filenm argument in the CALL to TRACEBK is a character variable containing the name of a file
in which TRACEBK() will write the traceback. filenm must not be open as a Fortran file when
TRACEBK() is called because the results are unpredictable. filenm may be read with standard Fortran I/O.

518 004– 2165– 002

TRACEBK ( 3F ) TRACEBK ( 3F )

MESSAGES
TRACEBK fails (with a message on stdout) if the trace data has been noticeably corrupted.

SEE ALSO
TRBK(3F) for information on listing the subroutines in a current calling sequence
REPRIEVE(3F) for a general description of reprieve processing, including descriptions of related
environment variables
STKSTAT(3C) in the UNICOS System Libraries Reference Manual

004– 2165– 002 519

TRBK ( 3F ) TRBK ( 3F )

NAME
TRBK – Lists all subroutines active in the current calling sequence

SYNOPSIS
CALL TRBK [(depth)]

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TRBK prints a list of all subroutines that are active in the current calling sequence from the currently active
subprogram. It also identifies the address of the reference. The list is printed to stderr.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
depth Optional argument that selects the maximum traceback depth. If not specified, the default is the
value of the TRBKDPTH environment variable (if defined) or 25 if the variable is not defined.

SEE ALSO
REPRIEVE(3F) for a description of UNICOS error handling
TRACEBK(3F) for information about the ability to write traceback information to an alternate file

520 004– 2165– 002

TRBKLVL ( 3F ) TRBKLVL ( 3F )

NAME
TRBKLVL – Returns information on current level of calling sequence

SYNOPSIS
CALL TRBKLVL(trbktab, arglist, status, name, calladr, entpnt, seqnum, numarg)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
TRBKLVL returns information on the current level of the calling sequence.
The following is a list of valid arguments for this routine.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
trbktab Current level’s traceback table address; on exit, current level caller’s traceback table address.
Returns a 0 if the current level is a main-level routine.
arglist Current level’s argument list address; on exit, current level caller’s argument list address.
Returns a 0 if the current level is a main-level routine.
status status can have the following values:
<0 Error
=0 No error
>0 No error and the current level is the main level
name Current level’s name (ASCII, left-justified, blank-filled). This may not be a Fortran character
variable.
calladr Parcel address from which the call to the current level was made.
entpnt Parcel address of the current level’s entry point.
seqnum Line sequence number corresponding to the call address (0 indicates none).
numarg Number of arguments or registers passed to the current level.

EXAMPLES
Using TRBKLVL from a Fortran program requires knowledge of the values of the traceback table address and
argument list address. This information is usually kept in B registers by the Fortran system. To get the
necessary information, you must use the getb1 and getb2 functions. These should be declared as integer
externals.

004– 2165– 002 521

TRBKLVL ( 3F ) TRBKLVL ( 3F )

Example of use:
int eger get b1, get b2
int ege r trb ktab,argl ist ,st atus,c alladr ,entpn t
int ege r seq num
c
c Get tra ceback table add res ses for this
c rou tine.
c
arg list=g etb1()
trb ktab=g etb 2()
c
c Cal ling trb klv l wil l return us the nam e
c and oth er inf ormation for this rou tine.
c
cal l trb klv l(trbktab ,ar gli st,sta tus,na me,cal lad r,
x entpnt ,se qnu m,numa rg)
c
c At this point, ’tr bkt ab’ and ’ar gli st’ contai n the se
c val ues for the routin e usi ng trbklv l. ’na me’ con tains
c the nam e of thi s rou tin e, and so on.
c
c Callin g trb klvl aga in wil l return the inform ation for
c the cal ler of thi s routin e.
c
cal l trb klv l(trbktab ,ar gli st,sta tus,na me,cal lad r,
x entpnt ,se qnu m,numa rg)
c
c At this point, ’tr bktab’ and ’argli st’ contai n the se
c values for the cal ler. ’na me’ con tai ns the nam e of
c the calling routin e, and so on.
c
c If we call trbklvl aga in, wit h the sam e parame ter s,
c the ret urn ed values wil l then con tain inf ormati on abo ut the
c cal ler ’s caller. We can con tinue this rep eated proces s until
c we reach the top of the cal ling tre e. At tha t poi nt, ’st atu s’
c will be a number gre ater than zer o, and the user sho uld stop
c cal lin g trbklv l. Otherw ise , the user wou ld loop indefinit ely.

Note that the name returned is truncated to 8 characters if it is longer than 8 characters.

SEE ALSO
TRBK(3F)

522 004– 2165– 002

TREMAIN ( 3F ) TREMAIN ( 3F )

NAME
TREMAIN – Returns the CPU time (in seconds of type real) remaining for the program

SYNOPSIS
CALL TREMAIN(result)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
This routine returns the CPU time remaining for the program.
result The calculated CPU time remaining. Type real.

NOTES
The time remaining is the lesser of the CPU time remaining for the current program, and the CPU time
remaining for the current process.
TREMAIN returns 0 after the time limit is exceeded and returns a large number if no CPU time limits are in
effect.

004– 2165– 002 523

TRIMLEN ( 3F ) TRIMLEN ( 3F )

NAME
TRIMLEN – Returns the length of a character argument without counting trailing blanks

SYNOPSIS
INTEGER trimlen
intlen = TRIMLEN(string)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
TRIMLEN is an integer function that returns the length of a character argument without counting the trailing
blanks. The function must be declared as type integer in the calling routine. The string argument must be
of type character.
This function is intended for use as part of the substring notation. Examples 2 and 3 show the TRIMLEN
function used in this manner. The value of each of the parts of the substring notation must be as follows:
1 ≤ leftmostpos ≤ rightmostpos ≤ stringlength

leftmostpos is the leftmost character position in the substring, rightmostpos is the rightmost character position
in the substring, and stringlength is the declared length of the character entity. TRIMLEN returns a value of
1 for a string of all blanks.

EXAMPLES
Example 1: A program using the function TRIMLEN could do the following:
INT EGE R TRI MLEN
CHA RACTER *80 STR ING
STR ING = ’ ’
STR ING(20 :47) = ’TE ST TRI MLEN LEN GTH RETURN ED’
INTLEN = TRI MLE N(STRI NG)
WRI TE( 6,1) INTLEN , STRING (1:INT LEN )
1 FOR MAT(’ LENGTH =’,I5,’ STR ING=’, A,’ -DONE’)
PRI NT 2,’ 123456 789012345 678901 234 567890123 456 789012345 678 90’
2 FOR MAT (21X,A )
END

The output of the program is as follows:

LEN GTH= 47 STR ING = TEST TRI MLEN LEN GTH RETURN ED-DONE
123456 789012 345678 901234 567890 123456 789012 345678 90

524 004– 2165– 002

TRIMLEN ( 3F ) TRIMLEN ( 3F )

Example 2: This example produces a string with the character < written following the last nonblank
character of STRING:
WRI TE( 6,901) STR ING (1:TRI MLE N(S TRI NG))
901 FOR MAT (’ The str ing is >’,A,’ <’)

Example 3: In this example, although NEW may have trailing blanks, the character < is written after the last
nonblank character in STRING:
NEW = STR ING(1: TRI MLEN(STRI NG) ) // ’< The end ’

004– 2165– 002 525

TSECND ( 3F ) TSECND ( 3F )

NAME
TSECND – Returns elapsed CPU time for a calling task or process

SYNOPSIS
second=TSECND()
CALL TSECND(second)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
On UNICOS systems, this routine returns the elapsed CPU time of a calling task since the start of that task.
On UNICOS/mk systems, this routine returns the elapsed CPU time of a calling process since the start of
that process.
When using the CF90 compiler on UNICOS or UNICOS/mk systems, all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, the default kind is KIND=8 for integer, real,
complex, and logical arguments.
This routine accepts the following argument:
second A real variable. second is the elapsed CPU time in seconds.
The initial call to TSECND may take longer than subsequent calls due to certain initializations performed by
the routine. If the cost of calling TSECND is important, ignore the initial call when computing TSECND’s
time.
TSECND only returns CPU time for the current task or process. It is your responsibility to determine which
task or process is running at the time the call is made. This call may not be useful in an Autotasking
environment, because the running user program does not know which task is actually executing the parallel
regions of code.
For Cray C90 series, CPU times returned by TSECND include wait-semaphore time. For all other systems,
CPU times returned by TSECND do not include wait-semaphore time. Contrast this with the SECOND(3F)
call.

526 004– 2165– 002

TSECND ( 3F ) TSECND ( 3F )

EXAMPLES
The following example calculates how much of the total execution time for a multitasked program is
accumulated by the calling process.
BEFORE = SEC OND ( )
TBE FORE = TSE CND ( )
CAL L DOW ORK ( ) ! The subrou tine DOW ORK or
AFT ER = SEC OND( ) ! someth ing it calls may be
TAF TER = TSE CND ( ) ! multit ask ed.
CPU = (AFTER - BEF ORE)
TCP U = (TAFTE R - TBE FORE)
MYP ORT ION = TCP U/C PU

SEE ALSO
RTC(3I), SECOND(3F), SECONDR(3F)

004– 2165– 002 527

TSDT ( 3F ) TSDT ( 3F )

NAME
TSDT – Converts time stamps to ASCII date and time strings

SYNOPSIS
CALL TSDT(ts, date, hhmmss, ssss)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
TSDT converts time stamps to ASCII date and time.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ts Time stamp on entry (type integer). This may not be Fortran character variable.
date Word to receive ASCII date in mm/dd/yy format. This may not be Fortran character variable.
hhmmss Word to receive ASCII time in hh:mm:ss format. This may not be Fortran character variable.
ssss Word to receive ASCII fractional seconds in .ssssnnn format

NOTES
Time stamp routines are invalid for dates later than 1999.

528 004– 2165– 002

TSMT ( 3F ) TSMT ( 3F )

NAME
TSMT – Converts time stamp to machine time (real-time clock value)

SYNOPSIS
INTEGER TSMT irtc, ts, cptype, cpcycl
irtc=TSMT(ts [, cptype, cpcycl])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
TSMT converts a time stamp to machine time (real-time clock value).
The following are valid arguments for this routine.
irtc 64-bit integer result of the conversion of the specified time stamp to a real-time clock value.
ts 64-bit integer specifying a time stamp in nanoseconds to be converted to a real-time clock value.
cptype CPU type (not implemented under the UNICOS operating system). The CPU type is the host
machine.
cpcycl Integer specifying CPU cycle time in picoseconds.
The integer function TSMT converts time stamp ts specified in nanoseconds to a number of clock ticks using
cpcycl. If cpcycl is not present, TMST uses the clock cycle time for the system on which the executable is
running.
The input ts and the result irtc may be larger than 48 bits.

NOTES
Time stamp routines are invalid for dates later than 1999.

SEE ALSO
DTTS(3F), MTTS(3F), TSDT(3F), UNITTS(3F)

004– 2165– 002 529

UNITTS ( 3F ) UNITTS ( 3F )

NAME
UNITTS – Returns time-stamp units in specified standard-time units

SYNOPSIS
INTEGER UNITTS
ts=UNITTS(periods, units)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
UNITTS returns time-stamp units in specified standard-time units.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
ts Number of time-stamp units in periods and units (type integer).
periods Number of time-stamp units to be returned in standard-time units (that is, number of seconds,
minutes, and so on); type integer.
units Specification for the units in which periods is expressed. The following values are accepted:
’DAYS’, ’HOURS’, ’MINUTES’, ’SECONDS’, ’MSEC’ (milliseconds), ’USEC’
(microseconds), ’USEC100’ (100s of microseconds). UNITTS may be a character variable or
type integer. If it is type integer, the values must be left-justified, blank-filled Hollerith.

EXAMPLES

ts= UNITTS (2,’DA YS’)

530 004– 2165– 002

UNPACK ( 3F ) UNPACK ( 3F )

NAME
UNPACK – Expands stored data

SYNOPSIS
CALL UNPACK(p, nbits, u, count[, sef])

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
UNPACK takes 64-bit words and extracts partial word items and places them right-justified into 64-bit words.
The items can be optionally sign-extended.
When using the CF90 compiler on UNICOS or UNICOS/mk systems all arguments must be of default kind
unless documented otherwise. On UNICOS and UNICOS/mk, default kind is KIND=8 for integer, real,
complex, and logical arguments.
The following is a list of valid arguments for this routine.
p Vector of full 64-bit words to be expanded.
nbits The number of rightmost bits of data in each partial word; must be 1, 2, 4, 8, 16, or 32.
u On exit, vector of unpacked data.
count Number of resulting partial words.
sef Optional sign extension flag. If .TRUE., items are sign-extended. If omitted or .FALSE., items
are not sign-extended.

SEE ALSO
PACK(3F)

004– 2165– 002 531

XPFMT ( 3F ) XPFMT ( 3F )

NAME
XPFMT – Produces a printable image of an exchange package

SYNOPSIS
CALL XPFMT(address, in, out, mode)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
XPFMT produces a printable image of an exchange package in a user-supplied buffer. A and S registers
appear in the buffer in both octal and character form; in the character form, the contents of the register are
copied unchanged to the printable buffer. The calling program is responsible for proper translation of
unprintable characters. Parcel addresses have a lowercase a, b, c, or d suffixed to the memory address.
When using the CF90 compiler on UNICOS systems, all arguments must be of default kind unless
documented otherwise. On UNICOS systems the default kind is KIND=8 for integer, real, complex, and
logical arguments.
The following is a list of valid arguments for this routine.
address The nominal location of the exchange package to be printed as the starting exchange package
address. The output buffer contains an 8-character field at the beginning of each line of the
exchange package to indicate a Cray Research address. The binary number in address is used
to fill these 8 characters of the first line of the exchange package in the output buffer and is
incremented to fill each succeeding line of the output buffer. This is not the address of the
16-word buffer containing the exchange package to be formatted.
in A 16-word integer array containing the binary representation of the exchange package.
out An integer array, dimensioned (8,0:23), into which the character representation of the exchange
package is stored. Line 0 is a ruler for debugging and is not usually printed.
The first word of each line is an address and need not always be printed.
mode An integer word indicating the mode in which the exchange package is to be printed. ’Y’L
forces the exchange package to be formatted as an exchange package; 0 means that the
subprogram is to use the exchange package contents to determine the machine type.

532 004– 2165– 002

XPFMT ( 3F ) XPFMT ( 3F )

EXAMPLES

SUBROU TIN E SUB 1(INTX P,OUTX P)

INT EGE R INT XP(16),OU TXP(8, 0:23), IADDR,IMO DE
*
* addres s to use in out put arr ay
*
IAD DR = 870 0
*
* let pro cessor ded uce mac hine typ e
*
IMODE = 0
*
* pass the input exc hange package to XPFMT and get the for matted
* versio n to pri nt in OUT XP
*
CAL L XPFMT( IADDR, INTXP, OUTXP,IMO DE)
*
* pri nt the out put of the XPF MT rou tine
*
PRI NT 1,OUTX P
1 FOR MAT (24(1X ,8A8/) )
END

004– 2165– 002 533

534 004– 2165– 002
INTRO_SYNC ( 3F ) INTRO_SYNC ( 3F )

NAME
INTRO_SYNC – Introduction to synchronization routines

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
Synchronization routines are used to synchronize processing elements (PE) within programs. This section
describes a set of synchronization primitives and timing routines that are available on UNICOS/mk systems.
For information about multitasking on systems other than UNICOS/mk systems, see the UNICOS System
Libraries Reference Manual.
Definitions
UNICOS/mk systems implement a special hardware barrier network to implement two types of barrier
synchronization operations: barriers and eurekas. A barrier is a point within a program where a task must
wait until all other tasks reach the barrier. A eureka is a point within a program where all tasks are
informed when one task has satisfied some condition. Eureka synchronization has several uses, including
database searches. Using eureka synchronization, a programmer can stop a database search as soon as any
task finds the data rather than waiting for all of the tasks to exhaust the search.
Two specific types of routines are used for event and barrier processing:
• Event routines: Event routines are used to record the state of a program’s execution and to communicate
that state to another task.
• Barrier routines: Barrier routines are used to synchronize the execution of all tasks. A task’s execution is
suspended at a barrier until all tasks have reached the barrier. The barrier routines use the UNICOS/mk
hardware barrier network. When adding a barrier to your program, be sure that all tasks will eventually
reach the barrier. If any of the tasks do not reach the barrier because of task-dependent conditions or
branches, the other tasks will wait at the barrier indefinitely or abort with a user deadlock error.

NOTES
UNICOS/mk synchonization routines are not generally thread-safe. When synchronization routines are used
in conjunction with pthreads, use pthreads locks around the calls.

SEE ALSO
UNICOS System Libraries Reference Manual
INTRO_SHMEM(3), SHMEM_CLEAR_EVENT(3), SHMEM_CLEAR_LOCK(3), SHMEM_SET_CODE(3),
SHMEM_SET_EVENT(3), SHMEM_TEST_EVENT(3), SHMEM_WAIT_EVENT.

004– 2165– 002 535

CLEAR_EVENT ( 3C ) CLEAR_EVENT ( 3C )

NAME
clear_event – Clears an event and returns control to the calling PE

SYNOPSIS
Fortran:
CALL CLEAR_EVENT
C:
void clear_event(void);

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
The clear_event function clears the eureka event and returns control to the calling processing element
(PE). The result of this is that PEs subsequently performing wait_event(3C) calls must wait. If a posted
eureka event is not cleared, the posted condition remains outstanding.
When the event routines are used, clear_event initializes the eureka barrier bit to the cleared state. All
PEs must call clear_event before any PE can test, wait, or post the eureka mode event. If any PEs fail
to call clear_event, the program’s behavior is undefined. Although all PEs must call clear_event
when using the event routines, PEs are not required to wait for the eureka event to be posted. However,
before another eureka activity can be started, all PEs must once again call clear_event to reinitialize the
eureka barrier bit.

536 004– 2165– 002

CLEAR_EVENT ( 3C ) CLEAR_EVENT ( 3C )

EXAMPLES
The following examples show the use of the clear_event function.
Example 1:
sea rch _data( )
{
long fla g;

/*
* All PEs must call clear_ eve nt() to initializ e
* the eureka barrie r.
*/

cle ar_eve nt( );

/*
* The fir st proces sor to ret urn from sea rch with a
* ret urn val ue of 0, wil l pos t the eureka event.
*/

whi le ((flag = search ()) != -1) {

/*
* If the eve nt is posted , exi t the while loo p.
*/

if (te st_event( )) {
flag = -1;
break;
}

/*
* If the sea rch is suc cessful, pos t the eve nt.
*/

if (fl ag == 0) {
set_ev ent ();
break;
}
}
}

004– 2165– 002 537

CLEAR_EVENT ( 3C ) CLEAR_EVENT ( 3C )

Example 2:
PRO GRA M MUL TI
C ...
CALL CLEAR_ EVENT( )
DO I=1 , MAX VAL
CALL GINK(R ESU LT,A(I ,1))
IF (RESUL T .EQ . SEA RCH_VAL) THE N
CALL SET_EV ENT ();
GOTO 20
END IF
IF (TE ST_ EVENT()) GOT O 20
END DO
CAL L WAI T_E VENT()
20 CON TIN UE
C ...
END

SEE ALSO
set_event(3C), test_event(3C), wait_event(3C)

538 004– 2165– 002

SET_BARRIER ( 3C ) SET_BARRIER ( 3C )

NAME
set_barrier – Registers the arrival of a PE at a barrier

SYNOPSIS
Fortran:
CALL SET_BARRIER
C:
void set_barrier();

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
This routine registers the arrival of a PE at a barrier. It waits for the completion of previously issued local
and remote stores. See shmem_barrier_all(3) for more details.

NOTES
Processing elements (PE) can spend time waiting at a barrier. To spend PE time at a barrier productively,
you can create your own barrier mechanism using set_barrier (SET_BARRIER) and wait_barrier
(WAIT_BARRIER). set_barrier indicates that the calling PE has arrived at the barrier;
wait_barrier suspends execution of the calling PE until all of the other PEs have arrived at the barrier.
You can place code between the two calls that will execute while waiting for other PEs to arrive at the
barrier. In this way, a PE can continue to do useful work after notifying that it has reached the barrier.
When it completes the extra work, the PE calls wait_barrier and waits, if necessary, for the remaining
PEs to reach the barrier.

SEE ALSO
shmem_barrier_all(3), test_barrier(3C), wait_barrier(3C)

004– 2165– 002 539

SET_EVENT ( 3C ) SET_EVENT ( 3C )

NAME
set_event – Posts an event and returns control to the calling PE

SYNOPSIS
Fortran:
CALL SET_EVENT
C:
void set_event(void)

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
All Processing Elements (PEs) must clear an event before any tasks can test, wait for, or post the event. All
PEs do not have to wait for an event to be posted. However, all PEs must once again clear the event before
another activity can begin.
When using the CF90 compiler on UNICOS/mk systems all arguments must be of default kind unless
documented otherwise. On UNICOS/mk systems, default kind is KIND=8 for integer, real, complex, and
logical arguments.

EXAMPLES

PROGRA M MUL TI
C ...
CALL CLEAR_ EVENT()
DO I=1 , MAX VAL
CALL GINK(R ESULT, A(I,1) )
IF (RE SULT .EQ . SEARCH _VAL) THEN
CAL L SET_EV ENT ();
GOT O 20
ENDIF
IF (TEST_ EVENT( )) GOT O 20
END DO
CAL L WAI T_EVEN T()
20 CON TINUE
C ...
END

540 004– 2165– 002

SET_EVENT ( 3C ) SET_EVENT ( 3C )

SEE ALSO
clear_event(3C), INTRO_SYNC(3F), wait_event(3C)

004– 2165– 002 541

TEST_BARRIER ( 3C ) TEST_BARRIER ( 3C )

NAME
test_barrier – Tests a barrier to determine its state (set or cleared)

SYNOPSIS

Fortran:
LOGICAL TEST_BARRIER
return=TEST_BARRIER()
C:
long test_barrier()

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
This barrier routine checks to see if all PEs have arrived at the barrier.
return A logical .TRUE. if all processors have arrived and set the barrier. A logical .FALSE. if all
processors have not set the barrier.

SEE ALSO
intro_sync(3F), set_barrier(3C), wait_barrier(3C)

542 004– 2165– 002

TEST_EVENT ( 3C ) TEST_EVENT ( 3C )

NAME
test_event – Returns the state of an event, either posted or cleared

SYNOPSIS
Fortran:
LOGICAL TEST_EVENT
return=TEST_EVENT
C:
long test_event(void)

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
Eureka events are potentially useful to signal the end of a search or other parallel activity where a single
success should end the attempt by all PEs. In eureka mode, the hardware barrier network is used for event
communication. This implies that TEST_EVENT is returning the state of the eureka barrier bit.
When using the CF90 compiler on UNICOS/mk systems, all arguments must be of default kind unless
documented otherwise. On UNICOS/mk, the default kind is KIND=8 for integer, real, complex, and logical
arguments.
return A logical .TRUE. if the event is set, .FALSE. otherwise. The TEST_EVENT routine will return
.FALSE. if the SHARED event control variable is in the busy state. An event control variable
can be in the busy state if another PE is executing a call to other event routines at the same time
the call to test_event occurs.

NOTES
TEST_EVENT and return must be declared as type LOGICAL in the calling module.

SEE ALSO
clear_event(3C), set_event(3C), wait_event(3C)

004– 2165– 002 543

WAIT_BARRIER ( 3C ) WAIT_BARRIER ( 3C )

NAME
wait_barrier – Suspends PE execution until all PEs arrive at the barrier

SYNOPSIS

Fortran:
CALL WAIT_BARRIER()
C:
void wait_barrier()

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
Processing Elements (PEs) can spend time waiting at a barrier. To spend PE time at a barrier productively,
you can create your own barrier mechanism using SET_BARRIER and WAIT_BARRIER. SET_BARRIER
indicates that the calling PE has arrived at the barrier; WAIT_BARRIER suspends execution of the calling
PE until all of the other PEs have arrived at the barrier.
You can place code between the two calls that will execute while waiting for other PEs to arrive at the
barrier. In this way, a PE can continue to do useful work after notifying that it has reached the barrier.
When it completes the extra work, the PE calls WAIT_BARRIER and waits, if necessary, for the remaining
PEs to reach the barrier. WAIT_BARRIER suspends PE execution until all PEs arrive at the barrier.
If WAIT_BARRIER is called from outside of a parallel region, the user program will deadlock.
WAIT_BARRIER must be called from within a parallel region and all PEs must participate. The user can
guard against calling WAIT_BARRIER from outside of a parallel region with the use of the IN_PARALLEL
compiler intrinsic.

SEE ALSO
barrier(3C), set_barrier(3C), test_barrier(3C)

544 004– 2165– 002

WAIT_EVENT ( 3C ) WAIT_EVENT ( 3C )

NAME
wait_event – Delays the calling PE until the eureka event is posted

SYNOPSIS
Fortran:
CALL WAIT_EVENT
C:
void wait_event(void)

IMPLEMENTATION
UNICOS/mk systems

DESCRIPTION
wait_event suspends processing element (PE) execution at a cleared event until that event is posted by
set_event. wait_event does not change the state of the event. wait_event always uses the
hardware eureka mechanism for event communication. When the posting of one memory mode event is
required (a simple signal), call CLEAR_EVENT immediately after WAIT_EVENT to indicate that the posting
of the event was detected. All PEs do not have to wait for a eureka event to be posted. However, all PEs
must once again clear the event before another eureka activity can begin.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.

EXAMPLES

PRO GRA M MUL TI

C ...
CAL L CLEAR_ EVENT()
DO I=1 , MAX VAL
CALL GIN K(RESU LT,A(I ,1))
IF (RESUL T .EQ. SEA RCH_VA L) THE N
CAL L SET _EVENT ();
GOT O 20
ENDIF
IF (TE ST_EVENT()) GOTO 20
ENDDO
CALL WAI T_E VENT()
20 CONTIN UE
C ...
END

004– 2165– 002 545

WAIT_EVENT ( 3C ) WAIT_EVENT ( 3C )

SEE ALSO
clear_event(3C), set_event(3C), test_event(3C)

546 004– 2165– 002

INTRO_SORTSEARCH ( 3F ) INTRO_SORTSEARCH ( 3F )

NAME
INTRO_SORTSEARCH – Introduction to sorting and searching routines

IMPLEMENTATION
See individual man pages for implementation details

DESCRIPTION

The ISMAX routine runs on UNICOS and UNICOS/mk systems. The remainder of these sorting and
searching routines run only on UNICOS systems.
Sorting Routines
The following table contains the purpose, name, and entry of each sorting routine. The entry is the name of
the man page that contains documentation for the routine(s) listed.
Sorting routines:

Purpose Name Entry

Performs a distribution counting sort on the elements of an integer vector ISORTD ISORTD
Performs a Batcher’s Odd/Even Merge sort on the elements of a real or SSORTB SSORTB
integer general vector ISORTB
Performs an internal fixed-length record sort using radix sort algorithm ORDERS ORDERS

Searching Routines
The searching routines are grouped into maximum or minimum element search routines and vector search
routines.
Maximum or Minimum Element Search Routines
The maximum and minimum element search routines search a vector for the largest or smallest element and
return its index.
Note: The index location returned by each of these routines is in relation to the number of elements chosen
to be searched, rather than the total number of elements in the vector. For example, if you choose to search
every second element in a 15-element vector, 8 values will be searched and the index location of the target
returned will be the target’s position relative to the 8 searched values, not relative to the 15 total elements.
That is, the returned index is relative, not absolute.
The following table contains the purpose, name, and entry of each maximum or minimum element search
routine. The entry is the name of the man page containing documentation for the routine(s) listed.

004– 2165– 002 547

INTRO_SORTSEARCH ( 3F ) INTRO_SORTSEARCH ( 3F )

Purpose Name Entry

Searches for the maximum or minimum value in subfields of a vector INFLMAX INFLMAX
element INFLMIN
Searches an integer vector for the maximum or minimum value INTMAX INTMAX
INTMIN
Searches a vector for the first occurrence of the maximum or minimum ISAMAX ISAMAX
absolute value ICAMAX
ISAMIN
Searches a real vector for the first occurrence of the maximum or ISMAX ISMAX
minimum value ISMIN

Vector Search Routines

Vector search routines have one of the following functions:
• To return the number of leading occurrences of an object in a vector
• To search for an object in a vector

To return the number of leading occurrences of an object in a vector: These integer functions return the
number of occurrences of a given relation in a vector.
Note: The number of occurrences returned is relative to the number of elements chosen to be searched, not
the absolute number of elements in the vector.
IILZ returns the number of zero values in a vector before the first nonzero value.
ILLZ returns the number of leading elements of a vector that do not have the sign bit set.
ILSUM returns the number of .TRUE. values in a vector declared logical.

To search for an object in a vector: These routines return the index (or indices) of the element(s) found.
ISRCH functions search a vector for the first element (or element subfield) that has a specified logical
relationship to a target.
Note: As previously described for the Maximum or Minimum Element Search Routines, the index returned
by these functions and routines is relative, not absolute.
The WHEN routines search a vector for all elements (or element subfields) that have a specified logical
relationship to a target.
The CLUS routines search a vector for clusters of values that have a specified logical relationship to a target.

548 004– 2165– 002

INTRO_SORTSEARCH ( 3F ) INTRO_SORTSEARCH ( 3F )

The OSRCHI and OSRCHF routines search an ordered vector for the first element (or element subfield) that
has a specified logical relationship to a target.
The following table contains the purpose, name, and entry of each vector search routine. The entry is the
name of the man page containing documentation for the routine(s) listed.

Purpose Name Entry

Returns the number of leading occurrences of an object in a vector IILZ IILZ

ILLZ
ILSUM
Searches a vector for clusters of values equal or not equal to a target CLUSEQ CLUSEQ
CLUSNE
Searches a real vector for clusters of values that are less than, less than CLUSFLT CLUSFLT
or equal to, greater than, or greater than or equal to a target CLUSFLE
CLUSFGT
CLUSFGE
Searches an integer vector for clusters of values that are less than, less CLUSILT CLUSILT
than or equal to, greater than, or greater than or equal to a target CLUSILE
CLUSIGT
CLUSIGE
Searches a vector for the first element equal or not equal to a target ISRCHEQ ISRCHEQ
ISRCHNE
Searches a real vector for the first element that is less than, less than or ISRCHFLT ISRCHFLT
equal to, greater than, or greater than or equal to a real target ISRCHFLE
ISRCHFGT
ISRCHFGE
Searches an integer vector for the first element that is less than, less than ISRCHILT ISRCHILT
or equal to, greater than, or greater than or equal to an integer target ISRCHILE
ISRCHIGT
ISRCHIGE
Searches a vector for the first element whose subfield is equal or not ISRCHMEQ ISRCHMEQ
equal to a target ISRCHMNE
Searches a vector for the first element whose subfield is less than, less ISRCHMLT ISRCHMLT
than or equal to, greater than, or greater than or equal to a target ISRCHMLE
ISRCHMGT
ISRCHMGE
Searches an ordered vector for the first location that contains a target OSRCHI OSRCHI
OSRCHF

004– 2165– 002 549

INTRO_SORTSEARCH ( 3F ) INTRO_SORTSEARCH ( 3F )

Purpose Name Entry

Searches an ordered integer vector for the first element having a subfield OSRCHM OSRCHM
equal to an integer target
Searches a vector for all elements equal or not equal to a target WHENEQ WHENEQ
WHENNE
Searches a real vector for all elements that are less than, less than or WHENFLT WHENFLT
equal to, greater than, or greater than or equal to a real target WHENFLE
WHENFGT
WHENFGE
Searches an integer vector for all elements that are less than, less than or WHENILT WHENILT
equal to, greater than, or greater than or equal to an integer target WHENILE
WHENIGT
WHENIGE
Searches a vector for all elements whose subfields are equal or not equal WHENMEQ WHENMEQ
to a target WHENMNE
Searches a vector for all elements whose subfields are less than, less than WHENMLT WHENMLT
or equal to, greater than, or greater than or equal to a target WHENMLE
WHENMGT
WHENMGE

550 004– 2165– 002

CLUSEQ ( 3F ) CLUSEQ ( 3F )

NAME
CLUSEQ, CLUSNE – Searches a vector for clusters of values equal or not equal to a target

SYNOPSIS
CALL CLUSEQ (n, x, incx, target, index, nn)
CALL CLUSNE (n, x, incx, target, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
CLUSEQ searches a real or integer vector for clusters of values equal to a real or integer target.
CLUSNE searches a real or integer vector for clusters of values not equal to a real or integer target.
The indices of the beginning and end of these clusters are returned in the array index. The number of
occurrences of these clusters is returned in nn.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements (64-bit words) of the searched array.
target Real or integer. (input)
Value for which array is searched.
index Integer array of dimension (2, n). (output)
On exit, contains the indices in x at which each cluster starts and stops. The index of the first
element is 1.
nn Integer. (output)
Number of matches found.

004– 2165– 002 551

CLUSEQ ( 3F ) CLUSEQ ( 3F )

NOTES
Searching for the cluster allows vectorization. Before using these routines, users should know that the
logical search results in clusters of finds.
If the size of each cluster is 1, this routine operates the same as WHENEQ(3F).
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

552 004– 2165– 002

CLUSFLT ( 3F ) CLUSFLT ( 3F )

NAME
CLUSFLT, CLUSFLE, CLUSFGT, CLUSFGE – Searches a real vector for clusters of values with a specified
logical relationship to a real target

SYNOPSIS
CALL CLUSFLT (n, x, incx, target, index, nn)
CALL CLUSFLE (n, x, incx, target, index, nn)
CALL CLUSFGT (n, x, incx, target, index, nn)
CALL CLUSFGE (n, x, incx, target, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
CLUSFLT searches a real vector for clusters of values less than a real target.
CLUSFLE searches a real vector for clusters of values less than or equal to a real target.
CLUSFGT searches a real vector for clusters of values greater than a real target.
CLUSFGE searches a real vector for clusters of values greater than or equal to a real target.
The indices of the beginning and end of these clusters are returned in the array index. The number of
occurrences of these clusters is returned in nn.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Real array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
target Real. (input)
Value for which array is searched.
index Integer array of dimension (2, n). (output)
On exit, contains the indices in x where the cluster(s) starts and stops. The index of the first
element is 1.

004– 2165– 002 553

CLUSFLT ( 3F ) CLUSFLT ( 3F )

nn Integer. (output)
Number of matches found.

NOTES
Searching for the cluster allows vectorization. Before using these routines, you should know that the logical
search results in clusters of finds.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

554 004– 2165– 002

CLUSILT ( 3F ) CLUSILT ( 3F )

NAME
CLUSILT, CLUSILE, CLUSIGT, CLUSIGE – Searches an integer vector for clusters of values with a
specified logical relationship to an integer target

SYNOPSIS
CALL CLUSILT (n, x, incx, itarget, index, nn)
CALL CLUSILE (n, x, incx, itarget, index, nn)
CALL CLUSIGT (n, x, incx, itarget, index, nn)
CALL CLUSIGE (n, x, incx, itarget, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
CLUSILT searches an integer vector for clusters of values less than an integer target.
CLUSILE searches an integer vector for clusters of values less than or equal to an integer target.
CLUSIGT searches an integer vector for clusters of values greater than an integer target.
CLUSIGE searches an integer vector for clusters of values greater than or equal to an integer target.
The indices of the beginning and end of these clusters are returned in the array index. The number of
occurrences of these clusters is returned in nn.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
itarget Integer. (input)
Value for which the array is searched.
index Integer array of dimension (2, n). (output)
On exit, contains the indices in x where the cluster(s) starts and stops. The index of the first
element is 1.

004– 2165– 002 555

CLUSILT ( 3F ) CLUSILT ( 3F )

nn Integer. (output)
Number of matches found.

NOTES
Searching for the cluster allows vectorization. Before using these routines, you should know that the logical
search will result in clusters of finds.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

556 004– 2165– 002

IILZ ( 3F ) IILZ ( 3F )

NAME
IILZ, ILLZ, ILSUM – Returns number of leading occurrences of an object in a vector

SYNOPSIS
kount = IILZ (n, x, incx)
kount = ILLZ (n, x, incx)
kount = ILSUM (n, x, incx)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
IILZ returns the number of zero values in a vector before the first nonzero value. The vector can be of
type integer, real, or logical.
ILLZ returns the number of leading elements of a vector that do not have the sign bit set. The vector can
be of type integer, real, or logical.
ILSUM returns the number of .TRUE. values in a vector declared logical.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
kount Integer. (output)
Number of leading occurrences of an object in the vector.
n Integer. (input)
Number of vector elements to process.
x Integer, real, or logical array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of x.

NOTES
When scanning backward (incx < 0), both IILZ and ILLZ start at the end of the vector and move
backward, as follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

004– 2165– 002 557

IILZ ( 3F ) IILZ ( 3F )

If x is of type logical, IILZ returns the number of FALSE values before encountering the first .TRUE.
value.

558 004– 2165– 002

INFLMAX ( 3F ) INFLMAX ( 3F )

NAME
INFLMAX, INFLMIN – Searches for the maximum or minimum value in subfields of a vector element

SYNOPSIS
index = INFLMAX (n, x, incx, mask, shift)
index = INFLMIN (n, x, incx, mask, shift)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
INFLMAX searches for the maximum value in subfields of a vector element.
INFLMIN searches for the minimum value in subfields of a vector element.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index in x where maximum or minimum occurs. The index of the first element is 1.
n Integer. (input)
Number of elements to be searched; length of the array.
x Real, integer, or logical array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the table to be searched.
incx Integer. (input)
Increment between elements of x.
mask Integer. (input)
Right-justified mask used for masking the table vector.
shift Integer. (input)
Number of bits to right shift the table vector before masking.

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

004– 2165– 002 559

INFLMAX ( 3F ) INFLMAX ( 3F )

The desired element is at:

x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

560 004– 2165– 002

INTMAX ( 3F ) INTMAX ( 3F )

NAME
INTMAX, INTMIN – Searches an integer vector for the maximum or minimum value

SYNOPSIS
index = INTMAX (n, x, incx)
index = INTMIN (n, x, incx)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
INTMAX searches an integer vector for the maximum value. INTMIN searches an integer vector for the
minimum value.
When using the CF90 compiler UNICOS or UNICOS/mk, all arguments must be of default kind unless
documented otherwise. On UNICOS and UNICOS/mk, default kind is KIND=8 for integer, real, complex,
and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index in x where maximum or minimum occurs. The index of the first element is 1.
n Integer. (input)
Number of elements to be searched.
x Integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of x.

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired element is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

004– 2165– 002 561

ISAMAX ( 3F ) ISAMAX ( 3F )

NAME
ISAMAX, ICAMAX, ISAMIN – Searches a vector for the first occurrence of the maximum or minimum
absolute value

SYNOPSIS
index = ISAMAX (n, x, incx)
index = ICAMAX (n, x, incx)
index = ISAMIN (n, x, incx)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISAMAX searches a real vector for the first occurrence of the maximum absolute value.
ICAMAX searches a complex vector for the first occurrence of the maximum absolute value.
ISAMIN searches a real vector for the first occurrence of the minimum absolute value.
ISAMAX returns the first index i such that
 x i  = MAX  x j  : j = 1, . . ., n
where x j is an element of a real vector.
ICAMAX determines the first index i such that
 Real(x i )  +  Imag(x i )  = MAX(  Real(x j )  +  Imag(x j )  ): j = 1, . . ., n
where x j is an element of a complex vector.
ISAMIN returns the first index i such that
 x i  = MIN x j  : j = 1, . . ., n
where x j is an element of a real vector.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These integer functions have the following arguments:
index Integer. (output)
First index of maximum or minimum absolute value.
n Integer. (input)
Number of elements to process in the vector to be searched. If n ≤ 0, ISAMAX, ICAMAX, and
ISAMIN return 0.

562 004– 2165– 002

ISAMAX ( 3F ) ISAMAX ( 3F )

x ISAMAX, ISAMIN: Real array of dimension (n– 1) . incx +1.

 (input)
ICAMAX: Complex array of dimension (n– 1) . incx +1.
 (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of x.

NOTES
This subroutine executes on a single processor and uses private data only.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The largest absolute value is:
ABS (x(1+(index– 1) . incx)) when incx > 0
ABS (x(1+(index– n) . incx)) when incx < 0

ISAMAX and ICAMAX are Level 1 Basic Linear Algebra Subprograms (Level 1 BLAS).

004– 2165– 002 563

ISMAX ( 3F ) ISMAX ( 3F )

NAME
ISMAX, ISMIN – Searches a real vector for the first occurrence of the maximum or minimum value

SYNOPSIS
index = ISMAX (n, x, incx)
index = ISMIN (n, x, incx)

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
ISMAX searches a real vector for the first occurrence of the maximum value; ISMIN searches a real vector
for the first occurrence of the minimum value.
ISMAX returns the first index i such that
x i = MAX x j for all j = 1,. . ., n
where x j is an element of a real vector.
ISMIN returns the first index i such that
x i = MIN x j for all j = 1,. . ., n
where x j is an element of a real vector.
When using the CF90 compiler on UNICOS or UNICOS/mk, all arguments must be of default kind unless
documented otherwise. On UNICOS and UNICOS/mk, default kind is KIND=8 for integer, real, complex,
and logical arguments.
These functions have the following arguments:
index Integer. (output)
First index of maximum or minimum value.
n Integer. (input)
Number of elements to process in the vector to be searched. If n ≤ 0, ISMAX and ISMIN return 0.
x Real array containing the vector to be searched. (input)
Array x of dimension 1+(n– 1) .  incx  .
incx Integer. (input)
Increment between elements of x.

564 004– 2165– 002

ISMAX ( 3F ) ISMAX ( 3F )

NOTES
This subroutine executes on a single processor and uses private data only.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

004– 2165– 002 565

ISORTD ( 3F ) ISORTD ( 3F )

NAME
ISORTD – Performs a distribution counting sort on the elements of an integer vector

SYNOPSIS
CALL ISORTD (ad, n, l, h, x, incx, index, incd, count)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
This routine performs an indexed sort on the elements of an integer vector in ascending or descending order.
An indexed sort returns the result in an index array, leaving the input vector unchanged. This sort is
applicable when all values fall into the range l ≤ x(i) ≤ h and h – l is small. When this is true, the ISORTD
algorithm is of O(n) complexity and does not entail the startup found in ORDERS.
The following calls illustrate the sorts provided by this routine.
CALL ISORTD(’A’, N, L, H, X, INCX, INDEX, INCD, COUNT) – Performs an indexed sort
in ascending order.
CALL ISORTD(’D’, N, L, H, X, INCX, INDEX, INCD, COUNT) – Performs an indexed sort
in descending order.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
This routine has the following arguments:
ad Character. (input)
Indicates whether to sort in ascending or descending order.
Valid values are ’a’, ’A’, ’d’, and ’D’. To signify ascending order, use ’a’ and ’A’ and to signify
descending order use ’d’ and ’D’. Only the first character is significant; therefore, to enhance clarity,
you may use ’ascending’ or ’descending’ as the value for ad, to enhance clarity.
n Integer. (input)
Number of elements to be sorted. n > 0.
l Integer. (input)
Lower bound on the values of the input array.
h Integer. (input)
Upper bound on the values of the input array.
x Integer array of dimension (n– 1) . incx+1. (input)
Array x contains the values to be sorted.
incx Integer. (input)
Increment between elements of the input array. incx > 0.

566 004– 2165– 002

ISORTD ( 3F ) ISORTD ( 3F )

index Integer array of dimension (n– 1) . incd+1. (output)

Array index holds the results of the sort.
On exit, x may be accessed in sorted order using index, as follows:
xsorted(k) = x(1+(index(1+(k– 1) . incd) – 1) . incx), for all k = 1, 2, . . ., n
incd Integer. (input)
Increment for the elements of index. incd > 0.
count Integer. (output (scratch))
Work array of dimension at least w = (h – l) used to count occurrences of values.

NOTES
Negative increments are never required because ad specifies ascending or descending order.
The increment in count is 1.
This sort is stable.

EXAMPLES
Suppose that you want to sort every third element of the array X into ascending order. The values of X
range from 61 to 1010 and consist of a small subset of these. You want these to go into column 4 of a
matrix of indices, MID. INCD=1, the increment between elements of a column in MID. The call is as
follows:
CALL ISO RTD ( ’A’ , N, 61, 1010, X, 3, MID( 1,4 ), INC D, COUNT )

Following are two examples that show how to sort rows or columns of a matrix into the corresponding rows
or columns of an index matrix. After the sort is complete, you can access the matrix in sorted order through
the matrix MID. The examples in the code are sorting each row of a matrix into ascending order and then
sorting each column of a matrix into descending order.
Example 1: Row-by-row sort (ascending order):
PROGRA M TIS ORT D1
*----- --- --- ------ ------ --- --------- --- ------------ ------------ --------
* ..P ara meters ..
INT EGE R ROW , COL , L, H
PAR AMETER( ROW =4, COL =5, L=1 , H=4 )

* ..S calar var s..

INT EGER I, J

* ..V ect or vars..

INT EGER COUNT( L:H ), MID ( ROW,CO L ), IA( ROW,COL )

*-- ------ ------ --- ------ --------- --- ------------ ------------ -----------
* ..B egi n exe cut ion..

004– 2165– 002 567

ISORTD ( 3F ) ISORTD ( 3F )

* Initialize IA() wit h num bers betwee n L and H.

DO I = 1, ROW
DO J = 1, COL
IA( I,J ) = 1 + MOD( I*J, H )
END DO
END DO

*-------- --------------------- ------ --- --- --- ------ --- --- --- ------ --- --
* Sort eac h row in ascend ing order.
DO I = 1, ROW
CAL L ISORTD ( ’ASCEN DING’, COL , L, H, IA( I,1 ), ROW,
& MID( I,1 ), ROW, COUNT )
END DO

*-- ------ ------ ------ ------ --- --- --- --- ------ --- --- --- ------ --- --- --- --
* ..I/O..
PRINT *, " ... IA( ) pri or to row-by -ro w sor t ... "
DO I = 1, ROW
WRI TE( 6,1 0 ) ( IA( I,J ), J=1,CO L )
END DO

PRINT *, " ... IA( ) aft er row -by -ro w sor t ... "
DO I = 1, ROW
WRI TE( 6,1 0 ) ( IA( I,MID( I,J ) ), J=1 ,COL )
END DO

* ..F ormat Statements..

10 FORMAT ( 5X, 5( I5, 2X ) )
END

The results of program TISORTD1 are as follows:

... IA( ) prior to row -by -row sort ...
2 3 4 1 2
3 1 3 1 3
4 3 2 1 4
1 1 1 1 1
... IA() aft er row -by-ro w sort ...
1 2 2 3 4
1 1 3 3 3
1 2 3 4 4
1 1 1 1 1

568 004– 2165– 002

ISORTD ( 3F ) ISORTD ( 3F )

Example 2: Column-by-column sort (descending order):

PROGRA M TISORT D2
*----- --- --- ------ ------ --- --- ------ --- --- --- ------ --- --- --- ------ -----
* ..P ara meters ..
INTEGE R ROW, COL, L, H
PAR AME TER( ROW =5, COL =4, L=1 , H=4 )

* ..Scal ar var s..

INT EGE R I, J

* ..Vect or var s..

INTEGE R COUNT( L:H ), MID( ROW ,COL ), IA( ROW ,COL )

*----- --- --- ------ ------ --- --- ------ --- --- --- ------ --- --- --- ------ -----
* ..Begi n execut ion..

* Initia lize IA() wit h num ber s bet wee n L and H.

DO I = 1, ROW
DO J = 1, COL
IA( I,J ) = 1 + MOD ( I*J , H )
END DO
END DO

*----- ------ --- ------ --- --- --- --- ------ --- --- --- ------ ------ --- --------
* Sort each col umn in des cendin g ord er.
DO J = 1, COL
CAL L ISO RTD ( ’DE SCE NDING’ , ROW , L, H, IA( 1,J ), 1,
& MID( 1,J ), 1, COUNT )
END DO

*----- --- ------ --- --- ------ --- --- --- ------ ------ --- ------ ------ ------ --
* ..I /O..
PRI NT *, " ... IA( ) pri or to column -by -colum n sort ... "
DO I = 1, ROW
WRI TE( 6,10 ) ( IA( I,J ), J=1 ,CO L )
END DO

PRI NT *, " ... IA() aft er col umn -by -colum n sor t ... "
DO I = 1, ROW
WRI TE( 6,1 0 ) ( IA( MID( I,J ),J ), J=1 ,COL )
END DO

* ..Form at statem ents

004– 2165– 002 569

ISORTD ( 3F ) ISORTD ( 3F )

10 FOR MAT( 5X, 4( I5, 2X ) )

END

The results of program TISORTD2 are as follows:

... IA() pri or to col umn -by -co lumn sor t ...
2 3 4 1
3 1 3 1
4 3 2 1
1 1 1 1
2 3 4 1
... IA( ) aft er column-by -co lum n sor t ...
4 3 4 1
3 3 4 1
2 3 3 1
2 1 2 1
1 1 1 1

570 004– 2165– 002

ISRCHEQ ( 3F ) ISRCHEQ ( 3F )

NAME
ISRCHEQ, ISRCHNE – Searches a vector for the first element equal or not equal to a target

SYNOPSIS
index = ISRCHEQ (n, x, incx, target)
index = ISRCHNE (n, x, incx, target)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISRCHEQ searches a real or integer vector for the first element that is equal to a real or integer target.
ISRCHNE searches a real or integer vector for the first element that is not equal to a real or integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index of the first element equal or not equal to target. If target is not found, n+1 is returned. If
n ≤ 0, 0 is returned.
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
target Real or integer. (input)
Value for which to search in the array.

004– 2165– 002 571

ISRCHEQ ( 3F ) ISRCHEQ ( 3F )

The Fortran equivalent code for ISRCHEQ is as follows:

FUN CTION ISRCHE Q(N ,X,INC X,TARG ET)
INT EGER X(*), TARGET
J=1
ISR CHEQ=0
IF( N.LE.0 ) RETURN
IF( INCX.L T.0) J=1-(N -1) *IN CX
DO 100 I=1 ,N
IF(X(J ).E Q.TARG ET) GO TO 200
J=J+IN CX
100 CON TINUE
200 ISRCHE Q=I
RETURN
END

Although used as integers internally, you can use real values of x and target, because ISRCHEQ and
ISRCHEQ are matching bit patterns.

NOTES
ISRCHEQ replaces the ISEARCH routine, but it has an entry point named ISEARCH as well as ISRCHEQ.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

572 004– 2165– 002

ISRCHFLT ( 3F ) ISRCHFLT ( 3F )

NAME
ISRCHFLT, ISRCHFLE, ISRCHFGT, ISRCHFGE – Searches a real vector for the first element with a
specified logical relationship to a real target

SYNOPSIS
index = ISRCHFLT (n, x, incx, ftarget)
index = ISRCHFLE (n, x, incx, ftarget)
index = ISRCHFGT (n, x, incx, ftarget)
index = ISRCHFGE (n, x, incx, ftarget)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISRCHFLT searches a real vector for the first element that is less than a real target.
ISRCHFLE searches a real vector for the first element that is less than or equal to a real target.
ISRCHFGT searches a real vector for the first element that is greater than a real target.
ISRCHFGE searches a real vector for the first element that is greater than or equal to a real target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index of the first element with the specified logical relationship to ftarget. If ftarget is not found,
n+1 is returned. If n ≤ 0, 0 is returned.
n Integer. (input)
Number of elements to be searched.
x Real array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
ftarget Real. (input)
Value for which to search in the array.

004– 2165– 002 573

ISRCHFLT ( 3F ) ISRCHFLT ( 3F )

NOTES

When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

574 004– 2165– 002

ISRCHILT ( 3F ) ISRCHILT ( 3F )

NAME
ISRCHILT, ISRCHILE, ISRCHIGT, ISRCHIGE – Searches an integer vector for the first element with a
specified logical relationship to an integer target

SYNOPSIS
index = ISRCHILT (n, x, incx, itarget)
index = ISRCHILE (n, x, incx, itarget)
index = ISRCHIGT (n, x, incx, itarget)
index = ISRCHIGE (n, x, incx, itarget)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISRCHILT searches an integer vector for the first element that is less than an integer target.
ISRCHILE searches an integer vector for the first element that is less than or equal to an integer target.
ISRCHIGT searches an integer vector for the first element that is greater than an integer target.
ISRCHIGE searches an integer vector for the first element that is greater than or equal to an integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index of the first element with the specified logical relationship to itarget. If itarget is not found,
n+1 is returned. If n ≤ 0, 0 is returned.
n Integer. (input)
Number of elements to be searched.
x Integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
itarget Integer value searched for in the array. (input)

004– 2165– 002 575

ISRCHILT ( 3F ) ISRCHILT ( 3F )

NOTES

When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

576 004– 2165– 002

ISRCHMEQ ( 3F ) ISRCHMEQ ( 3F )

NAME
ISRCHMEQ, ISRCHMNE – Searches a vector for the first element whose subfield is equal or not equal to a
target

SYNOPSIS
index = ISRCHMEQ (n, x, incx, itarget, mask, iright)
index = ISRCHMNE (n, x, incx, itarget, mask, iright)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISRCHMEQ searches a real or integer vector for the first element whose subfield is equal to a real or integer
target.
ISRCHMNE searches a real or integer vector for the first element whose subfield is not equal to a real or
integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index of the first element whose subfield is equal or not equal to itarget. If itarget is not found,
n+1 is returned. If n ≤ 0, 0 is returned.
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
itarget Integer. (input)
Value for which to search in the array.
mask Integer. (input)
Mask of 1’s (set bits) from the right. The number of set bits in mask is the number of bits in the
subfield, which is searched in each element of the input array.
iright Integer. (input)
Number of bits to shift each element of the input array to the right so as to right justify the
subfield searched.

004– 2165– 002 577

ISRCHMEQ ( 3F ) ISRCHMEQ ( 3F )

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

578 004– 2165– 002

ISRCHMLT ( 3F ) ISRCHMLT ( 3F )

NAME
ISRCHMLT, ISRCHMLE, ISRCHMGT, ISRCHMGE – Searches a vector for the first element whose subfield
has a specified logical relationship with a target

SYNOPSIS
index = ISRCHMLT (n, x, incx, itarget, mask, iright)
index = ISRCHMLE (n, x, incx, itarget, mask, iright)
index = ISRCHMGT (n, x, incx, itarget, mask, iright)
index = ISRCHMGE (n, x, incx, itarget, mask, iright)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ISRCHMLT searches a real or integer vector for the first element whose subfield is less than a real or integer
target.
ISRCHMLE searches a real or integer vector for the first element whose subfield is less than or equal to a
real or integer target.
ISRCHMGT searches a real or integer vector for the first element whose subfield is greater than a real or
integer target.
ISRCHMGE searches a real or integer vector for the first element whose subfield is greater than or equal to a
real or integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These functions have the following arguments:
index Integer. (output)
Index of the first element whose subfield has the specified logical relationship with itarget. If
itarget is not found, n+1 is returned. If n ≤ 0, 0 is returned.
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
itarget Integer. (input)
Value for which to search in the array.

004– 2165– 002 579

ISRCHMLT ( 3F ) ISRCHMLT ( 3F )

mask Integer. (input)

Mask of 1’s (set bits) from the right. The number of set bits in mask is the number of bits in the
subfield, which is searched in each element of the input array.
iright Integer. (input)
Number of bits to shift each element of the input array to the right so as to right justify the subfield
searched.

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0

580 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

NAME
ORDERS – Internal, fixed-length record-sorting routine optimized for UNICOS systems

SYNOPSIS
CALL ORDERS (mode, iwork, data, index, n[, ireclth, ikeylth, iradsiz])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
ORDERS is an internal, fixed-length record sort routine. ORDERS uses the radix sort, which is more
commonly known as a bucket or pocket sort. For this type of sort, the length, in bytes, of the key, and the
length, in words, of the record, determines the number of passes made through all of the records. You can
perform the sort in O(n) operations, and it is stable.
For definitions of major terms used in this document, see the Glossary subsection of the NOTES section.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
This routine has the following arguments:
mode Integer. (input/output)
On input, mode describes the type of key and indicates an initial ordering of the records, as
follows:
0 Keys are positive integers or ASCII characters
63 63
1 Keys are treated as two’s complement (signed) integers over the range [– 2 , 2 – 1]
2 Keys are treated as floating-point numbers
10 Same as mode = 0, but the array index contains the initial ordering of the records
11 Same as mode = 1, but the array index contains the initial ordering of the records
12 Same as mode = 2, but the array index contains the initial ordering of the records
On output, if an error is encountered, ORDERS returns a value < 0 in mode; otherwise, mode
remains unchanged. The error values are as follows:
–1 Too few arguments (must be greater than 4)
–2 Too many arguments (must be less than 9)
–3 ireclth is not valid (must be > 0)
–4 Invalid ikeylth (must be in the range 0 < ikeylth ≤ 8 . ireclth)
–5 iradsiz is not valid (must be 1 or 2)
–6 ikeylth is not valid (must be > 0)
–7 n is not valid (must be > 0)
–8 mode input value is not valid (must be 0, 1, 2, 10, 11, or 12)
–9 ikeylth is not valid (must be 8 for real or integer sort)

004– 2165– 002 581

ORDERS ( 3F ) ORDERS ( 3F )

iwork Integer array of dimension 256 or 65,536. (workspace)

User-supplied working storage array. The length depends on iradsiz, as follows:
If iradsiz = 1, the length of iwork should be 256.
If iradsiz = 2, the length of iwork should be 65,536.
data Integer array of dimension (ireclth, n). (input)
data contains n records of length ireclth each.
index Integer array of dimension n. (output)
If mode = 10, 11, or 12, index contains an initial ordering of the records in the array data. Thus,
data( i,index( 1 ) ) is the ith word of the first record, and data( i,index( n ) ) is the ith word of the
last record. Each index( i ) should be in the closed interval ( 1 . . . n ) and unique with respect to
all other index( i ).
n Integer. (input)
Number of records to be sorted.
ireclth Integer. (input)
Optional argument. Length of each record in words. If specified, 1 ≤ ireclth. The default is 1.
ikeylth Integer. (input)
Optional argument. Length of each key as a number of 8-bit bytes. (8 bytes = 1 word.) If
specified, must be in the interval (1 ≤ ikeylth ≤ 8 . ireclth). If mode = 1, ikeylth must = 8. The
default is 8.
iradsiz Integer. (input)
Optional argument. Radix of the sort (the number of 8-bit bytes processed per pass). If specified,
must be 1 or 2. A radix-2 sort requires fewer passes through the record, but it uses more
workspace and has a higher overhead per pass. The default is 1.

NOTES
ORDERS has the option of processing 1 or 2 bytes of the key per pass through the records. This process
halves the number of passes through the record, but at the expense of increased working storage and
overhead per pass. ORDERS can sort on several keys within a record by using its multipass capability.
Large Radix Sorting
The number of times the key of each record is read from memory is proportional to ikeylth/iradsiz. Using
ORDERS with iradsiz = 2 halves this ratio, because 2 bytes instead of 1 are processed each time the key is
read. The disadvantage of halving the number of passes is that the user-supplied working storage array goes
from 256 words to 65,536 words and the initialization time of this work array is greater than for the
256-word array. From a performance standpoint, this favors a 1-byte pass for sorting smaller arrays up to
approximately 5000 records. For more than 5000 records, however, a 2-byte pass is faster.

582 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

Multipass Sorting
Because the array index can define an ordering of the records, several calls can be made to ORDERS where
the order of the records is that of the previous call. mode = 10, 11, or 12 specifies that the array index
contains an ordering from a previous call to ORDERS. This specification allows sorting of text keys that
extend over more than 1 word or keys involving double-precision numbers. This algorithm performs the
radix sort over all keys. When using the multipass capability, sort the least-significant word first.
Glossary
This subsection contains definitions for some of the terms used in this man page.
Internal sort
An internal sort means that the sort can be performed entirely in core memory.
Record
A record is a generalized array element. The term record corresponds to the definition used in Pascal.
Record also corresponds to the term struct in C. From a C or Pascal programmer’s perspective, a struct
(record) is allowed to contain heterogeneous elements; it can be any mix of integer, real, logical, or character
data. It can even contain another struct (record).
This idea translates in limited fashion to Fortran. Although Fortran does not allow this general type of
storage scheme, you could envision each element of an array of real numbers as being a record.
Furthermore, if you are sorting a character array in which each element is 24 bytes wide, each 24-byte
element is also a record.
A fixed-length record means that the length of the record cannot vary. The programming construct that
allows the length of a data structure to vary is known as a union in C. Fixed-length records do not allow
this. The length of the record is always the same.
Key
Suppose a Pascal code contains the declaration of an array of records in which each record consists of an
integer and a real number. Each component of the record is called a key. If you wanted to sort this array
based on the values of the integers in each record, the sort is done on the integer key. For Fortran, a limited
notion of key applies. In this case, if you were sorting the character array consisting of 24-byte elements, a
sort could be done in which a key consists of the high-order 8 bytes. That is, the sort does not necessarily
have to apply to an entire element. Rather, the array can be sorted on the high-order 8 bytes of each array
element. For example, suppose that you are sorting an array of character strings in dictionary order and that
each string consists of 16 letters (bytes). If it were known that the last 8 letters (bytes) consists of the letters
xxxxxxxx, the sort need not proceed beyond the eighth letter of the element. Table 1 shows that you do
not have to look beyond the first 8 letters to sort these strings.

004– 2165– 002 583

ORDERS ( 3F ) ORDERS ( 3F )

Table 1: Example of sorting on keys

Unsort ed | Sor ted
====== ====== === === ====== === === === === ==
cccccc aax xxx xxxx | bcc ccc abxxxx xxx x
cccccc cbx xxx xxxx | bcc ccc gbxxxx xxx x
bccccc gbx xxx xxxx | ccc ccc aaxxxx xxx x
bccccc abx xxx xxxx | ccc ccc cbxxxx xxx x
====== ====== === === ====== === === === =====

Indexed sort
An indexed sort means that the original data is not disturbed. The indices in an index array are permuted
such that on completion of the sort, the data can be accessed in sorted order through this array. Because
ORDERS sorts the keys in increasing order, data( index(1)) will be the first word of the record with the
smallest key, data( index(2)) will be the first word of the record with the next smallest key, and so on. See
Table 2.
Table 2: Example of an indexed sort
Initia l Dat a Aft er Ind exe d Sor t

i x(i ) index( i) x(i ndex(i )) | i x(i ) index( i) x(i ndex(i))

=== ====== === ====== ====== === === ====== === === === ====== ====== ====== ======
1 2 1 2 | 1 2 1 2
2 3 2 3 | 2 3 3 2
3 2 3 2 | 3 2 2 3
4 10 4 10 | 4 10 6 9
5 17 5 17 | 5 17 4 10
6 9 6 9 | 6 9 5 17
7 17 7 17 | 7 17 7 17
====== ====== === ====== ====== === === ====== ====== === ========= ====== ======

Multipass sorting
Sorting can be done in multiple passes. For example, suppose you wanted to sort a character array
consisting of 16 byte-wide elements. The sort could be done in two passes. The first pass could sort on the
low-order byte of each element. This byte could be thought of as a key. During the second pass, the sort is
done on the high-order byte (key).
Stable sort
A stable sort is one in which the original order of records with equal keys is not disturbed. This matters for
multipass sorting. In a multipass sort, elements are sorted whose previous byte is the same. For example,
suppose you have an array of 2-character strings to be sorted. Table 3 illustrates the progression of a
multipass sort of the character array. When complete, the array inx will contain the permuted indices.

584 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

Table 3: Progression of a multipass sort

| Ini tia l Ord eri ng | Fir st Pas s | Sec ond Pass
| | |
i cx( i) | inx (i) cx(inx (i) ) | inx (i) cx( inx (i)) | inx (i) cx(inx (i))
====== === === ====== ====== === === ====== === === === ====== === ========= ====
1 cb | 1 cb | 2 aa | 2 aa
2 aa | 2 aa | 4 xa | 3 ac
3 ac | 3 ac | 5 ba | 5 ba
4 xa | 4 xa | 6 ca | 7 bx
5 ba | 5 ba | 1 cb | 6 ca
6 ca | 6 ca | 3 ac | 1 cb
7 bx | 7 bx | 7 bx | 4 xa
=== ====== ====== === ========= === === === ====== ====== === ========= =======

Note the two stages of the sort. During the first stage or pass, the strings are arranged in dictionary order
based on the least significant letter only (in this case, a letter is a key); therefore, all of the strings ending
with an "a" come first, then those ending with a "b", and so forth. The most-significant byte is sorted on
during the second pass. This is called least significant digit first radix sorting.
Also notice how this data was moved around. During the first pass, the strings were rearranged so that if
originally the string "xa" preceded the string "ba", that ordering is preserved when moving the data. This is
what is meant by a stable sort.

EXAMPLES
This section contains examples of the following uses of ORDERS:
• Sorting an array of 20 floating-point numbers, using default values for ireclth, ikeylth, and iradsiz
• Sorting double-precision numbers

004– 2165– 002 585

ORDERS ( 3F ) ORDERS ( 3F )

Sorting an array of 20 floating-point numbers, using default values for ireclth, ikeylth, and iradsiz:
PRO GRAM TRO RD
IMPLICIT NONE

* ..Para meters ..
INTEGE R LDIM, WKS PAC E
PARAME TER ( LDI M=2 0 )
PARAME TER ( WKS PAC E=6 553 6 )

* ..Vari abl es..

INTEGE R I, MOD E, IND EX( LDI M ), IWORK( WKS PAC E )
REAL VEC( LDIM )

* ..D ata ini tializ ati on. .

DATA MOD E / 2 / ! Sor t flo ati ng poi nt num ber s
DAT A VEC / 55.,54 .,5 3., 52. ,51.,
& -1.,-2 .,- 3., -4. ,-5.,
& 105.,1 04. ,10 3., 102.,1 01. ,
& -201., -202., -20 3.,-20 4., -20 5 /

* ..External rou tines. .

EXTERN AL ORDERS

* ..Begi n Exe cution ..

PRINT *, " ... VEC() pri or to sort ..."
DO I = 1, LDI M
WRITE( 6,1 0 ) VEC ( i )
END DO

CALL ORDERS ( MOD E, IWO RK, VEC , IND EX, LDI M )

PRINT *, " "

PRINT *, " ... VEC() aft er sor t ... "
DO I = 1, LDI M
WRITE( 6,1 0 ) VEC ( IND EX( i ) )
END DO

10 FORMAT( 5X, F10 .3 )

STOP
END

586 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

The results of program TRORD are as follows:

... VEC() pri or to sor t ...
55. 000
54. 000
53. 000
52. 000
51. 000
-1. 000
-2. 000
-3. 000
-4. 000
-5. 000
105 .000
104 .000
103 .000
102 .000
101 .000
-201.0 00
-202.0 00
-203.0 00
-204.0 00
-205.0 00

... VEC () after sort ...

-205.0 00
-204.0 00
-203.0 00
-202.0 00
-201.0 00
-5.000
-4.000
-3.000
-2.000
-1.000
51.000
52.000
53.000
54.000
55.000
101 .00 0
102 .00 0
103 .00 0
104 .00 0
105 .00 0

004– 2165– 002 587

ORDERS ( 3F ) ORDERS ( 3F )

Sorting Double-precision Numbers

This code example presents the sort of double-precision numbers. Double-precision numbers consist of 2
words per number. To sort them, you must use the multipass capability of ORDERS.
The data is equivalenced to an integer array so that for each pass the data can be treated as unsigned
integers. If the number is negative, the negative sign has to be carried temporarily to the low-order
component so that the direction of the sort will be consistent for both passes. This example uses random
numbers.
PRO GRAM TDO RD
* ..Para meters ..
INT EGER LDIM, WKS PACE
DOUBLE PRE CISION BOT, TOP
PARAME TER ( LDI M=2 0 )
PAR AME TER( WKS PAC E=256 )
PAR AME TER( BOT =1. 0D-12 )
PAR AME TER( TOP =2. 0D-12 )

* ..V ariabl es..

INT EGE R I, MOD E, INDEX( LDI M ), IWORK( WKS PACE )
INT EGER IVEC( 2*L DIM )
DOUBLE PRE CISION VEC( LDIM )
EQUIVA LEN CE( VEC ,IV EC )

* ..E xte rnal rou tines. .

EXT ERN AL ORD ERS

* ..Data ini tializ ati on. .

DAT A IRECLT H / 2 / ! Length of a record . In this cas e, a
* ! rec ord is two CRI wor ds long.
* ! Len gth of a record is in ter ms of
* ! CRI wor ds.
DAT A IKE YLT H / 8 / ! Length of a key is 8 bytes.
DATA IRA DSIZ / 1 / ! Do sor t 1 byt e at a tim e.

* ..S tat ement functi on. .

* Gen erate random dou ble precis ion number s betwee n the value A
* and the val ue B not inc luding A or B.
DOUBLE PRE CISION A, B, DRA N
DRAN( A,B ) = ( B-A )*D BLE( RANF() ) + A

* ..B egin execut ion ..

* Load VEC() with pos iti ve ran dom num bers tha t dif fer onl y
* in the low -order bits.

588 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

DO I = 1, LDI M/2
VEC ( I ) = 1.0 D2 + DRA N( BOT ,TOP )
END DO

* Loa d VEC () wit h neg ati ve ran dom num ber s tha t dif fer onl y
* in the low -or der bits.
DO I = LDIM/2 +1, LDI M-1
VEC( I ) = -1. 0D2 - DRA N( BOT ,TO P )
END DO

* Make sure there is a num ber and it’ s neg ative versio n in
* the arr ay.
VEC ( LDI M ) = -VE C( 1 )

* Change the sec ond wor d to hav e the same sign as the fir st
* wor d. Otherw ise , if the num ber is neg ative, the
* sor t of the sec ond wor d wou ld be backwa rds.
DO I = 1, 2*L DIM , 2
IF( IVEC( I ) .LE . 0 ) IVE C( I+1 ) = -IVEC( I+1 )
END DO

* Sor t low -order bit s, fir st.

* IVEC() had to be use d bec aus e the re is no way to acc ess
* the low-or der bit s usi ng VEC ().
MODE = 1
CALL ORD ERS( MOD E, IWO RK, IVE C(2 ), INDEX, LDIM, IRECLT H,
& IKE YLT H, IRA DSIZ )

* Res tore second word to ori gin al for m.

DO I = 1, 2*LDIM , 2
IVE C( I+1 )= ABS ( IVE C( I+1 ) )
END DO

* Sort hig h-orde r bit s.

MODE = 12
CAL L ORD ERS( MODE, IWO RK, VEC , IND EX, LDIM, IRE CLTH,
& IKEYLT H, IRA DSI Z )

* I/O
WRI TE( 6,10 )
DO I = 1, LDIM
WRI TE( 6,30 ) VEC ( I ), IVE C(2 *I- 1), IVE C(2*I)
END DO

004– 2165– 002 589

ORDERS ( 3F ) ORDERS ( 3F )

PRINT *, " "

WRI TE( 6,2 0 )
DO I = 1, LDIM
J = INDEX( I)
WRI TE( 6,30 ) VEC ( J ), IVE C(2*J- 1), IVEC(2 *J)
END DO

10 FOR MAT ( 4X, ".. .Value s in VEC () bef ore sort.. .", 5X,
& "...Eq uiv alent hex val ues in IVEC() ..." )
20 FOR MAT ( 4X, ".. .Value s in VEC () aft er sor t.. .", 6X,
& "...Eq uiv alent hex val ues in IVEC() ..." )
30 FOR MAT ( D40 .30, 2X, Z16 , 1X, Z16 )
END

The following output presents an array of random numbers that were generated. This array is sorted using
the multipass option. The result is then presented. Other than sign, the numbers differ from one another
only in the low-order bits. This is to show that, other than the sign of the numbers, the sort will really take
place based on these values.
...Values in VEC() before sort... ...Equivalent hex values in IVEC()...
0.100000000000001580113648579586E+03 4007C80000000003 00007986602A5AAD
0.100000000000001950512734980764E+03 4007C80000000004 00004A0A82782AC9
0.100000000000001786371425330602E+03 4007C80000000003 0000EDA34101DFE7
0.100000000000001297620264003728E+03 4007C80000000002 0000DA7EC9D47284
0.100000000000001453699900298492E+03 4007C80000000003 0000325C3C0AA41E
0.100000000000001006261941606187E+03 4007C80000000002 00003679A1040E89
0.100000000000001275736426383874E+03 4007C80000000002 0000CE2CFEB9DCBA
0.100000000000001305650943870477E+03 4007C80000000002 0000DF04219F5276
0.100000000000001689100710749872E+03 4007C80000000003 0000B6E1110D45E2
0.100000000000001382662238656297E+03 4007C80000000003 00000A5EA0E9EB86
-0.100000000000001132902705496380E+03 C007C80000000002 00007DC47C8993AF
-0.100000000000001831857903209073E+03 C007C80000000004 0000073E8BD6FD21
-0.100000000000001582979795830740E+03 C007C80000000003 00007B236E55C827
-0.100000000000001098625338337415E+03 C007C80000000002 00006A7898E5FDEB
-0.100000000000001276548455133567E+03 C007C80000000002 0000CEA2054C9046
-0.100000000000001620446027796948E+03 C007C80000000003 0000903AE251EF64
-0.100000000000001083502966833808E+03 C007C80000000002 000061F53BDD54E3
-0.100000000000001990377120595685E+03 C007C80000000004 0000607B92B524B0
-0.100000000000001979346943443064E+03 C007C80000000004 00005A45F4FF5F3C
-0.100000000000001580113648579586E+03 C007C80000000003 00007986602A5AAD

...Values in VEC() after sort... ...Equivalent hex values in IVEC()...

-0.100000000000001990377120595685E+03 C007C80000000004 0000607B92B524B0
-0.100000000000001979346943443064E+03 C007C80000000004 00005A45F4FF5F3C
-0.100000000000001831857903209073E+03 C007C80000000004 0000073E8BD6FD21
-0.100000000000001620446027796948E+03 C007C80000000003 0000903AE251EF64
-0.100000000000001582979795830740E+03 C007C80000000003 00007B236E55C827
-0.100000000000001580113648579586E+03 C007C80000000003 00007986602A5AAD
-0.100000000000001276548455133567E+03 C007C80000000002 0000CEA2054C9046
-0.100000000000001132902705496380E+03 C007C80000000002 00007DC47C8993AF

590 004– 2165– 002

ORDERS ( 3F ) ORDERS ( 3F )

-0.100000000000001098625338337415E+03 C007C80000000002 00006A7898E5FDEB

-0.100000000000001083502966833808E+03 C007C80000000002 000061F53BDD54E3
0.100000000000001006261941606187E+03 4007C80000000002 00003679A1040E89
0.100000000000001275736426383874E+03 4007C80000000002 0000CE2CFEB9DCBA
0.100000000000001297620264003728E+03 4007C80000000002 0000DA7EC9D47284
0.100000000000001305650943870477E+03 4007C80000000002 0000DF04219F5276
0.100000000000001382662238656297E+03 4007C80000000003 00000A5EA0E9EB86
0.100000000000001453699900298492E+03 4007C80000000003 0000325C3C0AA41E
0.100000000000001580113648579586E+03 4007C80000000003 00007986602A5AAD
0.100000000000001689100710749872E+03 4007C80000000003 0000B6E1110D45E2
0.100000000000001786371425330602E+03 4007C80000000003 0000EDA34101DFE7
0.100000000000001950512734980764E+03 4007C80000000004 00004A0A82782AC9

004– 2165– 002 591

OSRCHI ( 3F ) OSRCHI ( 3F )

NAME
OSRCHI, OSRCHF – Searches an ordered vector for the first location that contains a target

SYNOPSIS
CALL OSRCHI (n, x, incx, target, index, iwhere, inum)
CALL OSRCHF (n, x, incx, target, index, iwhere, inum)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
OSRCHI searches an ordered integer vector for the first location that contains an integer target.
OSRCHF searches an ordered real vector for the first location that contains a real target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of array elements to be searched.
x OSRCHI: Integer array of dimension (n– 1) .  incx  + 1. (input)
OSRCHF: Real array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
target OSRCHI: Integer. (input)
OSRCHF: Real. (input)
Value for which to search in the array.
index Integer. (output)
Index of the first element equal to target. If target is not found, index = n + 1. If n ≤ 0, index = 0
.
iwhere Integer. (output)
Index of the first element greater than or equal to target. If target is found, iwhere = index. If
target is greater than the last element of the array, iwhere = n + 1. If n ≤ 0, iwhere = 0.
inum Integer. (output)
Number of copies of target found in the array

592 004– 2165– 002

OSRCHI ( 3F ) OSRCHI ( 3F )

NOTES
Searching always begins at the lowest value in the ordered array. Even if the target is not found, the index
of the location that would contain the target is returned in iwhere. The total number of occurrences of the
target in the array (inum) can also be returned.
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
Thus, a positive increment indicates an ascending array, while a negative increment indicates a descending
array.
The index value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0
The iwhere value is at:
x(1+(iwhere– 1) . incx) when incx > 0
x(1+(iwhere– n) . incx) when incx < 0

004– 2165– 002 593

OSRCHM ( 3F ) OSRCHM ( 3F )

NAME
OSRCHM – Searches an ordered integer vector for the first element whose subfield is equal to an integer
target

SYNOPSIS
CALL OSRCHM (n, x, incx, itarget, mask, iright, index, iwhere, inu)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
OSRCHM searches an ordered integer vector and returns the index of the first element for which the subfield
defined by mask and iright is equal to an integer target. For the search to be successful, the input vector
must be ordered by subfield, not by the whole integer.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
This routine has the following arguments:
n Integer. (input)
Number of array elements to be searched
x Integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the array to be searched.
itarget Integer. (input)
Value for which to search in the array.
mask Integer. (input)
Mask set from the right side of the field of interest in array x.
iright Integer. (input)
Amount to right-shift array x to position the field of interest at right side of word.
index Integer. (output)
Index of the first element whose subfield is equal to itarget. If itarget is not found, index = n + 1.
If n ≤ 0, index = 0.
iwhere Integer. (output)
Index of the first element whose subfield is greater than or equal to itarget. If itarget is found,
iwhere = index . If itarget is greater than the subfield of the last element in the array,
iwhere = n + 1. If n ≤ 0, iwhere = 0.

594 004– 2165– 002

OSRCHM ( 3F ) OSRCHM ( 3F )

inum Integer. (input and output)

If inum equals 0 on input, inum is still 0 on output. If inum does not equal 0 on input, inum is the
number of array elements whose subfields match itarget on output; that is, inum returns a value only
if requested and at least one target value is found in the array; otherwise, it will always be 0.

NOTES
Searching always begins at the lowest value in the ordered array. Even if the target is not found, the index
of the location that would contain the target is returned in iwhere. The total number of occurrences of the
target in the array (inum) can also be returned.
When scanning backward (incx < 0), this routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
Thus, a positive increment indicates an ascending array (with respect to the subfield), while a negative
increment indicates a descending array (with respect to the subfield).
The index value is at:
x(1+(index– 1) . incx) when incx > 0
x(1+(index– n) . incx) when incx < 0
The iwhere value is at:
x(1+(iwhere– 1) . incx) when incx > 0
x(1+(iwhere– n) . incx) when incx < 0

EXAMPLES
As an example of a vector that is ordered by the whole integer value, but not ordered by subfield, consider
the following Fortran program:
PARAME TER (N= 128 )
PARAME TER (IT ARG ET= 20)
PARAME TER (IN CX= 1)
INT EGER X(N ),XWHE RE,IND EX, IWHERE,IN UM
C
C EAC H SUB FIELD IS THE FIV E RIGHTM OST BITS OF EACH INTEGER
C ( SUBFIE LD( I) = MOD(X( I), 2** 5), FOR ALL I = 1, 2, ..., 128 )
C
PAR AMETER (MA SK=(2* *5)-1, IRI GHT=0)
C
C X IS AN ASC ENDING SEQ UEN CE
C
PRINT*
PRI NT* , ’X( i) = 127 *i, for all I = 1, 2, ... , 128’
PRI NT*

004– 2165– 002 595

OSRCHM ( 3F ) OSRCHM ( 3F )

DO 10 I=1,12 8
X(I)=1 27* I
10 CON TIN UE
C
C LIS T OF ALL LOC ATI ONS WHE RE SUBFIE LD MAT CHE S TAR GET
C
INU M=0
PRI NT* , ’LO CATION S WHE RE MOD (X( i), 2** 5) = ’,I TARGET
PRINT*, ’(SUBF IEL D MAT CHE S TARGET )’
DO I=1,12 8
IF (IA ND( X(I ),MASK).E Q.I TAR GET ) THE N
PRI NT*, ’i = ’,I, ’ X(’ ,I,’) = ’, X(I)
INU M=INUM +1
ENDIF
END DO
PRI NT*
PRI NT* , ’NU MBER OF SUC H LOC ATIONS = ’,INUM
PRI NT*
C
C ATTEMP T TO FIN D TAR GET WIT H OSR CHM
C
CAL L OSR CHM (N,X,I NCX ,IT ARG ET, MASK,I RIGHT, IND EX,IWHERE ,IN UM)
XWH ERE=X( 1+(IWH ERE -1) *IN CX)
PRINT* , ’LO CAT IONS FOU ND BY OSR CHM WITH INCX = ’, INC X
PRINT*,’ IND EX IWH ERE INU M XWHERE MOD (XW HERE,2**5)’
PRI NT5 0, IND EX, IWHERE , INU M, XWHERE , IAN D(XWHERE, MAS K)
50 FOR MAT(I7 ,4( I10))
END

596 004– 2165– 002

OSRCHM ( 3F ) OSRCHM ( 3F )

The output of this program is as follows:

X(i) = 127*i, for all i = 1, 2, ... , 128

LOCATI ONS WHE RE MOD(X(i), 2** 5) = 20

(SU BFI ELD MAT CHE S TAR GET )
i = 12 X(1 2) = 1524
i = 44 X(44) = 558 8
i = 76 X(7 6) = 965 2
i = 108 X(1 08) = 13716

NUM BER OF SUC H LOCATI ONS = 4

LOC ATIONS FOUND BY OSRCHM WIT H INC X = 1

INDEX IWHERE INU M XWH ERE MOD (XW HERE,2 **5 )
129 1 0 127 31

004– 2165– 002 597

SSORTB ( 3F ) SSORTB ( 3F )

NAME
SSORTB, ISORTB – Performs Batcher’s Odd-Even Merge sort on the elements of a real or integer general
vector

SYNOPSIS
CALL SSORTB (ad, n, x, incx [, index, incd])
CALL ISORTB (ad, n, x, incx [, index, incd])

IMPLEMENTATION
UNICOS systems

DESCRIPTION
SSORTB sorts the elements of a real general vector.
ISORTB sorts the elements of an integer general vector.
These routines can perform an in-place or indexed sort in ascending or descending order.
An in-place sort returns the result by overwriting the input vector. An indexed sort returns the result in
another array, leaving the input vector unchanged. The in-place sort offers about 25% better performance.
The following calls illustrate the various sorts provided by these routines.
• CALL SSORTB(’A’, N, X, INCX) – Performs an in-place sort in ascending order.
• CALL ISORTB(’A’, N, X, INCX) – Performs an in-place sort in ascending order.
• CALL SSORTB(’D’, N, X, INCX) – Performs an in-place sort in descending order.
• CALL ISORTB(’D’, N, X, INCX) – Performs an in-place sort in descending order.
• CALL SSORTB(’A’, N, X, INCX, ID, INCD) – Performs an indexed sort in ascending order.
• CALL ISORTB(’A’, N, X, INCX, ID, INCD) – Performs an indexed sort in ascending order.
• CALL SSORTB(’D’, N, X, INCX, ID, INCD) – Performs an indexed sort in descending order.
• CALL ISORTB(’D’, N, X, INCX, ID, INCD) – Performs an indexed sort in descending order.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
ad Character. (input)
Indicates whether to sort in ascending or descending order.
Valid values are ’a’, ’A’, ’d’, and ’D’. Use ’a’ and ’A’ to signify ascending order, and use ’d’ and
’D’ to signify descending order. Because only the first character is significant, to enhance clarity,
you may use ’ascending’ or ’descending’ as the value for ad.

598 004– 2165– 002

SSORTB ( 3F ) SSORTB ( 3F )

n Integer. (input)
Number of elements to be sorted. n > 0.
x SSORTB: Real array of dimension (n– 1) . incx+1. (input and output)
ISORTB: Integer array of dimension (n– 1) . incx+1. (input and output)
Array x contains the values to be sorted. If you specify only four arguments, these routines perform
an in-place sort and use x for output.
incx Integer. (input)
Increment between elements of the array x. incx > 0.
index Integer array of dimension (n– 1) . incd+1. (output, optional)
If specified, array index holds the results of the indexed sort.
In this case, on exit, x may be accessed in sorted order by using index, as follows:
xsorted(k) = x(1 + (index(1 + (k– 1) . incd) – 1) . incx),
for all k = 1, 2, . . ., n
incd Integer. (input)
Increment for the elements of index. incd > 0.

NOTES
Negative increments are not required because ad specifies ascending or descending order.
These sorts are unstable. An unstable sort is one in which the indices of two elements whose values are the
same could be inverted in the sorted output. That is, if x(j) = x(k) for some j < k, and (at the end of the sort)
index(ij) = j and index(ik) = k for some ij and ik, it is possible that ij > ik .
For example, if x(6) = x(15) = 10, at the end of sorting, the subscript at which the array index takes on the
value 6 may be larger than the subscript at which index takes on the value 15.
If the number of arguments is 4, the routine performs an in-place sort. If the number of arguments is 6, the
routine performs an indexed sort.

EXAMPLES

In-place Sorting
Suppose you have a real array X, every other element of which to sort into descending order, then the call is
as follows:
CALL SSORTB ( ’D’, N, X, 2 )

Indexed Sorting
Suppose you have a real array X, every third element of which to sort into ascending order without
destroying X, then an indexed sort is done, as follows:
CALL SSORTB ( ’A’, N, X, 3, ID, INCD )

004– 2165– 002 599

SSORTB ( 3F ) SSORTB ( 3F )

The argument incd allows you extra flexibility in arranging the indexing. For instance, suppose you want to
sort row #2 of matrix A in descending order. Furthermore, suppose you want the result to be stored into the
corresponding row of a matrix of indices, I, with leading dimension LDI. The call is as follows:
CALL SSO RTB( ’D’, N, A( 2,1 ), LDA, I( 2,1 ), LDI )

The following program is an example of a row-by-row indexed sort of a 4-by-5 rectangular matrix into
ascending order. This example shows how to access the ordered version of A by using the index array, MID.
Following the program is its output. The output demonstrates the values to which SSORTB initializes MID.
It also presents the values in the unsorted matrix, A. It then presents the results of a call to SSORTB. First
the values in A are presented in sorted order; then the corresponding values in MID are output. That way
you can apply the final results in MID to the unsorted version of A and see how the indexed sort works. The
final values in MID are such that
A(i,MID(i,1)) ≤ A(i,MID(i,2)). . . ≤ A(i,MID(i,5)).
PROGRA M TSS ORTB
*----- --- --- --------- --- ------ ------------ ------------ ------------ -----
* ..P ara meters..
INT EGE R ROW , COL , MAX
PARAMETER ( ROW =4, COL=5, MAX =9 )

* ..Scal ar vars..
INTEGE R I, J

* ..V ect or vars..

REA L A( ROW,CO L )
INT EGE R MID ( ROW ,COL )

*----- ------ ------ --- --------- --- --------- --- ------------ ------------ --
* ..B egin execut ion ..

* Loa d A() wit h number s bet ween 1. and max .

DO I = 1, ROW
DO J = 1, COL
A( I,J ) = 1. + REAL( MOD( I*J, MAX ) )
END DO
END DO

* Initia lize MID ()

DO I = 1, ROW
DO J = 1, COL
MID ( I,J ) = J
END DO
END DO

600 004– 2165– 002

SSORTB ( 3F ) SSORTB ( 3F )

*----- --- --------- --- --------- --- --------- --- ------ --- --- --- ------ -----
PRINT *, " ... Indice s in MID () prior to ind exe d sor t ",
& "of eac h row of A() ... "
DO I = 1, ROW
WRITE( 6,2 0 ) ( MID ( I,J ), J=1 ,CO L )
END DO

PRI NT *, " ... A() pri or to row-by -ro w sor t ... "
DO I = 1, ROW
WRITE( 6,1 0 ) ( A( I,J ), J=1,CO L )
END DO

*-- --- --------- --- --------- --- --------- --- ------ --- ------ --- --- --------
* Sort eac h col umn in asc ending ord er.
DO I = 1, ROW
CALL SSORTB( ’ASCENDIN G’, COL , A( I,1 ), ROW ,
& MID ( I,1 ), ROW )
END DO

*----- --- --------- --- --------- --- --------- --- ------ --- --- --- ------ -----
PRI NT *, " ... A() aft er row -by -ro w sort ..."
DO I = 1, ROW
WRITE( 6,1 0 ) ( A( I,M ID( I,J ) ), J=1,CO L )
END DO

PRI NT *, " ... Indices in MID() after the ind exe d sort ",
& "of eac h row of A() ... "
DO I = 1, ROW
WRI TE( 6,2 0 ) ( MID ( I,J ), J=1 ,CO L )
END DO

*-- ------ ------ ------ ------ ------ ------ ------ --- ------ --- --- --- ------ --
* ..Form at sta tement s..
10 FOR MAT( 5X, 5( F5.1, 2X ) )
20 FOR MAT( 5X, 5( I5, 2X ) )
END

004– 2165– 002 601

SSORTB ( 3F ) SSORTB ( 3F )

The results of program TSSORTB are as follows:

... Ind ices in MID () pri or to indexed sort of each row of A() ...
1 2 3 4 5
1 2 3 4 5
1 2 3 4 5
1 2 3 4 5
... A() prior to row -by -row sort ...
2.0 3.0 4.0 5.0 6.0
3.0 5.0 7.0 9.0 2.0
4.0 7.0 1.0 4.0 7.0
5.0 9.0 4.0 8.0 3.0
... A() aft er row-by -ro w sort ...
2.0 3.0 4.0 5.0 6.0
2.0 3.0 5.0 7.0 9.0
1.0 4.0 4.0 7.0 7.0
3.0 4.0 5.0 8.0 9.0
... Indice s in MID () after the indexed sort of each row of A() ...
1 2 3 4 5
5 1 2 3 4
3 4 1 2 5
5 3 1 4 2

The following example illustrates the use of ISORTB to perform a column-by-column in-place sort of a
5-by-4 rectangular matrix into descending order.
PRO GRAM TISORT B
*----- ------ --- ------ ------ --- ------ --------- --- ------------ -----------
* ..Para met ers..
INT EGER ROW, COL, MAX
PARAME TER( ROW=5, COL=4, MAX =9 )

* ..S calar var s..

INT EGER I, J

* ..Vect or vars..
INT EGE R IA( ROW ,CO L )

602 004– 2165– 002

SSORTB ( 3F ) SSORTB ( 3F )

*----- --- --------- --- --------- --- --------- --- ------ --- --- --- ------ --- --
* ..Begin execution ..

* Ini tializ e IA() wit h number s betwee n 1 and max.

DO I = 1, ROW
DO J = 1, COL
IA( I,J ) = 1 + MOD( I*J, MAX )
END DO
END DO

*----- ------ ------ ------ ------ ------ ------ ------ --- --- ------ --- --- -----
PRI NT *, " ... IA() prior to col umn -by -co lumn sort ..."
DO I = 1, ROW
WRI TE( 6,1 0 ) ( IA( I,J ), J=1 ,COL )
END DO

*-- ------ ------ ------ ------ ------ ------ ------ --- ------ --- --- --- ------ --
* Per form an in-place sor t on IA in des cendin g ord er on
* eac h col umn .
DO J = 1, COL
CALL ISO RTB( ’DE SCENDI NG’, ROW , IA( 1,J ), 1 )
END DO

*-- --- --------- --- --------- --- --------- --- ------ --- ------ --- --- --- -----
PRI NT *, " ... IA() aft er col umn -by -colum n sor t ... "
DO I = 1, ROW
WRI TE( 6,1 0 ) ( IA( I,J ), J=1 ,COL )
END DO

*-- ------ ------ ------ ------ ------ ------ ------ --- ------ --- --- --- ------ --
* ..Form at sta tement s..
10 FORMAT ( 5X, 4( I5, 2X ) )
STOP
END

004– 2165– 002 603

SSORTB ( 3F ) SSORTB ( 3F )

The results of program TISORTB are as follows:

... IA() pri or to column-by -co lumn sort ...
2 3 4 5
3 5 7 9
4 7 1 4
5 9 4 8
6 2 7 3
... IA() aft er col umn-by-co lum n sor t ...
6 9 7 9
5 7 7 8
4 5 4 5
3 3 4 4
2 2 1 3

604 004– 2165– 002

WHENEQ ( 3F ) WHENEQ ( 3F )

NAME
WHENEQ, WHENNE – Searches a vector for all elements equal or not equal to a target

SYNOPSIS
CALL WHENEQ (n, x, incx, target, index, nn)
CALL WHENNE (n, x, incx, target, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
WHENEQ searches a real or integer vector for all elements equal to a real or integer target.
WHENNE searches a real or integer vector for all elements not equal to a real or integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x containing the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
target Real or integer. (input)
Value for which to search in the array.
index Integer array of dimension n. (output)
Array index contains the indices in the array elements that match target.
nn Integer. (output)
Number of values put in the index array.

NOTES

When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)

004– 2165– 002 605

WHENEQ ( 3F ) WHENEQ ( 3F )

The desired values are at:

x(1+(index(k)– 1) . incx) when incx > 0
x(1+(index(k)– n) . incx) when incx < 0
for all k = 1, 2, . . ., nn .

606 004– 2165– 002

WHENFLT ( 3F ) WHENFLT ( 3F )

NAME
WHENFLT, WHENFLE, WHENFGT, WHENFGE – Searches a real vector for all elements with a specified
logical relationship to a real target

SYNOPSIS
CALL WHENFLT (n, x, incx, target, index, nn)
CALL WHENFLE (n, x, incx, target, index, nn)
CALL WHENFGT (n, x, incx, target, index, nn)
CALL WHENFGE (n, x, incx, target, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
WHENFLT searches a real vector for all elements that are less than a real target.
WHENFLE searches a real vector for all elements that are less than or equal to a real target.
WHENFGT searches a real vector for all elements that are greater than a real target.
WHENFGE searches a real vector for all elements that are greater than or equal to a real target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements of the array to be searched.
x Real array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
target Real. (input)
Value for which array is searched.
index Integer array of dimension n. (output)
Array index contains the indices in the array elements that match target.
nn Integer. (output)
Number of values put in the index array.

004– 2165– 002 607

WHENFLT ( 3F ) WHENFLT ( 3F )

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired values are at:
x(1+(index(k)– 1) . incx) when incx > 0
x(1+(index(k)– n) . incx) when incx < 0
for all k = 1, 2, . . ., nn.

608 004– 2165– 002

WHENILT ( 3F ) WHENILT ( 3F )

NAME
WHENILT, WHENILE, WHENIGT, WHENIGE – Searches an integer vector for all elements that have a
specified relationship to an integer target

SYNOPSIS
CALL WHENILT (n, x, incx, itarget, index, nn)
CALL WHENILE (n, x, incx, itarget, index, nn)
CALL WHENIGT (n, x, incx, itarget, index, nn)
CALL WHENIGE (n, x, incx, itarget, index, nn)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
WHENILT searches an integer vector for all elements that are less than an integer target.
WHENILE searches an integer vector for all elements that are less than or equal to an integer target.
WHENIGT searches an integer vector for all elements that are greater than an integer target.
WHENIGE searches an integer vector for all elements that are greater than or equal to an integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements in the array to be searched.
x Integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
incx Integer. (input)
Increment between elements of the searched array.
itarget Integer. (input)
Value for which the array is searched.
index Integer array of dimension n. (output)
Array index contains the indices in the array elements that match target.
nn Integer. (output)
Number of values put in the index array.

004– 2165– 002 609

WHENILT ( 3F ) WHENILT ( 3F )

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired values are at:
x(1+(index(k)– 1) . incx) when incx > 0
x(1+(index(k)– n) . incx) when incx < 0
for all k = 1, 2, . . ., nn.

610 004– 2165– 002

WHENMEQ ( 3F ) WHENMEQ ( 3F )

NAME
WHENMEQ, WHENMNE – Searches a vector for all elements whose subfields are equal or not equal to a target

SYNOPSIS
CALL WHENMEQ (n, x, incx, itarget, index, nn, mask, iright)
CALL WHENMNE (n, x, incx, itarget, index, nn, mask, iright)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
WHENMEQ searches a real or integer vector for all elements for which the subfield defined by mask and iright
is equal to an integer target.
WHENMNE searches a real or integer vector for all elements for which the subfield defined by mask and iright
is not equal to an integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
itarget Integer. (input)
Value for which to search in the array.
index Integer array of dimension n. (output)
Array index contains the indices of the array elements whose subfield is equal or not equal to
itarget.
nn Integer. (output)
Number of values put in the index array.
mask Integer. (input)
Mask of 1’s (set bits) from the right. The number of set bits in mask is the number of bits in the
subfield, which is searched in each element of the input array.
iright Integer. (input)
Number of bits to shift each element of the input array to the right so as to right justify the
subfield searched.

004– 2165– 002 611

WHENMEQ ( 3F ) WHENMEQ ( 3F )

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired values are at:
x(1+(index(k)– 1) . incx) when incx > 0
x(1+(index(k)– n) . incx) when incx < 0
for all k = 1, 2, . . ., nn.

612 004– 2165– 002

WHENMLT ( 3F ) WHENMLT ( 3F )

NAME
WHENMLT, WHENMLE, WHENMGT, WHENMGE – Searches a vector for all elements whose subfields have a
specified logical relationship with a target

SYNOPSIS
CALL WHENMLT (n, x, incx, itarget, index, nn, mask, iright)
CALL WHENMLE (n, x, incx, itarget, index, nn, mask, iright)
CALL WHENMGT (n, x, incx, itarget, index, nn, mask, iright)
CALL WHENMGE (n, x, incx, itarget, index, nn, mask, iright)

IMPLEMENTATION
UNICOS systems

DESCRIPTION
WHENMLT searches a real or integer vector for all elements for which the subfield defined by mask and iright
is less than an integer target.
WHENMLE searches a real or integer vector for all elements for which the subfield defined by mask and iright
is less than or equal to an integer target.
WHENMGT searches a real or integer vector for all elements for which the subfield defined by mask and iright
is greater than an integer target.
WHENMGE searches a real or integer vector for all elements for which the subfield defined by mask and iright
is greater than or equal to an integer target.
When using the CF90 compiler UNICOS systems, all arguments must be of default kind unless documented
otherwise. On UNICOS systems, default kind is KIND=8 for integer, real, complex, and logical arguments.
These routines have the following arguments:
n Integer. (input)
Number of elements to be searched.
x Real or integer array of dimension (n– 1) .  incx  + 1. (input)
Array x contains the vector to be searched.
itarget Integer. (input)
Value for which to search in the array.
index Integer array of dimension n. (output)
Array index contains the indices of the array elements whose subfield is equal or not equal to
itarget.
nn Integer. (output)
Number of values put in the index array.

004– 2165– 002 613

WHENMLT ( 3F ) WHENMLT ( 3F )

mask Integer. (input)

Mask of 1’s (set bits) from the right. The number of set bits in mask is the number of bits in the
subfield, which is searched in each element of the input array.
iright Integer. (input)
Number of bits to shift each element of the input array to the right so as to right justify the
subfield searched.

NOTES
When scanning backward (incx < 0), each routine starts at the end of the vector and moves backward, as
follows:
x(1– incx . (n– 1)), x(1– incx . (n– 2)), . . ., x(1)
The desired values are at:
x(1+(index(k)– 1) . incx) when incx > 0
x(1+(index(k)– n) . incx) when incx < 0
for all k = 1, 2, . . ., nn.

614 004– 2165– 002

CINTER ( 3F ) CINTER ( 3F )

NAME
cinter – Introduction to interfaces to C library routines

IMPLEMENTATION
UNICOS and UNICOS/mk systems

DESCRIPTION
This section contains descriptions of interfaces to C library routines.
A number of Fortran-callable interfaces to C library routines are available under the UNICOS operating
system. These routines give a Fortran programmer access to an extensive number of routines and system
calls found in the C library. The interfaces are simple routines that resolve calling sequence differences and
provide uppercase entry-point names. Argument lists and return values should match those of the
corresponding C routine, except where noted otherwise. Calling sequences for many of these Fortran
interfaces to C routines are documented on the corresponding C library man page. Except where otherwise
noted, data types should be handled as follows:
• C character data may be defined as a Fortran character data type for some of the C routines. See each
man page for a description of the routines that allow this. For the routines that do not accept Fortran
character data types as an argument, C character data should be defined as Fortran integers and terminated
by a null (0) byte. On UNICOS systems, Hollerith data handles this for 1– 7 characters in length.
• C pointers should be handled by Fortran integers.
• Other C data types are compatible with their Fortran counterparts.
When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on UNICOS, UNICOS/mk, or IRIX, all
arguments must be of default kind unless documented otherwise. On UNICOS and UNICOS/mk, default
kind is KIND=8 for integer, real, complex, and logical arguments; on IRIX, the default kind is KIND=4.
Interface routines should be coded as Fortran functions.
Example:
CHARAC TER*8 PAT H, IDA (10)
INTEGE R FOPEN, FWR ITE
PAT H=’fil enm ’
C FOP EN ret urns an int ege r
IST REA M = FOPEN ( PAT H, ’w+ ’ )
IF ( IST REA M .EQ . 0 ) THE N
PRINT *,’FOP EN fai led’
CALL ABO RT

004– 2165– 002 615

CINTER ( 3F ) CINTER ( 3F )

END IF
DO 10 I=1,10
IDA (I)=’t estcas e’
10 CON TIN UE
N=8
J=FWRI TE ( IDA (1) , N, 10, IST REA M )
.
.
.
END

NOTES
The following set of interface routines is provided in the standard UNICOS libraries. See the appropriate
manual or the appropriate online man page for specific usage information.

Purpose Name Heading

Closes or flushes a stream fclose fclose

fflush fflush
Gets integer file descriptor associated with stream fileno ferror
Opens a stream fopen fopen
fdopen
freopen
Gets a string from a stream fgets gets
Puts a string on a stream fputs puts
Performs binary I/O fread fread
fwrite
Repositions a file pointer in a stream fseek fseek
ftell
Returns the current working directory getcwd getcwd
Returns value for environment name getenv* getenv
Gets option letter from argument vector getopt* getopt
Makes a unique file name mktemp mktemp
Changes or adds value to the environment putenv putenv
Suspends execution for a specified interval sleep sleep
Creates a name for a temporary file tempnam tempnam

616 004– 2165– 002

CINTER ( 3F ) CINTER ( 3F )

Purpose Name Heading

Creates a temporary file tmpfile tmpfile

Prints a traceback tracebk tracebk

* Not on UNICOS/mk systems or Cray T90 series.

For the Fortran syntax for the above routines, see the appropriate page in the UNICOS System Libraries
Reference Manual. For more information on Fortran I/O routines, see the Application Programmer’s I/O
Guide.
Many routines which are not supported on UNICOS/mk systems or Cray T90 series are supported as POSIX
1003.9 routines. See the INTRO_PXF(3F) man page for details.

Purpose Name Heading

Determines accessibility of a file access* access

Sets a process alarm clock alarm alarm
Changes working directory chdir* chdir
Changes mode of file chmod* chmod
Changes owner and group of a file chown* chown
Changes root directory chroot* chroot
Closes a file descriptor close close
Selects which processors may run the process cpselect*** cpselect
Creates a new file or rewrites an existing one creat* creat
Terminates a program and specifies status exit exit
Terminates all processes, not just the calling process newexit* exit
Controls open files fcntl fcntl
Creates a new process fork* fork
Gets effective group ID getegid getuid
Gets effective user ID geteuid getuid
Gets group ID getgid getgid
Gets process-group ID getpgrp getpid
Gets process ID getpid getpid
Gets parent process ID getppid getpid

004– 2165– 002 617

CINTER ( 3F ) CINTER ( 3F )

Purpose Name Heading

Returns process ID of multitasking group newgetpid*** getpid

Returns process ID of the multitasking group that created the newgetppid*** getpid
caller’s multitasking group.
Gets user ID getuid getuid
Allocates storage for a file ialloc ialloc
Controls device ioctl ioctl
Sends a signal to a process or a group of processes kill kill
Sets resource limits limit limit
Creates a link to a file link* link
Moves read/write file pointer lseek lseek
Makes a directory, or a special or regular file mknod* mknod
Changes priority of process nice nice
Changes priority of process nicem nice
Opens a file for reading or writing open* open
Suspends process until signal pause pause
Creates an interprocess channel pipe pipe
Locks process in memory plock*** plock
Traces processes ptrace*** ptrace
Performs asynchronous read from a file reada reada
Controls execution of processes resume resume
Changes data segment space allocation sbreak brk
sbrk
brk
Sets group ID setgid*** setuid
Sets process-group ID setpgrp setpgrp
Sets user ID setuid*** setuid
Provides signal control sigctl sigctl
Fortran interface to signal control fsigctl
Pascal interface to signal control psigctl*
Specifies what to do upon receipt of a signal signal signal

618 004– 2165– 002

CINTER ( 3F ) CINTER ( 3F )

Purpose Name Heading

Fortran interface to signal fsignal

Pascal interface to signal psignal
Manages the allocation and deallocation of the secondary data sdsalloc** sdsalloc
segment (SDS) sdsrealc**
sdsfree**
Changes size of secondary data segment (Fortran users should ssbreak**
use the new SDSALLOC routines instead of ssbreak. See
sdsalloc(3F).)
Reads, writes to secondary data segment ssread** ssread
sswrite
Gets file status stat* stat
Controls execution of processes suspend suspend
Flushes system buffers out of main memory sync sync
Gets time time time
Gets process and child process times times times
Truncates a file trunc trunc
Gets and sets user limits ulimit ulimit
Sets and gets file creation mark umask umask
Gets name of current operating system uname* uname
Removes directory entry unlink* unlink
Gets file system statistics ustat ustat
Sets file access and modification times utime* utime
Awaits completion of process wait* wait
Performs asynchronous write on a file writea writea

* Not available on UNICOS/mk systems or Cray T90 series.

** See sdsalloc(3F) for restrictions when using these routines on UNICOS/mk systems.
*** Not available on UNICOS/mk systems.
The argument lists of the uname(3) and time(3) routines differ from those of the corresponding C routines.
No arguments can be used with the Fortran call to time. See the man page in this manual for the correct
syntax when calling uname from Fortran.

004– 2165– 002 619

CINTER ( 3F ) CINTER ( 3F )

The third argument of Fortran routines ssread(2) and sswrite(3) specifies the number of words to be
read or written. This is different from the corresponding system call. See the WARNING section of the
SDSALLOC(3F) routine in this manual for cautions on using ssbreak(2) in Fortran programs.
For more information on Fortran I/O routines, see the Application Programmer’s I/O Guide.
General Usage Example
When a system call or library function has a pointer to a data structure as an argument, the corresponding
Fortran callable routine requires a pointer to a data entity at least as large as the structure. Any exception to
this requirement is documented in the specific man page.
Accessing the fields of a structure from Fortran may not be possible when the structure contains multiple
data types or when the structure uses a data type not recognized by Fortran.
For a few library routines and system calls, alternate Fortran callable entry points provide a simpler method
of accessing structures. These entry points being with the prefix pxf. See pxfintget(3F) for details.
An example of a call to the UTIME() system call from a Fortran program follows. The second argument to
UTIME is a pointer to a structure of type utimbuf. This structure is defined as follows:
struct uti mbuf {
tim e_t actime ;
tim e_t mod time;
}

In the following example, the Fortran programmer uses an integer array to hold the structure. The first word
of the array contains the actime field; the second word contains the modtime field.
PRO GRA M UTI M
INT EGE R TIM E, UTI ME
INT EGER UT(2)
I = TIM E()
UT( 1) = I
UT( 2) = I
C Upd ate the acc ess and mod ifi cat ion times of file ’myfil e’
C to the cur rent tim e
I = UTI ME(’my file’, UT)
IF (I.EQ. -1) THEN
PRI NT *, ’UT IME FAI LED ’
END IF
END

620 004– 2165– 002

INDEX

60-bit integer to Cray Research 64-bit integer conversion ............................. int6064(3F)........................................................ 375
60-bit pack and unpack ................................................................................... p6460(3F) ............................................................ 497
60-bit single-precision to 64-bit single-precision conversion ......................... fp6064(3F) .......................................................... 359
64-bit complex conversion .............................................................................. vxzctc(3F) .......................................................... 413
64-bit D format to single-precision conversion .............................................. vxdctc(3F) .......................................................... 399
64-bit integer to 60-bit integer conversion ..................................................... int6460(3F)........................................................ 376
64-bit logical to VAX logical conversion ....................................................... vxlcti(3F) .......................................................... 409
64-bit single-precision conversion .................................................................. usscti(3F) .......................................................... 391
Abort job ......................................................................................................... errexit(3F)........................................................ 422
Abort job (with traceback) .............................................................................. abort(3F) ............................................................ 419
ABORT(3F) ...................................................................................................... abort(3F) ............................................................ 419
abort(3F) ...................................................................................................... abort(3F) ............................................................ 419
Absolute value ................................................................................................. isamax(3F) .......................................................... 562
Active subroutine list ...................................................................................... trbk(3F)............................................................... 520
Adds a word to a table ................................................................................... tmadw(3F) ............................................................ 459
Adjust heap block ........................................................................................... hpnewlen(3F) ..................................................... 455
Allocate memory from heap ........................................................................... hpalloc(3F)........................................................ 450
Allocated heap block change .......................................................................... hpnewlen(3F) ..................................................... 455
Allocates a block of memory from the heap .................................................. hpalloc(3F)........................................................ 450
Allocates table space ....................................................................................... tmats(3F) ............................................................ 461
Argument ......................................................................................................... iargc(3F) ............................................................ 430
Array byte or bit move ................................................................................... mov(3F) ................................................................. 489
Array byte replace ........................................................................................... byt(3F) ................................................................. 479
ASCDC(3F) ...................................................................................................... dsasc(3F) ............................................................ 355
ascdc(3F) ...................................................................................................... dsasc(3F) ............................................................ 355
ASCII conversion functions ............................................................................ intro_conversion(3F) .................................. 327
ASCII from binary conversion ........................................................................ b2oct(3F) ............................................................ 333
ASCII from time ............................................................................................. tsdt(3F)............................................................... 528
ASCII to EBCDIC conversion ........................................................................ uscctc(3F) .......................................................... 381
ASCII to integer conversion ........................................................................... chconv(3F) .......................................................... 338
ASCII to time-stamp conversion .................................................................... dtts(3F)............................................................... 480
Auxiliary array variables access ..................................................................... auxstat(3F)........................................................ 473
AUXSTAT(3F) ................................................................................................. auxstat(3F)........................................................ 473
auxstat(3F) ................................................................................................. auxstat(3F)........................................................ 473
B2OCT(3F) ...................................................................................................... b2oct(3F) ............................................................ 333
b2oct(3F) ...................................................................................................... b2oct(3F) ............................................................ 333
Barrier synchronization with tasks .................................................................. set_barrier(3C) .............................................. 539
Barrier synchronization with tasks .................................................................. wait_barrier(3C) ........................................... 544
Batcher’s odd-even merge sort ....................................................................... ssortb(3F) .......................................................... 598
Bidirectional memory transfer ........................................................................ sensebt(3F)........................................................ 441
Bidirectional memory transfer (enable/disable) .............................................. clearbt(3F)........................................................ 420
Binary to character conversion ....................................................................... b2oct(3F) ............................................................ 333
Binary to octal conversion .............................................................................. b2oct(3F) ............................................................ 333
Bit mask creation ............................................................................................ bitvec(3F) .......................................................... 474
Bit mask creation ............................................................................................ bitvecm(3F)........................................................ 477
Bit move .......................................................................................................... mov(3F) ................................................................. 489
BITVEC(3F) .................................................................................................... bitvec(3F) .......................................................... 474

004– 2165– 002 Index-1

bitvec(3F) .................................................................................................... bitvec(3F) .......................................................... 474
BITVECM(3F) ................................................................................................. bitvecm(3F)........................................................ 477
bitvecm(3F) ................................................................................................. bitvecm(3F)........................................................ 477
Block address validity ..................................................................................... ihpvalid(3F) ..................................................... 458
Block extend or copy ...................................................................................... hpclmove(3F) ..................................................... 452
Block length heap ........................................................................................... ihplen(3F) .......................................................... 457
Block of memory to heap ............................................................................... hpdeallc(3F) ..................................................... 453
byt(3F) ........................................................................................................... byt(3F) ................................................................. 479
Byte move ....................................................................................................... mov(3F) ................................................................. 489
Byte replacement ............................................................................................. byt(3F) ................................................................. 479
C snapshot dump ............................................................................................. symdump(3F)........................................................ 511
Calling sequence information ......................................................................... trbklvl(3F)........................................................ 521
Calling sequence list ....................................................................................... trbk(3F)............................................................... 520
CDC 60-bit integer conversion ....................................................................... int6064(3F)........................................................ 375
CDC 60-bit single-precision conversion ......................................................... fp6064(3F) .......................................................... 359
CDC display code characters (conversion) ..................................................... dsasc(3F) ............................................................ 355
CDC to ASCII character conversion .............................................................. dsasc(3F) ............................................................ 355
CDC to Cray conversion ................................................................................. cdc2cray(3F) ..................................................... 335
CDC2CRAY(3F) ............................................................................................... cdc2cray(3F) ..................................................... 335
cdc2cray(3F) ............................................................................................... cdc2cray(3F) ..................................................... 335
C/Fortran interface .......................................................................................... cinter(3F) .......................................................... 615
Change length of block ................................................................................... hpclmove(3F) ..................................................... 452
Changes the size of an allocated heap block .................................................. hpnewlen(3F) ..................................................... 455
Character conversion (CDC to ASCII) ........................................................... dsasc(3F) ............................................................ 355
Character conversion (IEEE floating-point to Cray) ...................................... cry2cri(3F)........................................................ 349
Character conversion (IEEE floating-point to Cray) ...................................... cry2mips(3F) ..................................................... 352
Character conversion (IEEE floating-point to MIPS) ..................................... ieg2mips(3F) ..................................................... 369
Character conversion (IEEE floating-point to MIPS) ..................................... vax2mips(3F) ..................................................... 396
Character conversion (IEEE to Cray) ............................................................. cri2cray(3F) ..................................................... 340
Character conversion (IEEE to Cray) ............................................................. cri2ibm(3F)........................................................ 343
Character conversion (IEEE to Cray) ............................................................. ieg2cray(3F) ..................................................... 363
Character conversion (IEEE to Cray) ............................................................. ieg2cri_77(3F) ................................................ 366
Character conversion (IEEE to Cray) ............................................................. ieu2cray(3F) ..................................................... 372
Character count without trailing blanks .......................................................... trimlen(3F)........................................................ 524
Character move ............................................................................................... mvc(3F) ................................................................. 493
CHCONV(3F) .................................................................................................... chconv(3F) .......................................................... 338
chconv(3F) .................................................................................................... chconv(3F) .......................................................... 338
Check heap ...................................................................................................... hpcheck(3F)........................................................ 451
Checkpoint program ........................................................................................ shutdsav(3F) ..................................................... 504
Checks the integrity of the heap ..................................................................... hpcheck(3F)........................................................ 451
Checks to see whether two files have the same inode number ...................... samefile(3F) ..................................................... 440
cinter(3F) .................................................................................................... cinter(3F) .......................................................... 615
Clear multitasking event ................................................................................. clear_event(3C) .............................................. 536
CLEARBT(3F) ................................................................................................. clearbt(3F)........................................................ 420
clearbt(3F) ................................................................................................. clearbt(3F)........................................................ 420
CLEAR_EVENT(3C) ....................................................................................... clear_event(3C) .............................................. 536
clear_event(3C) ....................................................................................... clear_event(3C) .............................................. 536
CLEARFI(3F) ................................................................................................. clearfi(3F)........................................................ 421
clearfi(3F) ................................................................................................. clearfi(3F)........................................................ 421
Clears an event and returns control to the calling PE .................................... clear_event(3C) .............................................. 536

Index-2 004– 2165– 002

CLUSEQ(3F) .................................................................................................... cluseq(3F) .......................................................... 551
cluseq(3F) .................................................................................................... cluseq(3F) .......................................................... 551
CLUSFGE(3F) ................................................................................................. clusflt(3F)........................................................ 553
clusfge(3F) ................................................................................................. clusflt(3F)........................................................ 553
CLUSFGT(3F) ................................................................................................. clusflt(3F)........................................................ 553
clusfgt(3F) ................................................................................................. clusflt(3F)........................................................ 553
CLUSFLE(3F) ................................................................................................. clusflt(3F)........................................................ 553
clusfle(3F) ................................................................................................. clusflt(3F)........................................................ 553
CLUSFLT(3F) ................................................................................................. clusflt(3F)........................................................ 553
clusflt(3F) ................................................................................................. clusflt(3F)........................................................ 553
CLUSIGE(3F) ................................................................................................. clusilt(3F)........................................................ 555
clusige(3F) ................................................................................................. clusilt(3F)........................................................ 555
CLUSIGT(3F) ................................................................................................. clusilt(3F)........................................................ 555
clusigt(3F) ................................................................................................. clusilt(3F)........................................................ 555
CLUSILE(3F) ................................................................................................. clusilt(3F)........................................................ 555
clusile(3F) ................................................................................................. clusilt(3F)........................................................ 555
CLUSILT(3F) ................................................................................................. clusilt(3F)........................................................ 555
clusilt(3F) ................................................................................................. clusilt(3F)........................................................ 555
CLUSNE(3F) .................................................................................................... cluseq(3F) .......................................................... 551
clusne(3F) .................................................................................................... cluseq(3F) .......................................................... 551
Cluster ............................................................................................................. cluseq(3F) .......................................................... 551
Cluster ............................................................................................................. clusflt(3F)........................................................ 553
Cluster ............................................................................................................. clusilt(3F)........................................................ 555
Cluster search .................................................................................................. cluseq(3F) .......................................................... 551
Cluster search .................................................................................................. clusflt(3F)........................................................ 553
Cluster search .................................................................................................. clusilt(3F)........................................................ 555
Command-line arguments ............................................................................... getoarg(3F)........................................................ 426
Command-line arguments ............................................................................... getoargc(3F) ..................................................... 427
Complex conversion from VAX ..................................................................... vxzctc(3F) .......................................................... 413
Complex conversion (IEEE to Cray) .............................................................. cri2cray(3F) ..................................................... 340
Complex conversion (IEEE to Cray) .............................................................. ieg2cray(3F) ..................................................... 363
Complex conversion (IEEE to Cray) .............................................................. ieg2cri_77(3F) ................................................ 366
Complex conversion (IEEE to Cray) .............................................................. ieu2cray(3F) ..................................................... 372
Compresses stored data ................................................................................... pack(3F)............................................................... 494
Compute integer ceiling .................................................................................. iceil(3F) ............................................................ 487
Controls receipt of signals .............................................................................. sigoff(3F) .......................................................... 506
Conversion of 64-bit integer to VAX integer ................................................. vxicti(3F) .......................................................... 406
Conversion (real) to VAX F ........................................................................... vxscti(3F) .......................................................... 411
Conversion routines ........................................................................................ intro_conversion(3F) .................................. 327
Conversion subprograms ................................................................................. intro_conversion(3F) .................................. 327
Conversion to VAX floating-point .................................................................. vxscti(3F) .......................................................... 411
Convert ASCII to integer ................................................................................ chconv(3F) .......................................................... 338
Convert between VAX and Cray .................................................................... vax2cray(3F) ..................................................... 393
Convert binary to octal ................................................................................... b2oct(3F) ............................................................ 333
Convert data to and from Cray ....................................................................... cri2cray(3F) ..................................................... 340
Convert data to and from Cray ....................................................................... cry2cri(3F)........................................................ 349
Convert data to and from Cray ....................................................................... cry2mips(3F) ..................................................... 352
Convert data to and from Cray ....................................................................... ieg2cray(3F) ..................................................... 363
Convert data to and from Cray ....................................................................... ieg2cri_77(3F) ................................................ 366
Convert data to and from Cray ....................................................................... ieu2cray(3F) ..................................................... 372

004– 2165– 002 Index-3

Convert data to and from IEEE generic and Cray IEEE ................................ cri2ieg(3F)........................................................ 346
Convert floating-point from VAX ................................................................... vxsctc(3F) .......................................................... 410
Convert time .................................................................................................... dtts(3F)............................................................... 480
Convert time to ASCII .................................................................................... tsdt(3F)............................................................... 528
Converts a Cray Research 64-bit integer to an IBM packed-decimal field ... usictp(3F) .......................................................... 387
Converts ASCII date and time to time stamp ................................................ dtts(3F)............................................................... 480
Converts between CDC 60-bit and Cray Research 64-bit numbers ............... fp6064(3F) .......................................................... 359
Converts between IBM INTEGER*2/INTEGER*4 and Cray Research
64-bit integer numbers .................................................................................... usictc(3F) .......................................................... 385
Converts between IBM LOGICAL*1/LOGICAL*4 and Cray Research
64-bit logical values ........................................................................................ uslctc(3F) .......................................................... 388
Converts CDC 60-bit integers to Cray Research 64-bit integers ................... int6064(3F)........................................................ 375
Converts CDC data to Cray Research format and vice versa ........................ cdc2cray(3F) ..................................................... 335
Converts CDC display code character to ASCII character and vice versa .... dsasc(3F) ............................................................ 355
Converts Cray 64-bit integers to VAX INTEGER*2 (16 bit) or
INTEGER*4 (32 bit) numbers ........................................................................ vxicti(3F) .......................................................... 406
Converts Cray 64-bit single-precision, floating-point numbers to IBM
64-bit double-precision numbers ..................................................................... usdcti(3F) .......................................................... 384
Converts Cray Research 128-bit complex numbers to VAX 64-bit
complex numbers ............................................................................................ vxzcti(3F) .......................................................... 414
Converts Cray Research 64-bit integers to CDC 60-bit integers ................... int6460(3F)........................................................ 376
Converts Cray Research 64-bit logical numbers to VAX 32-bit logical
numbers ........................................................................................................... vxlcti(3F) .......................................................... 409
Converts Cray Research 64-bit single-precision, floating-point numbers to
IBM 32-bit single-precision numbers ............................................................. usscti(3F) .......................................................... 391
Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX D-format, 64-bit, double-precision, floating-point
numbers ........................................................................................................... vxdcti(3F) .......................................................... 400
Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX F format, 32-bit, single-precision, floating-point
numbers ........................................................................................................... vxscti(3F) .......................................................... 411
Converts Cray Research 64-bit single-precision, floating-point (real)
numbers to VAX G-format, 64-bit, single-precision, floating-point
numbers ........................................................................................................... vxgcti(3F) .......................................................... 403
Converts Cray Research IEEE Fortran data types to IBM (360/370-style)
Fortran data types ............................................................................................ cri2ibm(3F)........................................................ 343
Converts DEC ULTRIX/generic little-endian 32-bit data to Cray
Research 64-bit data and vice versa ............................................................... ieu2cray(3F) ..................................................... 372
Converts decimal ASCII numerals to an integer value .................................. chconv(3F) .......................................................... 338
Converts EBCDIC character data to ASCII character data, and vice versa .. uscctc(3F) .......................................................... 381
Converts ETA/CYBER 205 data to Cray Research format and vice versa ... eta2cray(3F) ..................................................... 356
Converts Fortran data types between Cray floating-point and IEEE
floating-point systems ..................................................................................... cry2cri(3F)........................................................ 349
Converts Fortran data types between Cray Fortran data types and MIPS
IEEE Fortran data types .................................................................................. cry2mips(3F) ..................................................... 352
Converts Fortran data types between Cray IEEE and generic IEEE data
types ................................................................................................................ cri2ieg(3F)........................................................ 346
Converts generic IEEE data to MIPS IEEE data and vice versa ................... ieg2mips(3F) ..................................................... 369
Converts generic IEEE data to MIPS IEEE data and vice versa ................... vax2mips(3F) ..................................................... 396

Index-4 004– 2165– 002

Converts IBM 32-bit floating-point numbers to Cray Research 64-bit
single-precision numbers ................................................................................. ussctc(3F) .......................................................... 390
Converts IBM 64-bit floating-point numbers to Cray Research 64-bit,
single-precision numbers ................................................................................. usdctc(3F) .......................................................... 383
Converts IBM data to Cray Research format and vice versa ......................... ibm2cray(3F) ..................................................... 360
Converts IEEE 32-bit data to Cray Research IEEE 64-bit data and vice
versa ................................................................................................................ ieg2cri_77(3F) ................................................ 366
Converts IEEE/Generic 32-bit data to Cray Research 64-bit data and vice
versa ................................................................................................................ ieg2cray(3F) ..................................................... 363
Converts IEEE/MPP 64-bit data to Cray Research PVP 64-bit data and
vice versa ........................................................................................................ cri2cray(3F) ..................................................... 340
Converts machine time (real-time clock value) to time stamp ....................... mtts(3F)............................................................... 492
Converts NOS/VE data to Cray Research format and vice versa .................. nve2cray(3F) ..................................................... 377
Converts specified number of bytes of IBM packed-decimal field to
64-bit integer field ........................................................................................... uspctc(3F) .......................................................... 389
Converts time stamp to machine time (real-time clock value) ....................... tsmt(3F)............................................................... 529
Converts time stamps to ASCII date and time strings ................................... tsdt(3F)............................................................... 528
Converts trailing blanks to nulls and vice versa ............................................. rbn(3F) ................................................................. 380
Converts VAX 32-bit floating-point numbers to Cray Research 64-bit
single-precision real numbers ......................................................................... vxsctc(3F) .......................................................... 410
Converts VAX 32-bit logical numbers to Cray Research 64-bit logical
numbers ........................................................................................................... vxlctc(3F) .......................................................... 408
Converts VAX 64-bit complex numbers to Cray Research 128-bit
complex numbers ............................................................................................ vxzctc(3F) .......................................................... 413
Converts VAX 64-bit, D-format numbers to Cray Research 64-bit
single-precision numbers ................................................................................. vxdctc(3F) .......................................................... 399
Converts VAX 64-bit G-format numbers to Cray Research 64-bit
single-precision numbers ................................................................................. vxgctc(3F) .......................................................... 402
Converts VAX data to Cray Research format and vice versa ........................ vax2cray(3F) ..................................................... 393
Converts VAX INTEGER*2 (16 bits) or INTEGER*4 (32 bits) to Cray
Research 64-bit integers .................................................................................. vxictc(3F) .......................................................... 405
Copy block ...................................................................................................... hpclmove(3F) ..................................................... 452
Count arguments ............................................................................................. iargc(3F) ............................................................ 430
Counting sort ................................................................................................... isortd(3F) .......................................................... 566
CPU time elapsed ............................................................................................ second(3F) .......................................................... 500
CPU time in real-time clock ticks (Fortran) ................................................... icpused(3F)........................................................ 488
CPU time remaining ....................................................................................... tremain(3F)........................................................ 523
Cray 64-bit conversion (single-precision floating-point) ................................ usdcti(3F) .......................................................... 384
Cray 64-bit integer conversion (and IBM) ..................................................... usictc(3F) .......................................................... 385
Cray 64-bit integer to VAX integer conversion ............................................. vxicti(3F) .......................................................... 406
Cray 64-bit logical to VAX logical conversion .............................................. vxlcti(3F) .......................................................... 409
Cray 64-bit single-precision conversion ......................................................... fp6064(3F) .......................................................... 359
Cray 64-bit single-precision floating-point (conversion) ................................ vxgcti(3F) .......................................................... 403
Cray 64-bit single-precision to floating-point conversion .............................. vxdcti(3F) .......................................................... 400
Cray complex to VAX complex conversion ................................................... vxzcti(3F) .......................................................... 414
Cray IEEE to IBM conversion ........................................................................ cri2ibm(3F)........................................................ 343
Cray logical to LOGICAL*1 conversion ........................................................ uslctc(3F) .......................................................... 388
Cray logical to LOGICAL*4 conversion ........................................................ uslctc(3F) .......................................................... 388
Cray Research 64-bit integer conversion (and CDC) ..................................... int6460(3F)........................................................ 376
Cray to CDC conversion ................................................................................. cdc2cray(3F) ..................................................... 335

004– 2165– 002 Index-5

Cray to ETA/Cyber 205 conversion ............................................................... eta2cray(3F) ..................................................... 356
Cray to IBM conversion ................................................................................. ibm2cray(3F) ..................................................... 360
Cray to NOS/VE conversion ........................................................................... nve2cray(3F) ..................................................... 377
Cray to VAX conversion ................................................................................ vax2cray(3F) ..................................................... 393
Cray to VAX conversion (complex) ............................................................... vxzcti(3F) .......................................................... 414
Cray to VAX conversion (floating-point to VAX) ......................................... vxgcti(3F) .......................................................... 403
CRAY-2 environment variables ...................................................................... reprieve(3F) ..................................................... 498
CRAY2CDC(3F) ............................................................................................... cdc2cray(3F) ..................................................... 335
cray2cdc(3F) ............................................................................................... cdc2cray(3F) ..................................................... 335
CRAY2CRI(3F) ............................................................................................... cri2cray(3F) ..................................................... 340
cray2cri(3F) ............................................................................................... cri2cray(3F) ..................................................... 340
CRAY2ETA(3F) ............................................................................................... eta2cray(3F) ..................................................... 356
cray2eta(3F) ............................................................................................... eta2cray(3F) ..................................................... 356
CRAY2IBM(3F) ............................................................................................... ibm2cray(3F) ..................................................... 360
cray2ibm(3F) ............................................................................................... ibm2cray(3F) ..................................................... 360
CRAY2IEC(3F) ............................................................................................... cry2cri(3F)........................................................ 349
cray2iec(3F) ............................................................................................... cry2cri(3F)........................................................ 349
CRAY2IEG(3F) ............................................................................................... ieg2cray(3F) ..................................................... 363
cray2ieg(3F) ............................................................................................... ieg2cray(3F) ..................................................... 363
CRAY2IEU(3F) ............................................................................................... ieu2cray(3F) ..................................................... 372
cray2ieu(3F) ............................................................................................... ieu2cray(3F) ..................................................... 372
CRAY2NVE(3F) ............................................................................................... nve2cray(3F) ..................................................... 377
cray2nve(3F) ............................................................................................... nve2cray(3F) ..................................................... 377
CRAY2VAX(3F) ............................................................................................... vax2cray(3F) ..................................................... 393
cray2vax(3F) ............................................................................................... vax2cray(3F) ..................................................... 393
CRAYDUMP(3F) ............................................................................................... craydump(3F) ..................................................... 449
craydump(3F) ............................................................................................... craydump(3F) ..................................................... 449
CRI2CRAY(3F) ............................................................................................... cri2cray(3F) ..................................................... 340
cri2cray(3F) ............................................................................................... cri2cray(3F) ..................................................... 340
CRI2CRY(3F) ................................................................................................. cry2cri(3F)........................................................ 349
cri2cry(3F) ................................................................................................. cry2cri(3F)........................................................ 349
CRI2IBM(3F) ................................................................................................. cri2ibm(3F)........................................................ 343
cri2ibm(3F) ................................................................................................. cri2ibm(3F)........................................................ 343
CRI2IEG(3F) ................................................................................................. cri2ieg(3F)........................................................ 346
cri2ieg(3F) ................................................................................................. cri2ieg(3F)........................................................ 346
CRI2IEG_77(3F) .......................................................................................... ieg2cri_77(3F) ................................................ 366
cri2ieg_77(3F) .......................................................................................... ieg2cri_77(3F) ................................................ 366
CRY2CRI(3F) ................................................................................................. cry2cri(3F)........................................................ 349
cry2cri(3F) ................................................................................................. cry2cri(3F)........................................................ 349
CRY2MIPS(3F) ............................................................................................... cry2mips(3F) ..................................................... 352
cry2mips(3F) ............................................................................................... cry2mips(3F) ..................................................... 352
Current level of calling sequence ................................................................... trbklvl(3F)........................................................ 521
Current operating system ................................................................................ uname(3F) ............................................................ 442
Current working directory ............................................................................... getcwd(3F) .......................................................... 424
Data compression ............................................................................................ pack(3F)............................................................... 494
Data conversion (ASCII to EBCDIC) ............................................................ uscctc(3F) .......................................................... 381
Data conversion (IBM to Cray) ...................................................................... ibm2cray(3F) ..................................................... 360
Data conversion (IEEE to Cray) ..................................................................... cri2cray(3F) ..................................................... 340
Data conversion (IEEE to Cray) ..................................................................... ieg2cray(3F) ..................................................... 363
Data conversion (IEEE to Cray) ..................................................................... ieg2cri_77(3F) ................................................ 366

Index-6 004– 2165– 002

Data conversion (IEEE to Cray) ..................................................................... ieu2cray(3F) ..................................................... 372
Data unpacking ............................................................................................... unpack(3F) .......................................................... 531
Date conversion ............................................................................................... dtts(3F)............................................................... 480
Deallocate heap ............................................................................................... hpdeallc(3F) ..................................................... 453
debug(3F) ...................................................................................................... symdebug(3F) ..................................................... 508
Debugging ....................................................................................................... reprieve(3F) ..................................................... 498
DEBUG-like snapshot dump ........................................................................... symdump(3F)........................................................ 511
Decrease heap block ....................................................................................... hpnewlen(3F) ..................................................... 455
Delays the calling PE until the eureka event is posted .................................. wait_event(3C) ................................................ 545
Describes error handling under the UNICOS and UNICOS/mk operating
system .............................................................................................................. reprieve(3F) ..................................................... 498
Determines if bidirectional memory transfer is enabled or disabled .............. sensebt(3F)........................................................ 441
Directory of process ........................................................................................ getcwd(3F) .......................................................... 424
Disable bidirectional memory ......................................................................... clearbt(3F)........................................................ 420
disablfi(3F) ............................................................................................... clearfi(3F)........................................................ 421
Distribution counting sort ............................................................................... isortd(3F) .......................................................... 566
DSASC(3F) ...................................................................................................... dsasc(3F) ............................................................ 355
dsasc(3F) ...................................................................................................... dsasc(3F) ............................................................ 355
DTTS(3F) ........................................................................................................ dtts(3F)............................................................... 480
dtts(3F) ........................................................................................................ dtts(3F)............................................................... 480
Dump arrays of memory ................................................................................. craydump(3F) ..................................................... 449
Dump heap size and address ........................................................................... hpdump(3F) .......................................................... 454
Dump of running program .............................................................................. symdump(3F)........................................................ 511
Dump routines ................................................................................................. intro_progaids(3F) ....................................... 469
dump(3F) ........................................................................................................ symdump(3F)........................................................ 511
Dumps the address and size of each heap block ............................................ hpdump(3F) .......................................................... 454
EBCDIC to ASCII conversion ........................................................................ uscctc(3F) .......................................................... 381
Enable bidirectional memory transfers ........................................................... clearbt(3F)........................................................ 420
enablfi(3F) ................................................................................................. clearfi(3F)........................................................ 421
End Fortran program ....................................................................................... exit(3F)............................................................... 423
End job ............................................................................................................ abort(3F) ............................................................ 419
Enters a formatted message in the stderr file ............................................ remarkf(3F)........................................................ 438
Enters a message in the stderr file ............................................................. remark(3F) .......................................................... 437
Environment variables ..................................................................................... reprieve(3F) ..................................................... 498
ERREXIT(3F) ................................................................................................. errexit(3F)........................................................ 422
errexit(3F) ................................................................................................. errexit(3F)........................................................ 422
Error handling description .............................................................................. reprieve(3F) ..................................................... 498
ETA2CRAY(3F) ............................................................................................... eta2cray(3F) ..................................................... 356
eta2cray(3F) ............................................................................................... eta2cray(3F) ..................................................... 356
ETA/Cyber 205 to Cray conversion ............................................................... eta2cray(3F) ..................................................... 356
Event post ....................................................................................................... set_event(3C) .................................................. 540
Event routines (UNICOS/mk) ......................................................................... intro_sync(3F) ................................................ 535
Event test ......................................................................................................... test_event(3C) ................................................ 543
Events (clear multitasking) ............................................................................. clear_event(3C) .............................................. 536
Events (post multitasking) .............................................................................. set_event(3C) .................................................. 540
Exchange package listing ................................................................................ xpfmt(3F) ............................................................ 532
Exchange package processing routines ........................................................... intro_progaids(3F) ....................................... 469
Executes a UNICOS shell command .............................................................. ishell(3F) .......................................................... 431
Execution time (elapsed) in CPU ................................................................... second(3F) .......................................................... 500
Execution time for calling task (elapsed) in CPU .......................................... tsecnd(3F) .......................................................... 526

004– 2165– 002 Index-7

Exit job (error exit) ......................................................................................... errexit(3F)........................................................ 422
EXIT(3F) ........................................................................................................ exit(3F)............................................................... 423
exit(3F) ........................................................................................................ exit(3F)............................................................... 423
Exits from a Fortran program ......................................................................... exit(3F)............................................................... 423
Expands stored data ........................................................................................ unpack(3F) .......................................................... 531
Extend block ................................................................................................... hpclmove(3F) ..................................................... 452
Extends a block or copies the contents of the block into a larger block ....... hpclmove(3F) ..................................................... 452
Field finder ...................................................................................................... tmmsc(3F) ............................................................ 463
Files with same inode numbers ...................................................................... samefile(3F) ..................................................... 440
Find field ......................................................................................................... tmmsc(3F) ............................................................ 463
Find table field ................................................................................................ tmsrc(3F) ............................................................ 467
Fixed length record sort .................................................................................. orders(3F) .......................................................... 581
Floating point conversion ................................................................................ usdcti(3F) .......................................................... 384
Floating point to 32-bit single-precision ......................................................... usscti(3F) .......................................................... 391
Floating point to double-precision conversion ................................................ vxdcti(3F) .......................................................... 400
Floating-point conversion (IBM 32-bit) .......................................................... ussctc(3F) .......................................................... 390
Floating-point interrupt status ......................................................................... clearfi(3F)........................................................ 421
Floating-point to double-precision .................................................................. usdcti(3F) .......................................................... 384
Floating-point to single-precision conversion ................................................. usdctc(3F) .......................................................... 383
Floating-point to VAX F format single precision .......................................... vxscti(3F) .......................................................... 411
Floating-point to VAX G format single precision .......................................... vxgcti(3F) .......................................................... 403
Foreign data conversion routines .................................................................... intro_conversion(3F) .................................. 327
Fortran exit ...................................................................................................... exit(3F)............................................................... 423
Fortran floating-point interrupt status ............................................................. clearfi(3F)........................................................ 421
Fortran snapshot dump .................................................................................... symdump(3F)........................................................ 511
Fortran/C interface .......................................................................................... cinter(3F) .......................................................... 615
FP6064(3F) .................................................................................................... fp6064(3F) .......................................................... 359
fp6064(3F) .................................................................................................... fp6064(3F) .......................................................... 359
FP6460(3F) .................................................................................................... fp6064(3F) .......................................................... 359
fp6460(3F) .................................................................................................... fp6064(3F) .......................................................... 359
Free block links for heap ................................................................................ hpdump(3F) .......................................................... 454
FSIGCTL(3F) ................................................................................................. fsigctl(3F)........................................................ 481
fsigctl(3F) ................................................................................................. fsigctl(3F)........................................................ 481
Generates a bit mask corresponding to integer or real arrays according to
a specified condition ....................................................................................... bitvec(3F) .......................................................... 474
Generates a bit mask corresponding to masked integer arrays according
to a specified condition ................................................................................... bitvecm(3F)........................................................ 477
GETARG(3F) .................................................................................................... iargc(3F) ............................................................ 430
getarg(3F) .................................................................................................... iargc(3F) ............................................................ 430
GETCALLERINFO(3F) ................................................................................... getcallerinfo(3F) ......................................... 483
getcallerinfo(3F) ................................................................................... getcallerinfo(3F) ......................................... 483
GETCWD(3F) .................................................................................................... getcwd(3F) .......................................................... 424
getcwd(3F) .................................................................................................... getcwd(3F) .......................................................... 424
GETHMC(3F) .................................................................................................... getpmc(3F) .......................................................... 485
gethmc(3F) .................................................................................................... getpmc(3F) .......................................................... 485
GETHOST(3F) ................................................................................................. gethost(3F)........................................................ 425
gethost(3F) ................................................................................................. gethost(3F)........................................................ 425
GETOARG(3F) ................................................................................................. getoarg(3F)........................................................ 426
getoarg(3F) ................................................................................................. getoarg(3F)........................................................ 426
GETOARGC(3F) ............................................................................................... getoargc(3F) ..................................................... 427

Index-8 004– 2165– 002

getoargc(3F) ............................................................................................... getoargc(3F) ..................................................... 427
GETPMC(3F) .................................................................................................... getpmc(3F) .......................................................... 485
getpmc(3F) .................................................................................................... getpmc(3F) .......................................................... 485
Gets command-line arguments ........................................................................ getoarg(3F)........................................................ 426
Gets command-line arguments ........................................................................ getoargc(3F) ..................................................... 427
Gets command-line arguments, allowing blanks or commas as delimiters .... getvarg(3F)........................................................ 428
Gets command-line arguments, allowing blanks or commas as delimiters .... getvargc(3F) ..................................................... 429
Gets task CPU time in real-time clock (RTC) ticks ....................................... icpused(3F)........................................................ 488
GETTMC(3F) .................................................................................................... getpmc(3F) .......................................................... 485
gettmc(3F) .................................................................................................... getpmc(3F) .......................................................... 485
GETVARG(3F) ................................................................................................. getvarg(3F)........................................................ 428
getvarg(3F) ................................................................................................. getvarg(3F)........................................................ 428
GETVARGC(3F) ............................................................................................... getvargc(3F) ..................................................... 429
getvargc(3F) ............................................................................................... getvargc(3F) ..................................................... 429
Gives the number of reads and writes to SDS that have occurred while
accessing auxiliary array variables ................................................................. auxstat(3F)........................................................ 473
Halting all processing elements ...................................................................... stop_all(3F) ..................................................... 507
Hardware standard name ................................................................................. uname(3F) ............................................................ 442
Heap address ................................................................................................... hpdump(3F) .......................................................... 454
Heap allocation ............................................................................................... hpalloc(3F)........................................................ 450
Heap block (adjustment) ................................................................................. hpnewlen(3F) ..................................................... 455
Heap block length ........................................................................................... ihplen(3F) .......................................................... 457
Heap blocks dump .......................................................................................... hpdump(3F) .......................................................... 454
Heap deallocation ............................................................................................ hpdeallc(3F) ..................................................... 453
Heap information ............................................................................................ hpdump(3F) .......................................................... 454
Heap integrity check ....................................................................................... hpcheck(3F)........................................................ 451
Heap management ........................................................................................... intro_heap(3F) ................................................ 445
Heap size ......................................................................................................... hpdump(3F) .......................................................... 454
History trace buffer routines ........................................................................... intro_sync(3F) ................................................ 535
Host mainframe ............................................................................................... gethost(3F)........................................................ 425
HPALLOC(3F) ................................................................................................. hpalloc(3F)........................................................ 450
hpalloc(3F) ................................................................................................. hpalloc(3F)........................................................ 450
HPCHECK(3F) ................................................................................................. hpcheck(3F)........................................................ 451
hpcheck(3F) ................................................................................................. hpcheck(3F)........................................................ 451
HPCLMOVE(3F) ............................................................................................... hpclmove(3F) ..................................................... 452
hpclmove(3F) ............................................................................................... hpclmove(3F) ..................................................... 452
HPDEALLC(3F) ............................................................................................... hpdeallc(3F) ..................................................... 453
hpdeallc(3F) ............................................................................................... hpdeallc(3F) ..................................................... 453
HPDUMP(3F) .................................................................................................... hpdump(3F) .......................................................... 454
hpdump(3F) .................................................................................................... hpdump(3F) .......................................................... 454
HPNEWLEN(3F) ............................................................................................... hpnewlen(3F) ..................................................... 455
hpnewlen(3F) ............................................................................................... hpnewlen(3F) ..................................................... 455
HPSHRINK(3F) ............................................................................................... hpshrink(3F) ..................................................... 456
hpshrink(3F) ............................................................................................... hpshrink(3F) ..................................................... 456
IARGC(3F) ...................................................................................................... iargc(3F) ............................................................ 430
iargc(3F) ...................................................................................................... iargc(3F) ............................................................ 430
IBM 32-bit floating-point conversion ............................................................. ussctc(3F) .......................................................... 390
IBM 64-bit floating-point conversion ............................................................. usdctc(3F) .......................................................... 383
IBM packed-decimal conversion .................................................................... uspctc(3F) .......................................................... 389
IBM to Cray conversion ................................................................................. ibm2cray(3F) ..................................................... 360

004– 2165– 002 Index-9

IBM2CRAY(3F) ............................................................................................... ibm2cray(3F) ..................................................... 360
ibm2cray(3F) ............................................................................................... ibm2cray(3F) ..................................................... 360
IBM2CRI(3F) ................................................................................................. cri2ibm(3F)........................................................ 343
ibm2cri(3F) ................................................................................................. cri2ibm(3F)........................................................ 343
ICAMAX(3F) .................................................................................................... isamax(3F) .......................................................... 562
icamax(3F) .................................................................................................... isamax(3F) .......................................................... 562
ICEIL(3F) ...................................................................................................... iceil(3F) ............................................................ 487
iceil(3F) ...................................................................................................... iceil(3F) ............................................................ 487
ICPUSED(3F) ................................................................................................. icpused(3F)........................................................ 488
icpused(3F) ................................................................................................. icpused(3F)........................................................ 488
IEC2CRAY(3F) ............................................................................................... cry2cri(3F)........................................................ 349
iec2cray(3F) ............................................................................................... cry2cri(3F)........................................................ 349
IEEE conversion routines ................................................................................ intro_conversion(3F) .................................. 327
IEEE floating-point to Cray conversion .......................................................... cry2cri(3F)........................................................ 349
IEEE floating-point to Cray conversion .......................................................... cry2mips(3F) ..................................................... 352
IEEE to Cray conversion ................................................................................ cri2cray(3F) ..................................................... 340
IEEE to Cray conversion ................................................................................ ieg2cray(3F) ..................................................... 363
IEEE to Cray conversion ................................................................................ ieg2cri_77(3F) ................................................ 366
IEEE to Cray conversion ................................................................................ ieu2cray(3F) ..................................................... 372
IEG2CRAY(3F) ............................................................................................... ieg2cray(3F) ..................................................... 363
ieg2cray(3F) ............................................................................................... ieg2cray(3F) ..................................................... 363
IEG2CRI(3F) ................................................................................................. cri2ieg(3F)........................................................ 346
ieg2cri(3F) ................................................................................................. cri2ieg(3F)........................................................ 346
IEG2CRI_77(3F) .......................................................................................... ieg2cri_77(3F) ................................................ 366
ieg2cri_77(3F) .......................................................................................... ieg2cri_77(3F) ................................................ 366
IEG2MIPS(3F) ............................................................................................... ieg2mips(3F) ..................................................... 369
ieg2mips(3F) ............................................................................................... ieg2mips(3F) ..................................................... 369
IEU2CRAY(3F) ............................................................................................... ieu2cray(3F) ..................................................... 372
ieu2cray(3F) ............................................................................................... ieu2cray(3F) ..................................................... 372
IGTBYT(3F) .................................................................................................... byt(3F) ................................................................. 479
igtbyt(3F) .................................................................................................... byt(3F) ................................................................. 479
IHPLEN(3F) .................................................................................................... ihplen(3F) .......................................................... 457
ihplen(3F) .................................................................................................... ihplen(3F) .......................................................... 457
IHPVALID(3F) ............................................................................................... ihpvalid(3F) ..................................................... 458
ihpvalid(3F) ............................................................................................... ihpvalid(3F) ..................................................... 458
IILZ(3F) ........................................................................................................ iilz(3F)............................................................... 557
iilz(3F) ........................................................................................................ iilz(3F)............................................................... 557
ILLZ(3F) ........................................................................................................ iilz(3F)............................................................... 557
illz(3F) ........................................................................................................ iilz(3F)............................................................... 557
ILSUM(3F) ...................................................................................................... iilz(3F)............................................................... 557
ilsum(3F) ...................................................................................................... iilz(3F)............................................................... 557
Increase heap block ......................................................................................... hpnewlen(3F) ..................................................... 455
INFLMAX(3F) ................................................................................................. inflmax(3F)........................................................ 559
inflmax(3F) ................................................................................................. inflmax(3F)........................................................ 559
INFLMIN(3F) ................................................................................................. inflmax(3F)........................................................ 559
inflmin(3F) ................................................................................................. inflmax(3F)........................................................ 559
Initialize table .................................................................................................. tminit(3F) .......................................................... 462
Initializes table descriptor vector and zeroes table length vector ................... tminit(3F) .......................................................... 462
Initiates a detailed tracing of each call and return ......................................... setplimq(3F) ..................................................... 503
Inode numbers ................................................................................................. samefile(3F) ..................................................... 440

Index-10 004– 2165– 002

INT6064(3F) ................................................................................................. int6064(3F)........................................................ 375
int6064(3F) ................................................................................................. int6064(3F)........................................................ 375
INT6460(3F) ................................................................................................. int6460(3F)........................................................ 376
int6460(3F) ................................................................................................. int6460(3F)........................................................ 376
Integer ceiling value ........................................................................................ iceil(3F) ............................................................ 487
Integer conversion (IEEE floating-point to Cray) ........................................... cry2cri(3F)........................................................ 349
Integer conversion (IEEE floating-point to Cray) ........................................... cry2mips(3F) ..................................................... 352
Integer conversion (IEEE floating-point to MIPS) ......................................... ieg2mips(3F) ..................................................... 369
Integer conversion (IEEE floating-point to MIPS) ......................................... vax2mips(3F) ..................................................... 396
Integer conversion (IEEE to Cray) ................................................................. cri2cray(3F) ..................................................... 340
Integer conversion (IEEE to Cray) ................................................................. ieg2cray(3F) ..................................................... 363
Integer conversion (IEEE to Cray) ................................................................. ieg2cri_77(3F) ................................................ 366
Integer conversion (IEEE to Cray) ................................................................. ieu2cray(3F) ..................................................... 372
Integer from ASCII conversion ...................................................................... chconv(3F) .......................................................... 338
Integer to packed-decimal conversion ............................................................ usictp(3F) .......................................................... 387
INTEGER*2 to integer conversion ................................................................. usictc(3F) .......................................................... 385
INTEGER*4 to integer conversion ................................................................. usictc(3F) .......................................................... 385
Integrity of heap check ................................................................................... hpcheck(3F)........................................................ 451
Interface ........................................................................................................... cinter(3F) .......................................................... 615
Internal, fixed-length record-sorting routine optimized for Cray Research
systems ............................................................................................................ orders(3F) .......................................................... 581
Interrupt status for floating-point errors .......................................................... clearfi(3F)........................................................ 421
INTMAX(3F) .................................................................................................... intmax(3F) .......................................................... 561
intmax(3F) .................................................................................................... intmax(3F) .......................................................... 561
INTMIN(3F) .................................................................................................... intmax(3F) .......................................................... 561
intmin(3F) .................................................................................................... intmax(3F) .......................................................... 561
Intro ................................................................................................................. intro_interface(3F) ..................................... 417
intro3(3F) .................................................................................................... intro_conversion(3F) .................................. 327
intro4(3F) .................................................................................................... intro_heap(3F) ................................................ 445
intro7(3F) .................................................................................................... intro_progaids(3F) ....................................... 469
intro8(3F) .................................................................................................... intro_interface(3F) ..................................... 417
INTRO_CONVERSION(3F) ............................................................................ intro_conversion(3F) .................................. 327
intro_conversion(3F) ............................................................................ intro_conversion(3F) .................................. 327
Introduction to conversion routines ................................................................ intro_conversion(3F) .................................. 327
Introduction to heap, table, and data segment management ........................... intro_heap(3F) ................................................ 445
Introduction to interfaces to C library routines .............................................. cinter(3F) .......................................................... 615
Introduction to programming aids ................................................................... intro_progaids(3F) ....................................... 469
Introduction to sorting and searching routines ............................................... intro_sortsearch(3F) .................................. 547
Introduction to synchronization routines ......................................................... intro_sync(3F) ................................................ 535
Introduction to system interface routines ........................................................ intro_interface(3F) ..................................... 417
INTRO_HEAP(3F) .......................................................................................... intro_heap(3F) ................................................ 445
intro_heap(3F) .......................................................................................... intro_heap(3F) ................................................ 445
INTRO_INTERFACE(3F) .............................................................................. intro_interface(3F) ..................................... 417
intro_interface(3F) .............................................................................. intro_interface(3F) ..................................... 417
INTRO_PROGAIDS(3F) ................................................................................. intro_progaids(3F) ....................................... 469
intro_progaids(3F) ................................................................................. intro_progaids(3F) ....................................... 469
INTRO_SORTSEARCH(3F) ............................................................................ intro_sortsearch(3F) .................................. 547
intro_sortsearch(3F) ............................................................................ intro_sortsearch(3F) .................................. 547
INTRO_SYNC(3F) .......................................................................................... intro_sync(3F) ................................................ 535
intro_sync(3F) .......................................................................................... intro_sync(3F) ................................................ 535

004– 2165– 002 Index-11

ISAMAX(3F) .................................................................................................... isamax(3F) .......................................................... 562
isamax(3F) .................................................................................................... isamax(3F) .......................................................... 562
ISAMIN(3F) .................................................................................................... isamax(3F) .......................................................... 562
isamin(3F) .................................................................................................... isamax(3F) .......................................................... 562
ISHELL(3F) .................................................................................................... ishell(3F) .......................................................... 431
ishell(3F) .................................................................................................... ishell(3F) .......................................................... 431
ISMAX(3F) ...................................................................................................... ismax(3F) ............................................................ 564
ismax(3F) ...................................................................................................... ismax(3F) ............................................................ 564
ISMIN(3F) ...................................................................................................... ismax(3F) ............................................................ 564
ismin(3F) ...................................................................................................... ismax(3F) ............................................................ 564
ISORTB(3F) .................................................................................................... ssortb(3F) .......................................................... 598
isortb(3F) .................................................................................................... ssortb(3F) .......................................................... 598
ISORTD(3F) .................................................................................................... isortd(3F) .......................................................... 566
isortd(3F) .................................................................................................... isortd(3F) .......................................................... 566
ISRCHEQ(3F) ................................................................................................. isrcheq(3F)........................................................ 571
isrcheq(3F) ................................................................................................. isrcheq(3F)........................................................ 571
ISRCHFGE(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
isrchfge(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
ISRCHFGT(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
isrchfgt(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
ISRCHFLE(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
isrchfle(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
ISRCHFLT(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
isrchflt(3F) ............................................................................................... isrchflt(3F) ..................................................... 573
ISRCHIGE(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
isrchige(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
ISRCHIGT(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
isrchigt(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
ISRCHILE(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
isrchile(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
ISRCHILT(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
isrchilt(3F) ............................................................................................... isrchilt(3F) ..................................................... 575
ISRCHMEQ(3F) ............................................................................................... isrchmeq(3F) ..................................................... 577
isrchmeq(3F) ............................................................................................... isrchmeq(3F) ..................................................... 577
ISRCHMGE(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
isrchmge(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
ISRCHMGT(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
isrchmgt(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
ISRCHMLE(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
isrchmle(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
ISRCHMLT(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
isrchmlt(3F) ............................................................................................... isrchmlt(3F) ..................................................... 579
ISRCHMNE(3F) ............................................................................................... isrchmeq(3F) ..................................................... 577
isrchmne(3F) ............................................................................................... isrchmeq(3F) ..................................................... 577
ISRCHNE(3F) ................................................................................................. isrcheq(3F)........................................................ 571
isrchne(3F) ................................................................................................. isrcheq(3F)........................................................ 571
Large radix sorting .......................................................................................... orders(3F) .......................................................... 581
Leading elements in a vector .......................................................................... iilz(3F)............................................................... 557
Length of block change .................................................................................. hpclmove(3F) ..................................................... 452
Length of character argument ......................................................................... trimlen(3F)........................................................ 524

Index-12 004– 2165– 002

Length of heap block ...................................................................................... ihplen(3F) .......................................................... 457
List calling sequence ....................................................................................... trbk(3F)............................................................... 520
List exchange package .................................................................................... xpfmt(3F) ............................................................ 532
List subroutines ............................................................................................... trbk(3F)............................................................... 520
Lists all subroutines active in the current calling sequence ........................... trbk(3F)............................................................... 520
Locate table field ............................................................................................. tmsrc(3F) ............................................................ 467
Lock routines (UNICOS/mk) .......................................................................... intro_sync(3F) ................................................ 535
Logical conversion .......................................................................................... cri2cray(3F) ..................................................... 340
Logical conversion .......................................................................................... ieg2cray(3F) ..................................................... 363
Logical conversion .......................................................................................... ieg2cri_77(3F) ................................................ 366
Logical conversion .......................................................................................... ieu2cray(3F) ..................................................... 372
LOGICAL*1 to Cray logical conversion ........................................................ uslctc(3F) .......................................................... 388
LOGICAL*4 to Cray logical conversion ........................................................ uslctc(3F) .......................................................... 388
machine types .................................................................................................. getpmc(3F) .......................................................... 485
Management routines ...................................................................................... intro_heap(3F) ................................................ 445
Maximum ........................................................................................................ intro_sortsearch(3F) .................................. 547
Maximum absolute value in a vector .............................................................. isamax(3F) .......................................................... 562
Maximum value in a vector ............................................................................ inflmax(3F)........................................................ 559
Maximum value in a vector ............................................................................ intmax(3F) .......................................................... 561
Maximum value in a vector ............................................................................ ismax(3F) ............................................................ 564
Memory allocation (heap) ............................................................................... hpalloc(3F)........................................................ 450
Memory dump ................................................................................................. craydump(3F) ..................................................... 449
Memory interface ............................................................................................ hpshrink(3F) ..................................................... 456
Memory move ................................................................................................. tmmve(3F) ............................................................ 464
Memory table allocation ................................................................................. tmats(3F) ............................................................ 461
Memory to heap return ................................................................................... hpdeallc(3F) ..................................................... 453
Memory to operating system .......................................................................... hpshrink(3F) ..................................................... 456
Merge exchange sort ....................................................................................... ssortb(3F) .......................................................... 598
Merge sort ....................................................................................................... ssortb(3F) .......................................................... 598
Minimum ......................................................................................................... intro_sortsearch(3F) .................................. 547
Minimum absolute value in a vector .............................................................. isamax(3F) .......................................................... 562
Minimum value in a vector ............................................................................. inflmax(3F)........................................................ 559
Minimum value in a vector ............................................................................. intmax(3F) .......................................................... 561
Minimum value in a vector ............................................................................. ismax(3F) ............................................................ 564
MIPS2CRY(3F) ............................................................................................... cry2mips(3F) ..................................................... 352
mips2cry(3F) ............................................................................................... cry2mips(3F) ..................................................... 352
MIPS2IEG(3F) ............................................................................................... ieg2mips(3F) ..................................................... 369
MIPS2VAX(3F) ............................................................................................... vax2mips(3F) ..................................................... 396
Modifies floating-point interrupt status ........................................................... clearfi(3F)........................................................ 421
Modify heap block .......................................................................................... hpnewlen(3F) ..................................................... 455
mov(3F) ........................................................................................................... mov(3F) ................................................................. 489
MOVBIT(3F) .................................................................................................... mov(3F) ................................................................. 489
movbit(3F) .................................................................................................... mov(3F) ................................................................. 489
MOVBITZ(3F) ................................................................................................. mov(3F) ................................................................. 489
movbitz(3F) ................................................................................................. mov(3F) ................................................................. 489
Move block ..................................................................................................... hpclmove(3F) ..................................................... 452
Move bytes or bits .......................................................................................... mov(3F) ................................................................. 489
Move characters .............................................................................................. mvc(3F) ................................................................. 493
Move memory words ...................................................................................... tmmve(3F) ............................................................ 464
Moves bytes or bits from one variable or array to another ............................ mov(3F) ................................................................. 489

004– 2165– 002 Index-13

Moves characters from one memory area to another ..................................... mvc(3F) ................................................................. 493
Moves memory (words) .................................................................................. tmmve(3F) ............................................................ 464
MTTS(3F) ........................................................................................................ mtts(3F)............................................................... 492
mtts(3F) ........................................................................................................ mtts(3F)............................................................... 492
Multipass sorting ............................................................................................. orders(3F) .......................................................... 581
Multitasking (delay of calling task) ................................................................ wait_event(3C) ................................................ 545
Multitasking (event clear) ............................................................................... clear_event(3C) .............................................. 536
Multitasking event test .................................................................................... test_event(3C) ................................................ 543
Multitasking (posting events) .......................................................................... set_event(3C) .................................................. 540
Multitasking synchronizes task at barrier ....................................................... wait_barrier(3C) ........................................... 544
Multitasking test barrier .................................................................................. test_barrier(3C) ........................................... 542
MVC(3F) ........................................................................................................... mvc(3F) ................................................................. 493
mvc(3F) ........................................................................................................... mvc(3F) ................................................................. 493
Name ............................................................................................................... uname(3F) ............................................................ 442
NLIMIT(3F) .................................................................................................... nlimit(3F) .......................................................... 432
nlimit(3F) .................................................................................................... nlimit(3F) .......................................................... 432
NOS/VE to Cray conversion ........................................................................... nve2cray(3F) ..................................................... 377
Null to trailing blank conversion .................................................................... rbn(3F) ................................................................. 380
Number of arguments ..................................................................................... iargc(3F) ............................................................ 430
Numerals to integer conversion ...................................................................... chconv(3F) .......................................................... 338
Numeric conversion routines .......................................................................... intro_conversion(3F) .................................. 327
NVE2CRAY(3F) ............................................................................................... nve2cray(3F) ..................................................... 377
nve2cray(3F) ............................................................................................... nve2cray(3F) ..................................................... 377
Octal from binary conversion ......................................................................... b2oct(3F) ............................................................ 333
Operating system name ................................................................................... uname(3F) ............................................................ 442
Ordered vector search ..................................................................................... osrchi(3F) .......................................................... 592
Ordered vector search ..................................................................................... osrchm(3F) .......................................................... 594
ORDERS(3F) .................................................................................................... orders(3F) .......................................................... 581
orders(3F) .................................................................................................... orders(3F) .......................................................... 581
OSRCHF(3F) .................................................................................................... osrchi(3F) .......................................................... 592
osrchf(3F) .................................................................................................... osrchi(3F) .......................................................... 592
OSRCHI(3F) .................................................................................................... osrchi(3F) .......................................................... 592
osrchi(3F) .................................................................................................... osrchi(3F) .......................................................... 592
OSRCHM(3F) .................................................................................................... osrchm(3F) .......................................................... 594
osrchm(3F) .................................................................................................... osrchm(3F) .......................................................... 594
P32(3F) ........................................................................................................... p32(3F) ................................................................. 496
p32(3F) ........................................................................................................... p32(3F) ................................................................. 496
P6460(3F) ...................................................................................................... p6460(3F) ............................................................ 497
p6460(3F) ...................................................................................................... p6460(3F) ............................................................ 497
Pack 64 into 60 bits ........................................................................................ p6460(3F) ............................................................ 497
Pack data ......................................................................................................... pack(3F)............................................................... 494
Pack from 64 to 32 bits .................................................................................. p32(3F) ................................................................. 496
PACK(3F) ........................................................................................................ pack(3F)............................................................... 494
pack(3F) ........................................................................................................ pack(3F)............................................................... 494
Packed decimal conversion ............................................................................. uspctc(3F) .......................................................... 389
Packed decimal to integer conversion ............................................................ uspctc(3F) .......................................................... 389
Packs or unpacks 32-bit words into or from Cray 64-bit words .................... p32(3F) ................................................................. 496
Packs or unpacks 60-bit words into or from Cray 64-bit words .................... p6460(3F) ............................................................ 497
Pascal snapshot dump ..................................................................................... symdump(3F)........................................................ 511
Performs a distribution counting sort on the elements of an integer vector .. isortd(3F) .......................................................... 566

Index-14 004– 2165– 002

Performs Batcher’s Odd-Even Merge sort on the elements of a real or
integer general vector ...................................................................................... ssortb(3F) .......................................................... 598
Places an octal Hollerith representation of a Cray Research numeric value
into a specified part of an integer array .......................................................... b2oct(3F) ............................................................ 333
Posts an event and returns control to the calling PE ...................................... set_event(3C) .................................................. 540
Presets table space .......................................................................................... tmpts(3F) ............................................................ 466
primary machine types .................................................................................... getpmc(3F) .......................................................... 485
Print exchange package ................................................................................... xpfmt(3F) ............................................................ 532
Prints a traceback ............................................................................................ tracebk(3F)........................................................ 518
Processes table collisions ................................................................................ tmptc(3F) ............................................................ 465
Processing elements stop all ........................................................................... stop_all(3F) ..................................................... 507
Produce symbolic dump .................................................................................. symdebug(3F) ..................................................... 508
Produces a printable image of an exchange package ..................................... xpfmt(3F) ............................................................ 532
Produces a symbolic snapshot dump of a running program ........................... symdump(3F)........................................................ 511
Produces a symbolic snapshot of a running process ...................................... symdebug(3F) ..................................................... 508
Program exit .................................................................................................... exit(3F)............................................................... 423
Program recovery ............................................................................................ shutdsav(3F) ..................................................... 504
Program time in CPU ..................................................................................... tsecnd(3F) .......................................................... 526
Provides an interface to setting or obtaining resource limit values ............... nlimit(3F) .......................................................... 432
PUTBYT(3F) .................................................................................................... byt(3F) ................................................................. 479
putbyt(3F) .................................................................................................... byt(3F) ................................................................. 479
Quit program ................................................................................................... exit(3F)............................................................... 423
RBN(3F) ........................................................................................................... rbn(3F) ................................................................. 380
rbn(3F) ........................................................................................................... rbn(3F) ................................................................. 380
Read SDS count .............................................................................................. auxstat(3F)........................................................ 473
Real conversion from VAX 32-bit ................................................................. vxsctc(3F) .......................................................... 410
Real conversion VAX G to Cray .................................................................... vxgctc(3F) .......................................................... 402
Real-time clock ............................................................................................... secondr(3F)........................................................ 502
Real-time clock routine (Fortran) ................................................................... icpused(3F)........................................................ 488
Real-time clock value ..................................................................................... sysclock(3F) ..................................................... 516
Registers the arrival of a PE at a barrier ........................................................ set_barrier(3C) .............................................. 539
Release version ............................................................................................... uname(3F) ............................................................ 442
REMARK2(3F) ................................................................................................. remark(3F) .......................................................... 437
remark2(3F) ................................................................................................. remark(3F) .......................................................... 437
REMARK(3F) .................................................................................................... remark(3F) .......................................................... 437
remark(3F) .................................................................................................... remark(3F) .......................................................... 437
REMARKF(3F) ................................................................................................. remarkf(3F)........................................................ 438
remarkf(3F) ................................................................................................. remarkf(3F)........................................................ 438
Replace byte .................................................................................................... byt(3F) ................................................................. 479
Replaces a byte in a variable or an array ....................................................... byt(3F) ................................................................. 479
Report table statistics ...................................................................................... tmamu(3F) ............................................................ 460
Reports table management operation statistics ............................................... tmamu(3F) ............................................................ 460
REPRIEVE(3F) ............................................................................................... reprieve(3F) ..................................................... 498
reprieve(3F) ............................................................................................... reprieve(3F) ..................................................... 498
Requests abort ................................................................................................. errexit(3F)........................................................ 422
Requests abort with traceback ........................................................................ abort(3F) ............................................................ 419
Resource limits ................................................................................................ nlimit(3F) .......................................................... 432
Restart program ............................................................................................... shutdsav(3F) ..................................................... 504
restorfi(3F) ............................................................................................... clearfi(3F)........................................................ 421
Return memory to heap .................................................................................. hpdeallc(3F) ..................................................... 453

004– 2165– 002 Index-15

Return message to user and system ................................................................ remarkf(3F)........................................................ 438
Returns 128-word output array describing machine characteristics ............... getpmc(3F) .......................................................... 485
Returns a block of memory to the list of available space (the heap) ............ hpdeallc(3F) ..................................................... 453
returns caller name .......................................................................................... getcallerinfo(3F) ......................................... 483
Returns elapsed CPU time .............................................................................. second(3F) .......................................................... 500
Returns elapsed CPU time for a calling task or process ................................ tsecnd(3F) .......................................................... 526
Returns elapsed wall-clock time in milliseconds since the previous call
to TIMEF ........................................................................................................ timef(3F) ............................................................ 517
Returns elapsed wall-clock time in seconds ................................................... secondr(3F)........................................................ 502
Returns information on current level of calling sequence .............................. trbklvl(3F)........................................................ 521
Returns integer ceiling of a rational number .................................................. iceil(3F) ............................................................ 487
Returns memory from the heap to the operating system ................................ hpshrink(3F) ..................................................... 456
Returns name of current operating system (Fortran interface to
uname(2)) ....................................................................................................... uname(3F) ............................................................ 442
Returns name of host mainframe .................................................................... gethost(3F)........................................................ 425
Returns number of command-line arguments or the argument itself ............. iargc(3F) ............................................................ 430
Returns number of leading occurrences of an object in a vector ................... iilz(3F)............................................................... 557
Returns real-time clock value and number of wraps ...................................... sysclock(3F) ..................................................... 516
Returns the CPU time (in seconds of type real) remaining for the
program ........................................................................................................... tremain(3F)........................................................ 523
Returns the current working directory ............................................................ getcwd(3F) .......................................................... 424
Returns the length of a character argument without counting trailing
blanks .............................................................................................................. trimlen(3F)........................................................ 524
Returns the length of a heap block ................................................................. ihplen(3F) .......................................................... 457
Returns the name and line number of the calling routine .............................. getcallerinfo(3F) ......................................... 483
Returns the state of an event, either posted or cleared .................................. test_event(3C) ................................................ 543
Returns time-stamp units in specified standard-time units ............................. unitts(3F) .......................................................... 530
Returns validity of block address ................................................................... ihpvalid(3F) ..................................................... 458
RNB(3F) ........................................................................................................... rbn(3F) ................................................................. 380
rnb(3F) ........................................................................................................... rbn(3F) ................................................................. 380
SAMEFILE(3F) ............................................................................................... samefile(3F) ..................................................... 440
samefile(3F) ............................................................................................... samefile(3F) ..................................................... 440
SDS read and write count ............................................................................... auxstat(3F)........................................................ 473
Search table ..................................................................................................... tmmsc(3F) ............................................................ 463
Search vector table .......................................................................................... tmvsc(3F) ............................................................ 468
search(3F) .................................................................................................... intro_sortsearch(3F) .................................. 547
Searches a real vector for all elements with a specified logical
relationship to a real target ............................................................................. whenflt(3F)........................................................ 607
Searches a real vector for clusters of values with a specified logical
relationship to a real target ............................................................................. clusflt(3F)........................................................ 553
Searches a real vector for the first element with a specified logical
relationship to a real target ............................................................................. isrchflt(3F) ..................................................... 573
Searches a real vector for the first occurrence of the maximum or
minimum value ............................................................................................... ismax(3F) ............................................................ 564
Searches a vector for all elements equal or not equal to a target .................. wheneq(3F) .......................................................... 605
Searches a vector for all elements whose subfields are equal or not equal
to a target ........................................................................................................ whenmeq(3F)........................................................ 611
Searches a vector for all elements whose subfields have a specified
logical relationship with a target .................................................................... whenmlt(3F)........................................................ 613
Searches a vector for clusters of values equal or not equal to a target ......... cluseq(3F) .......................................................... 551

Index-16 004– 2165– 002

Searches a vector for the first element equal or not equal to a target ........... isrcheq(3F)........................................................ 571
Searches a vector for the first element whose subfield has a specified
logical relationship with a target .................................................................... isrchmlt(3F) ..................................................... 579
Searches a vector for the first element whose subfield is equal or not
equal to a target .............................................................................................. isrchmeq(3F) ..................................................... 577
Searches a vector for the first occurrence of the maximum or minimum
absolute value .................................................................................................. isamax(3F) .......................................................... 562
Searches a vector table for the search argument ............................................ tmvsc(3F) ............................................................ 468
Searches an integer vector for all elements that have a specified
relationship to an integer target ...................................................................... whenilt(3F)........................................................ 609
Searches an integer vector for clusters of values with a specified logical
relationship to an integer target ...................................................................... clusilt(3F)........................................................ 555
Searches an integer vector for the first element with a specified logical
relationship to an integer target ...................................................................... isrchilt(3F) ..................................................... 575
Searches an integer vector for the maximum or minimum value .................. intmax(3F) .......................................................... 561
Searches an ordered integer vector for the first element whose subfield is
equal to an integer target ................................................................................ osrchm(3F) .......................................................... 594
Searches an ordered vector for the first location that contains a target ......... osrchi(3F) .......................................................... 592
Searches for the maximum or minimum value in subfields of a vector
element ............................................................................................................ inflmax(3F)........................................................ 559
Searches the table by using a mask to locate a specific field within an
entry using an optional offset ......................................................................... tmmsc(3F) ............................................................ 463
Searches the table by using optional mask to locate specific field within
entry and offset ............................................................................................... tmsrc(3F) ............................................................ 467
SECOND(3F) .................................................................................................... second(3F) .......................................................... 500
second(3F) .................................................................................................... second(3F) .......................................................... 500
SECONDR(3F) ................................................................................................. secondr(3F)........................................................ 502
secondr(3F) ................................................................................................. secondr(3F)........................................................ 502
SENSEBT(3F) ................................................................................................. sensebt(3F)........................................................ 441
sensebt(3F) ................................................................................................. sensebt(3F)........................................................ 441
SENSEFI(3F) ................................................................................................. clearfi(3F)........................................................ 421
sensefi(3F) ................................................................................................. clearfi(3F)........................................................ 421
SET_BARRIER(3C) ....................................................................................... set_barrier(3C) .............................................. 539
set_barrier(3C) ....................................................................................... set_barrier(3C) .............................................. 539
SETBT(3F) ...................................................................................................... clearbt(3F)........................................................ 420
setbt(3F) ...................................................................................................... clearbt(3F)........................................................ 420
set_event(3C) ............................................................................................ set_event(3C) .................................................. 540
SETFI(3F) ...................................................................................................... clearfi(3F)........................................................ 421
setfi(3F) ...................................................................................................... clearfi(3F)........................................................ 421
SETPLIMQ(3F) ............................................................................................... setplimq(3F) ..................................................... 503
setplimq(3F) ............................................................................................... setplimq(3F) ..................................................... 503
Sets up the calling program to be checkpointed on system shutdown ........... shutdsav(3F) ..................................................... 504
Shell command (execute) ................................................................................ ishell(3F) .......................................................... 431
Shutdown of program ..................................................................................... shutdsav(3F) ..................................................... 504
SHUTDSAV(3F) ............................................................................................... shutdsav(3F) ..................................................... 504
shutdsav(3F) ............................................................................................... shutdsav(3F) ..................................................... 504
SIG environment variables .............................................................................. reprieve(3F) ..................................................... 498
Signal action (Fortran) .................................................................................... fsigctl(3F)........................................................ 481
Signal control (Fortran) ................................................................................... sigoff(3F) .......................................................... 506
Signal routines ................................................................................................. intro_progaids(3F) ....................................... 469

004– 2165– 002 Index-17

SIGOFF(3F) .................................................................................................... sigoff(3F) .......................................................... 506
sigoff(3F) .................................................................................................... sigoff(3F) .......................................................... 506
SIGON(3F) ...................................................................................................... sigoff(3F) .......................................................... 506
sigon(3F) ...................................................................................................... sigoff(3F) .......................................................... 506
Single-precision ............................................................................................... usdcti(3F) .......................................................... 384
Snapshot dump ................................................................................................ symdump(3F)........................................................ 511
Sort .................................................................................................................. intro_sortsearch(3F) .................................. 547
Sort .................................................................................................................. isortd(3F) .......................................................... 566
Sort .................................................................................................................. orders(3F) .......................................................... 581
Sort .................................................................................................................. ssortb(3F) .......................................................... 598
Space for table ................................................................................................ tmpts(3F) ............................................................ 466
Specifies action on receipt of signal ............................................................... fsigctl(3F)........................................................ 481
SSORTB(3F) .................................................................................................... ssortb(3F) .......................................................... 598
ssortb(3F) .................................................................................................... ssortb(3F) .......................................................... 598
Stamp time to ASCII ...................................................................................... tsdt(3F)............................................................... 528
Standard time .................................................................................................. unitts(3F) .......................................................... 530
Statistics table management ............................................................................ tmamu(3F) ............................................................ 460
Status of floating-point interrupts ................................................................... clearfi(3F)........................................................ 421
Stderr message from user ................................................................................ remarkf(3F)........................................................ 438
Stderr message (from user) ............................................................................. remark(3F) .......................................................... 437
Stop Fortran program ...................................................................................... exit(3F)............................................................... 423
STOP_ALL(3F) ............................................................................................... stop_all(3F) ..................................................... 507
stop_all(3F) ............................................................................................... stop_all(3F) ..................................................... 507
Stops all PEs in an application ....................................................................... stop_all(3F) ..................................................... 507
STRMOV(3F) .................................................................................................... mov(3F) ................................................................. 489
strmov(3F) .................................................................................................... mov(3F) ................................................................. 489
Subfield ........................................................................................................... inflmax(3F)........................................................ 559
Subfield ........................................................................................................... isrchmeq(3F) ..................................................... 577
Subfield ........................................................................................................... isrchmlt(3F) ..................................................... 579
Subfield ........................................................................................................... osrchm(3F) .......................................................... 594
Subfield ........................................................................................................... whenmeq(3F)........................................................ 611
Subfield ........................................................................................................... whenmlt(3F)........................................................ 613
Subroutine listing ............................................................................................ trbk(3F)............................................................... 520
Suspends PE execution until all PEs arrive at the barrier .............................. wait_barrier(3C) ........................................... 544
Symbolic dump program ................................................................................. symdebug(3F) ..................................................... 508
SYMDEBUG(3F) ............................................................................................... symdebug(3F) ..................................................... 508
symdebug(3F) ............................................................................................... symdebug(3F) ..................................................... 508
SYMDUMP(3F) ................................................................................................. symdump(3F)........................................................ 511
symdump(3F) ................................................................................................. symdump(3F)........................................................ 511
Synchronization (introduction) ........................................................................ intro_sync(3F) ................................................ 535
Synchronize multitasking ................................................................................ set_barrier(3C) .............................................. 539
Synchronize multitasking ................................................................................ wait_barrier(3C) ........................................... 544
SYSCLOCK(3F) ............................................................................................... sysclock(3F) ..................................................... 516
sysclock(3F) ............................................................................................... sysclock(3F) ..................................................... 516
System errors .................................................................................................. reprieve(3F) ..................................................... 498
System interface .............................................................................................. intro_interface(3F) ..................................... 417
Table (add word to) ........................................................................................ tmadw(3F) ............................................................ 459
Table Base Address ........................................................................................ tminit(3F) .......................................................... 462
Table descriptor vector ................................................................................... tminit(3F) .......................................................... 462
Table initialization .......................................................................................... tminit(3F) .......................................................... 462

Index-18 004– 2165– 002

Table Length Table ......................................................................................... tminit(3F) .......................................................... 462
Table management .......................................................................................... intro_heap(3F) ................................................ 445
Table management statistics ........................................................................... tmamu(3F) ............................................................ 460
Table search .................................................................................................... tmmsc(3F) ............................................................ 463
Table (search) .................................................................................................. tmsrc(3F) ............................................................ 467
Table search vector ......................................................................................... tmvsc(3F) ............................................................ 468
Table space ...................................................................................................... tmptc(3F) ............................................................ 465
Table space adjustmenets ................................................................................ tmptc(3F) ............................................................ 465
Table space allocation ..................................................................................... tmats(3F) ............................................................ 461
Table space collisions ..................................................................................... tmptc(3F) ............................................................ 465
Table space preset ........................................................................................... tmpts(3F) ............................................................ 466
task CPU time ................................................................................................. icpused(3F)........................................................ 488
Task (delay) .................................................................................................... wait_event(3C) ................................................ 545
Task routines (UNICOS/mk) .......................................................................... intro_sync(3F) ................................................ 535
Temporarily disables or enables bidirectional memory transfers ................... clearbt(3F)........................................................ 420
Terminate Fortran program ............................................................................. exit(3F)............................................................... 423
Test multitasking barrier ................................................................................. test_barrier(3C) ........................................... 542
Test multitasking event ................................................................................... test_event(3C) ................................................ 543
TEST_BARRIER(3C) ..................................................................................... test_barrier(3C) ........................................... 542
test_barrier(3C) ..................................................................................... test_barrier(3C) ........................................... 542
TEST_EVENT(3C) .......................................................................................... test_event(3C) ................................................ 543
test_event(3C) .......................................................................................... test_event(3C) ................................................ 543
Tests a barrier to determine its state (set or cleared) ..................................... test_barrier(3C) ........................................... 542
Time conversion .............................................................................................. dtts(3F)............................................................... 480
Time elapsed wall-clock ................................................................................. timef(3F) ............................................................ 517
Time in standard time ..................................................................................... unitts(3F) .......................................................... 530
Time limit ....................................................................................................... nlimit(3F) .......................................................... 432
Time to ASCII ................................................................................................ tsdt(3F)............................................................... 528
Time to time-stamp ......................................................................................... dtts(3F)............................................................... 480
TIMEF(3F) ...................................................................................................... timef(3F) ............................................................ 517
timef(3F) ...................................................................................................... timef(3F) ............................................................ 517
Time-stamp conversion ................................................................................... dtts(3F)............................................................... 480
Time-stamp units ............................................................................................. unitts(3F) .......................................................... 530
Timing routines ............................................................................................... timef(3F) ............................................................ 517
Timing routines ............................................................................................... tremain(3F)........................................................ 523
TMADW(3F) ...................................................................................................... tmadw(3F) ............................................................ 459
tmadw(3F) ...................................................................................................... tmadw(3F) ............................................................ 459
TMAMU(3F) ...................................................................................................... tmamu(3F) ............................................................ 460
tmamu(3F) ...................................................................................................... tmamu(3F) ............................................................ 460
TMATS(3F) ...................................................................................................... tmats(3F) ............................................................ 461
tmats(3F) ...................................................................................................... tmats(3F) ............................................................ 461
TMINIT(3F) .................................................................................................... tminit(3F) .......................................................... 462
tminit(3F) .................................................................................................... tminit(3F) .......................................................... 462
TMMSC(3F) ...................................................................................................... tmmsc(3F) ............................................................ 463
tmmsc(3F) ...................................................................................................... tmmsc(3F) ............................................................ 463
TMMVE(3F) ...................................................................................................... tmmve(3F) ............................................................ 464
tmmve(3F) ...................................................................................................... tmmve(3F) ............................................................ 464
TMPTC(3F) ...................................................................................................... tmptc(3F) ............................................................ 465
tmptc(3F) ...................................................................................................... tmptc(3F) ............................................................ 465
TMPTS(3F) ...................................................................................................... tmpts(3F) ............................................................ 466

004– 2165– 002 Index-19

tmpts(3F) ...................................................................................................... tmpts(3F) ............................................................ 466
TMSRC(3F) ...................................................................................................... tmsrc(3F) ............................................................ 467
tmsrc(3F) ...................................................................................................... tmsrc(3F) ............................................................ 467
TMVSC(3F) ...................................................................................................... tmvsc(3F) ............................................................ 468
tmvsc(3F) ...................................................................................................... tmvsc(3F) ............................................................ 468
Trace call ......................................................................................................... setplimq(3F) ..................................................... 503
Trace return ..................................................................................................... setplimq(3F) ..................................................... 503
Traceback level ............................................................................................... trbklvl(3F)........................................................ 521
Traceback print (Fortran) ................................................................................ tracebk(3F)........................................................ 518
Traceback routines .......................................................................................... intro_progaids(3F) ....................................... 469
TRACEBK variable ........................................................................................ reprieve(3F) ..................................................... 498
TRACEBK(3F) ................................................................................................. tracebk(3F)........................................................ 518
tracebk(3F) ................................................................................................. tracebk(3F)........................................................ 518
Tracing and timing routines ............................................................................ intro_progaids(3F) ....................................... 469
trackback ......................................................................................................... abort(3F) ............................................................ 419
Trailing blank to null conversion .................................................................... rbn(3F) ................................................................. 380
Trailing blanks not counted ............................................................................ trimlen(3F)........................................................ 524
Transfer bytes or bits ...................................................................................... mov(3F) ................................................................. 489
TRBK environment variables ......................................................................... reprieve(3F) ..................................................... 498
TRBK(3F) ........................................................................................................ trbk(3F)............................................................... 520
trbk(3F) ........................................................................................................ trbk(3F)............................................................... 520
TRBKLVL(3F) ................................................................................................. trbklvl(3F)........................................................ 521
trbklvl(3F) ................................................................................................. trbklvl(3F)........................................................ 521
TREMAIN(3F) ................................................................................................. tremain(3F)........................................................ 523
tremain(3F) ................................................................................................. tremain(3F)........................................................ 523
TRIMLEN(3F) ................................................................................................. trimlen(3F)........................................................ 524
trimlen(3F) ................................................................................................. trimlen(3F)........................................................ 524
TSDT(3F) ........................................................................................................ tsdt(3F)............................................................... 528
tsdt(3F) ........................................................................................................ tsdt(3F)............................................................... 528
TSECND(3F) .................................................................................................... tsecnd(3F) .......................................................... 526
tsecnd(3F) .................................................................................................... tsecnd(3F) .......................................................... 526
TSMT(3F) ........................................................................................................ tsmt(3F)............................................................... 529
tsmt(3F) ........................................................................................................ tsmt(3F)............................................................... 529
U32(3F) ........................................................................................................... p32(3F) ................................................................. 496
u32(3F) ........................................................................................................... p32(3F) ................................................................. 496
U6064(3F) ...................................................................................................... p6460(3F) ............................................................ 497
u6064(3F) ...................................................................................................... p6460(3F) ............................................................ 497
UNAME(3F) ...................................................................................................... uname(3F) ............................................................ 442
uname(3F) ...................................................................................................... uname(3F) ............................................................ 442
UNITTS(3F) .................................................................................................... unitts(3F) .......................................................... 530
unitts(3F) .................................................................................................... unitts(3F) .......................................................... 530
Unpack 60 into 64 bits ................................................................................... p6460(3F) ............................................................ 497
Unpack data .................................................................................................... unpack(3F) .......................................................... 531
Unpack from 32 to 64 bits .............................................................................. p32(3F) ................................................................. 496
UNPACK(3F) .................................................................................................... unpack(3F) .......................................................... 531
unpack(3F) .................................................................................................... unpack(3F) .......................................................... 531
USCCTC(3F) .................................................................................................... uscctc(3F) .......................................................... 381
uscctc(3F) .................................................................................................... uscctc(3F) .......................................................... 381
USCCTI(3F) .................................................................................................... uscctc(3F) .......................................................... 381
USDCTC(3F) .................................................................................................... usdctc(3F) .......................................................... 383

Index-20 004– 2165– 002

usdctc(3F) .................................................................................................... usdctc(3F) .......................................................... 383
USDCTI(3F) .................................................................................................... usdcti(3F) .......................................................... 384
usdcti(3F) .................................................................................................... usdcti(3F) .......................................................... 384
USICTC(3F) .................................................................................................... usictc(3F) .......................................................... 385
usictc(3F) .................................................................................................... usictc(3F) .......................................................... 385
USICTI(3F) .................................................................................................... usictc(3F) .......................................................... 385
usicti(3F) .................................................................................................... usictc(3F) .......................................................... 385
USICTP(3F) .................................................................................................... usictp(3F) .......................................................... 387
usictp(3F) .................................................................................................... usictp(3F) .......................................................... 387
USLCTC(3F) .................................................................................................... uslctc(3F) .......................................................... 388
uslctc(3F) .................................................................................................... uslctc(3F) .......................................................... 388
USLCTI(3F) .................................................................................................... uslctc(3F) .......................................................... 388
uslcti(3F) .................................................................................................... uslctc(3F) .......................................................... 388
USPCTC(3F) .................................................................................................... uspctc(3F) .......................................................... 389
uspctc(3F) .................................................................................................... uspctc(3F) .......................................................... 389
USSCTC(3F) .................................................................................................... ussctc(3F) .......................................................... 390
ussctc(3F) .................................................................................................... ussctc(3F) .......................................................... 390
USSCTI(3F) .................................................................................................... usscti(3F) .......................................................... 391
usscti(3F) .................................................................................................... usscti(3F) .......................................................... 391
Validity of block address ................................................................................ ihpvalid(3F) ..................................................... 458
Values in a subfield ........................................................................................ inflmax(3F)........................................................ 559
Values in a vector ........................................................................................... intmax(3F) .......................................................... 561
Variable bit or byte move ............................................................................... mov(3F) ................................................................. 489
Variable byte replace ...................................................................................... byt(3F) ................................................................. 479
VAX 32-bit floating-point to 64-bit single-precision ..................................... vxsctc(3F) .......................................................... 410
VAX 64-bit complex to Cray complex conversion ........................................ vxzctc(3F) .......................................................... 413
VAX 64-bit G format to single-precision conversion .................................... vxgctc(3F) .......................................................... 402
VAX conversion ............................................................................................. vxdctc(3F) .......................................................... 399
VAX integer to 64-bit integer conversion ...................................................... vxictc(3F) .......................................................... 405
VAX logical value to 64-bit logical value conversion ................................... vxlctc(3F) .......................................................... 408
VAX to Cray conversion ................................................................................ vax2cray(3F) ..................................................... 393
VAX2CRAY(3F) ............................................................................................... vax2cray(3F) ..................................................... 393
vax2cray(3F) ............................................................................................... vax2cray(3F) ..................................................... 393
VAX2MIPS(3F) ............................................................................................... vax2mips(3F) ..................................................... 396
vax2mips(3F) ............................................................................................... vax2mips(3F) ..................................................... 396
Vector search .................................................................................................. intro_sortsearch(3F) .................................. 547
Vector search .................................................................................................. cluseq(3F) .......................................................... 551
Vector search .................................................................................................. clusflt(3F)........................................................ 553
Vector search .................................................................................................. clusilt(3F)........................................................ 555
Vector search .................................................................................................. iilz(3F)............................................................... 557
Vector search .................................................................................................. isrcheq(3F)........................................................ 571
Vector search .................................................................................................. isrchflt(3F) ..................................................... 573
Vector search .................................................................................................. isrchilt(3F) ..................................................... 575
Vector search .................................................................................................. isrchmeq(3F) ..................................................... 577
Vector search .................................................................................................. isrchmlt(3F) ..................................................... 579
Vector search .................................................................................................. osrchi(3F) .......................................................... 592
Vector search .................................................................................................. osrchm(3F) .......................................................... 594
Vector search .................................................................................................. wheneq(3F) .......................................................... 605
Vector search .................................................................................................. whenflt(3F)........................................................ 607
Vector search .................................................................................................. whenilt(3F)........................................................ 609

004– 2165– 002 Index-21

Vector search .................................................................................................. whenmeq(3F)........................................................ 611
Vector search .................................................................................................. whenmlt(3F)........................................................ 613
Vector table search .......................................................................................... tmvsc(3F) ............................................................ 468
Vector-scalar comparison ................................................................................ bitvec(3F) .......................................................... 474
Vector-scalar comparison ................................................................................ bitvecm(3F)........................................................ 477
VXDCTC(3F) .................................................................................................... vxdctc(3F) .......................................................... 399
vxdctc(3F) .................................................................................................... vxdctc(3F) .......................................................... 399
VXDCTI(3F) .................................................................................................... vxdcti(3F) .......................................................... 400
vxdcti(3F) .................................................................................................... vxdcti(3F) .......................................................... 400
VXGCTC(3F) .................................................................................................... vxgctc(3F) .......................................................... 402
vxgctc(3F) .................................................................................................... vxgctc(3F) .......................................................... 402
VXGCTI(3F) .................................................................................................... vxgcti(3F) .......................................................... 403
vxgcti(3F) .................................................................................................... vxgcti(3F) .......................................................... 403
VXICTC(3F) .................................................................................................... vxictc(3F) .......................................................... 405
vxictc(3F) .................................................................................................... vxictc(3F) .......................................................... 405
VXICTI(3F) .................................................................................................... vxicti(3F) .......................................................... 406
vxicti(3F) .................................................................................................... vxicti(3F) .......................................................... 406
VXLCTC(3F) .................................................................................................... vxlctc(3F) .......................................................... 408
vxlctc(3F) .................................................................................................... vxlctc(3F) .......................................................... 408
VXLCTI(3F) .................................................................................................... vxlcti(3F) .......................................................... 409
vxlcti(3F) .................................................................................................... vxlcti(3F) .......................................................... 409
VXSCTC(3F) .................................................................................................... vxsctc(3F) .......................................................... 410
vxsctc(3F) .................................................................................................... vxsctc(3F) .......................................................... 410
VXSCTI(3F) .................................................................................................... vxscti(3F) .......................................................... 411
vxscti(3F) .................................................................................................... vxscti(3F) .......................................................... 411
VXZCTC(3F) .................................................................................................... vxzctc(3F) .......................................................... 413
vxzctc(3F) .................................................................................................... vxzctc(3F) .......................................................... 413
VXZCTI(3F) .................................................................................................... vxzcti(3F) .......................................................... 414
vxzcti(3F) .................................................................................................... vxzcti(3F) .......................................................... 414
WAIT_BARRIER(3C) ..................................................................................... wait_barrier(3C) ........................................... 544
wait_barrier(3C) ..................................................................................... wait_barrier(3C) ........................................... 544
WAIT_EVENT(3C) .......................................................................................... wait_event(3C) ................................................ 545
wait_event(3C) .......................................................................................... wait_event(3C) ................................................ 545
Wall-clock time function ................................................................................ timef(3F) ............................................................ 517
Watchpointing routines ................................................................................... intro_progaids(3F) ....................................... 469
WHENEQ(3F) .................................................................................................... wheneq(3F) .......................................................... 605
wheneq(3F) .................................................................................................... wheneq(3F) .......................................................... 605
WHENFGE(3F) ................................................................................................. whenflt(3F)........................................................ 607
whenfge(3F) ................................................................................................. whenflt(3F)........................................................ 607
WHENFGT(3F) ................................................................................................. whenflt(3F)........................................................ 607
whenfgt(3F) ................................................................................................. whenflt(3F)........................................................ 607
WHENFLE(3F) ................................................................................................. whenflt(3F)........................................................ 607
whenfle(3F) ................................................................................................. whenflt(3F)........................................................ 607
WHENFLT(3F) ................................................................................................. whenflt(3F)........................................................ 607
whenflt(3F) ................................................................................................. whenflt(3F)........................................................ 607
WHENIGE(3F) ................................................................................................. whenilt(3F)........................................................ 609
whenige(3F) ................................................................................................. whenilt(3F)........................................................ 609
WHENIGT(3F) ................................................................................................. whenilt(3F)........................................................ 609
whenigt(3F) ................................................................................................. whenilt(3F)........................................................ 609
WHENILE(3F) ................................................................................................. whenilt(3F)........................................................ 609

Index-22 004– 2165– 002

whenile(3F) ................................................................................................. whenilt(3F)........................................................ 609
WHENILT(3F) ................................................................................................. whenilt(3F)........................................................ 609
whenilt(3F) ................................................................................................. whenilt(3F)........................................................ 609
WHENMEQ(3F) ................................................................................................. whenmeq(3F)........................................................ 611
whenmeq(3F) ................................................................................................. whenmeq(3F)........................................................ 611
WHENMGE(3F) ................................................................................................. whenmlt(3F)........................................................ 613
whenmge(3F) ................................................................................................. whenmlt(3F)........................................................ 613
WHENMGT(3F) ................................................................................................. whenmlt(3F)........................................................ 613
whenmgt(3F) ................................................................................................. whenmlt(3F)........................................................ 613
WHENMLE(3F) ................................................................................................. whenmlt(3F)........................................................ 613
whenmle(3F) ................................................................................................. whenmlt(3F)........................................................ 613
WHENMLT(3F) ................................................................................................. whenmlt(3F)........................................................ 613
whenmlt(3F) ................................................................................................. whenmlt(3F)........................................................ 613
WHENMNE(3F) ................................................................................................. whenmeq(3F)........................................................ 611
whenmne(3F) ................................................................................................. whenmeq(3F)........................................................ 611
WHENNE(3F) .................................................................................................... wheneq(3F) .......................................................... 605
whenne(3F) .................................................................................................... wheneq(3F) .......................................................... 605
Word (add to table) ......................................................................................... tmadw(3F) ............................................................ 459
Word pack and unpack ................................................................................... p32(3F) ................................................................. 496
Words move .................................................................................................... tmmve(3F) ............................................................ 464
Write SDS count ............................................................................................. auxstat(3F)........................................................ 473
XPFMT(3F) ...................................................................................................... xpfmt(3F) ............................................................ 532
xpfmt(3F) ...................................................................................................... xpfmt(3F) ............................................................ 532

004– 2165– 002 Index-23