CM FORTRAN LIBRARIES REFERENCE MANUAL Version 2.1, January 1994 Copyright (c) 1994 Thinking Machines Corporation. CHAPTER 1: INTRODUCTION ************************ The Utility Library provides convenient access from CM Fortran to the capabilities of lower-level CM software. The purpose is typically to achieve functionality or performance beyond what is currently available from the compiler. As the compiler continues to develop, some of the utility procedures become redundant with CM Fortran language features. Each chapter of Part I compares utility procedures with the corresponding language features in the current release and notes any differences in behavior or performance. 1.1 WHY A UTILITY LIBRARY? --------------------------- CM Fortran programmers can use Utility Library procedures in situations where one is normally tempted to make explicit calls to lower-level software. There are several advantages to using the Utility Library instead in these situations: o Convenience. The utility procedures take CM Fortran array names and other CM Fortran data objects as arguments. There is no need to convert CM Fortran objects into the data types used by lower- level software. o CM Portability. With the few exceptions noted, the utility procedures support all CM hardware configurations and execution models, regardless of the particular lower-level software involved. There is no need to recode these calls to port a program from one CM system to another, even though the underlying system software may be quite different. o Support. The Utility Library is a supported part of the CM Fortran product. Unlike some of the underlying system software, the library remains stable over time so that programs using it do not require maintenance. 1.2 CONTENTS OF THE UTILITY LIBRARY ------------------------------------ The chapters that follow describe the Utility Library procedures under these functional categories. o Inquiries o System inquiry o Array inquiry o Random number generation o Dynamic array allocation o Array aliasing o Alias construction o Alias operations o Alias descriptor inquiry o Execution environment o Data motion (interprocessor) o Array transfers o Scatters with combining (plus array address construction) o Parallel prefix operations o Ranking and sorting o Data motion (local) o Table look-ups o Gathers/scatters on serial axes o Parallel I/O o CM file operations o CM I/O via devices or sockets 1.3 THE UTILITY LIBRARY HEADER FILE ------------------------------------ Each program unit that uses procedures from the Utility Library must include its header file: INCLUDE '/usr/include/cm/CMF_defs.h' The pathname of CMF_defs.h may be different if your system administrator has revised the CM directory structure. The compiler command cmf links with the Utility Library automatically; no explicit linking is required. 1.4 RESTRICTIONS ON UTILITY PROCEDURES --------------------------------------- o Aligned arrays. The utility procedures do not operate on arrays that are aligned with other arrays of higher rank or aligned with non-zero dimension offset(s) with any other array. o Lower bounds. The procedure arguments that index into arrays assume that the array dimensions have a lower bound of 1. Any other lower bound value is ignored in these cases. This restriction is noted under the procedures to which it applies, such as CMF_DEPOSIT_ GRID_COORDINATE and CMF_AREF_1D. A few additional restrictions apply only to particular procedures. These are noted both in the text discussing the functional categories and in the man pages for those procedures. 1.5 SUPPORT FOR THE 64-BIT INTEGER TYPE ---------------------------------------- On CM-5 systems with vector units, you can take advantage of the Utility Library procedures' support for the 64-bit integer type. The INTEGER*8 type can be used for any CM array argument to procedures in the CM Fortran Utility Library, except the array aliasing procedures. It may not be used, however, for integer scalar arguments. For front- end array arguments, such as the array argument to the dynamic allocation utilities, an INTEGER*8 argument is accepted, but the extra length is not used. When specifying a type as an argument to a utility procedure, use the pre-defined constant CMF_LONG_S_INTEGER. ***************************************************************** The information in this document is subject to change without notice and should not be construed as a commitment by Think- ing Machines Corporation. Thinking Machines reserves the right to make changes to any product described herein. Although the information in this document has been reviewed and is believed to be reliable, Thinking Machines Corporation assumes no liability for errors in this document. Thinking Machines does not assume any liability arising from the application or use of any information or product described herein. ***************************************************************** Connection Machine (r) is a registered trademark of Thinking Machines Corporation. CM, CM-2, CM-200, CM-5, CM-5 Scale 3, and DataVault are trademarks of Thinking Machines Corporation. CMOST, CMAX, and Prism are trademarks of Thinking Machines Corporation. C* (r) is a registered trademark of Thinking Machines Corporation. Paris and CM Fortran are trademarks of Thinking Machines Corporation. CMMD, CMSSL, and CMX11 are trademarks of Thinking Machines Corporation. CMview is a trademark of Thinking Machines Corporation. Scalable Computing (SC) is a trademark of Thinking Machines Corporation. Scalable Disk Array (SDA) is a trademark of Thinking Machines Corporation. Thinking Machines (r) is a registered trademark of Thinking Machines Corporation. SPARC and SPARCstation are trademarks of SPARC International, Inc. Sun, Sun-4, and Sun Workstation are trademarks of Sun Microsystems, Inc. UNIX is a trademark of UNIX System Laboratories, Inc. Copyright (c) 1994 by Thinking Machines Corporation. All rights reserved. This file contains documentation produced by Thinking Machines Corporation. Unauthorized duplication of this documentation is prohibited. Thinking Machines Corporation 245 First Street Cambridge, Massachusetts 02142-1264 (617) 234-1000