The Basis System Release 12.1 The Basis Development Team November 13, 2007 Lawrence Livermore National Laboratory Email: [email protected] COPYRIGHT NOTICE All files in the Basis system are Copyright 1994-2001, by the Regents of the University of California. All rights reserved. This work was produced at the University of California, Lawrence Livermore National Laboratory (UC LLNL) under contract no. W-7405-ENG-48 (Contract 48) between the U.S. Department of Energy (DOE) and The Regents of the University of California (University) for the operation of UC LLNL. Copyright is reserved to the University for purposes of controlled dissemination, commercialization through formal licensing, or other disposition under terms of Contract 48; DOE policies, regulations and orders; and U.S. statutes. The rights of the Federal Government are reserved under Contract 48 subject to the restrictions agreed upon by the DOE and University as allowed under DOE Acquisition Letter 88-1. DISCLAIMER This software was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, or assumes any liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of the authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes. DOE Order 1360.4A Notice This computer software has been developed under the sponsorship of the Department of Energy. Any further distribution by any holder of this software package or other data therein outside of DOE offices or other DOE contractors, unless otherwise specifically provided for, is prohibited without the approval of the Energy, Science and Technology Software Center. Requests from outside the Department for DOE-developed computer software shall be directed to the Director, ESTSC, P.O. Box 1020, Oak Ridge, TN, 37831-1020. UCRL-MA-118543 CONTENTS 1 The Basis System 1 1.1 Environment Variables ................................ 1 1.2 Basis Is Both a Program and a Development System ................ 1 1.3 About This Manual .................................. 2 I Running a Basis Program, A Tutorial 5 2 Getting Started 7 2.1 What is Basis? .................................... 7 2.2 Starting the Program ................................. 7 2.3 Getting Information ................................. 8 2.4 Comparison of Basis and Fortran .......................... 9 3 The Basis Language 11 3.1 Assignments and Expressions ............................ 11 3.2 Input from a File ................................... 13 3.3 Some Differences from Fortran ........................... 13 3.4 Declaring Variables ................................. 14 3.5 Some Elements of Array Syntax ........................... 15 3.6 IF Statements ..................................... 16 3.7 Looping Constructs ................................. 16 3.8 Vector Syntax ..................................... 17 3.9 Differences between Basis and Fortran ....................... 18 4 Graphics 21 5 Text Input and Output 23 5.1 Stream Input ..................................... 23 5.2 Stream Output .................................... 25 6 Functions 27 6.1 Defining Functions .................................. 27 i 6.2 Arguments Passed by Value ............................. 28 6.3 Further Differences with Fortran ........................... 29 7 Built-in and Compiled Functions 31 7.1 max and min Versus sup and inf ........................... 32 7.2 iota and spanl ..................................... 33 7.3 Information about Arrays: length, shape ....................... 33 7.4 Summing Arrays: sum ................................ 35 7.5 Vector Conditionals with where ........................... 35 8 Commands 37 8.1 The Basis Command Capability ........................... 37 9 Saving and Restoring Code and Data in Binary 41 9.1 The PFB Package .................................. 41 9.2 Reading in Previously Saved Data .......................... 42 10 Error Recovery and Diagnosis 43 10.1 Error Recovery .................................... 43 10.2 Syntactic and Semantic Errors ............................ 43 11 Deciphering Commands 49 II Basis Language Reference 53 12 Basis Input 55 13 Basis Tokens 57 13.1 What Is A Token? .................................. 57 13.2 Special Characters .................................. 57 13.3 Alphanumeric and ConstantTokens ......................... 58 14 Declaring and Initializing Variables 61 14.1 GLOBAL declarations ................................ 63 14.2 Package declarations ................................. 63 14.3 Chameleon Variables ................................. 63 14.4 Computed Names .................................. 64 14.5 Range Variables ................................... 64 14.6 The Colon Notation For Vectors ........................... 66 14.7 Indirect Variables ................................... 67 15 Expressions 69 15.1 Introduction ..................................... 69 15.2 Operands ....................................... 69 15.3 Operators ....................................... 70 ii 15.4 Delimiters ...................................... 72 15.5 Array References and Operations .......................... 74 15.6 The Concatenation Operator ............................. 79 16 Display and Assignment Statements 81 16.1 Assignment Actions ................................. 83 16.2 Operator Assignments ................................ 83 16.3 The Append Statement ................................ 84 16.4 The Logical IF Statement .............................. 85 16.5 The Structured IF Statement ............................. 86 17 WHILE Statement 89 17.1 WHILE Statement .................................. 89 17.2 BREAK and NEXT Statements ........................... 90 18 FOR Statement 93 19 DO Statement 95 19.1 Uncontrolled DO .................................. 95 19.2 DO-UNTIL ...................................... 95 19.3 Controlled DO .................................... 96 20 Functions Listed by Type 99 20.1 Common Mathematical ............................... 99 20.2 Trigonometry ..................................... 99 20.3 Type Conversion and Complex Numbers ...................... 99 20.4 Arrays ........................................ 100 20.5 Character Manipulation ............................... 100 20.6 Special Purpose ................................... 100 20.7 Obtain/Set Scalar Values ............................... 100 21 Built-in Functions 101 22 User-Defined Functions 111 22.1 Defining Functions .................................. 111 22.2 RETURN ....................................... 112 22.3 Local Variables .................................... 112 22.4 CALL Is By Value .................................. 112 22.5 Examples of User Functions ............................. 113 23 Compiled Functions 115 23.1 CALLing By Address ................................ 116 24 Defining Your Own Commands 117 24.1 The COMMAND Statement ............................. 117 24.2 Changing the Default Type of a COMMAND Argument .............. 120 iii 24.3 Specifying Other Delimiters in a COMMAND Statement .............. 121 24.4 No Delimiters at All: the COMMAND L ...................... 123 25 The Search Stack 125 26 Package Control Statements 127 27 The CTL Package 129 28 Removing Functions and Variables 131 29 LIST Command 133 30 Obtaining and Setting Scalar Values 135 31 Help and News 137 32 Input, Output, and External File Access 139 32.1 Reading Basis Code From a Text File ........................ 139 32.2 Resuming Reading .................................. 141 32.3 Printing Messages on the Terminal ......................... 141 32.4 Changing the Destination of Basis Output ...................... 141 33 The Stream I/O Facility 143 33.1 Introduction to Stream I/O .............................. 143 33.2 Opening and Creating Files ............................. 143 33.3 The Input Operator >> ............................... 144 33.4 The Output Operator << .............................. 150 33.5 The Format Function ................................. 152 33.6 Closing File ..................................... 154 34 The Macro Facility 157 34.1 Protection Brackets .................................. 157 34.2 DEFINE Statement ................................. 158 34.3 MDEF - MEND Statement .............................. 159 34.4 IFELSE Statement .................................. 160 34.5 UNDEFINE Statement ............................... 161 35 Executing System Commands from the Parser 163 36 Timing 165 37 Ending Basis 167 38 Error Recovery 169 39 Interrupting Basis 173 iv 40 List of Reserved Words 175 41 List of Non-Alphanumeric Tokens 177 42 List of Parser Variables 179 42.1 Variables ....................................... 179 42.2 Constants ....................................... 181 43 List of Compiled Functions 183 43.1 Working With Attributes ............................... 183 43.2 Help and News .................................... 184 43.3 Memory Management