You are on page 1of 1049

GAUSS

TM
3.2 for UNIX
Users Guide
Aptech Systems, Inc.
Information in this document is subject to change without notice and does not
represent a commitment on the part of Aptech Systems, Inc. The software described in
this document is furnished under a license agreement or nondisclosure agreement. The
software may be used or copied only in accordance with the terms of the agreement.
The purchaser may make one copy of the software for backup purposes. No part of this
manual may be reproduced or transmitted in any form or by any means, electronic or
mechanical, including photocopying and recording, for any purpose other than the
purchasers personal use without the written permission of Aptech Systems, Inc.
c _Copyright Aptech Systems, Inc. Maple Valley WA 1984-2000
All Rights Reserved.
GAUSS, GAUSS Light, GAUSSi, GAUSS-386, and GAUSS-386i are trademarks of
Aptech Systems, Inc.
GEM is a trademark of Digital Research, Inc.
Lotus is a trademark of Lotus Development Corp.
HP LaserJet and HP-GL are trademarks of Hewlett-Packard Corp.
PostScript is a trademark of Adobe Systems Inc.
IBM is a trademark of International Business Machines Corporation
Hercules is a trademark of Hercules Computer Technology, Inc.
GraphiC is a trademark of Scientic Endeavors Corporation
Tektronix is a trademark of Tektronix, Inc.
Other trademarks are the property of their respective owners.
Part Number: GM-UNIX-PDF
Revision Date: August 9, 2000
Contents
1 Installation and Operation 1
1.1 Installing GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Extracting the Files . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.2 Solaris 2.x Volume Management . . . . . . . . . . . . . . . . . . . 2
1.1.3 Uncompressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.4 Conguring GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Starting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.1 X Window Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.2 Terminal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 Running GAUSS programs . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.6 Quitting GAUSS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.6.1 X Window Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.6.2 Terminal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.7 Editing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.8 Command Line Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.9 Command Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.10 Running Programs Written for the PC . . . . . . . . . . . . . . . . . . . . 9
1.11 atog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.12 File Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.12.1 Data Sets, Matrix Files and String Files . . . . . . . . . . . . . . . 10
1.13 Cache Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.14 Graphics Conguration File . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 Tutorial 15
2.1 Loading and Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.1 Starting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.2 Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.1 The let Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.2 Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.3 Special Matrix Functions . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.4 Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.3 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
ii
2.3.1 String Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.3.2 Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3.3 String Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.4 Matrix Description and Printing . . . . . . . . . . . . . . . . . . . . . . . 20
2.4.1 The print Statement . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.2 The format Statement . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 Indexing Matrices and Extracting Submatrices . . . . . . . . . . . . . . . 23
2.5.1 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.5.2 Using delif and selif . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.6 Running a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.7 Element-by-Element Operators . . . . . . . . . . . . . . . . . . . . . . . . 27
2.8 Creating a Data Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.8.1 Reading an ASCII File . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.9 Writing a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.10 Vectorizing for Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3 Windows 37
3.1 General Window Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.1.1 Opening a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.2 Moving a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.3 Resizing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
iii
3.1.4 Panning a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.5 Clearing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.6 Closing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.7 Selecting a Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.8 Getting Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.2 PQG Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.1 Opening a PQG Window . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.2 Selecting Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.3 Aspect Ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.3 Text Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.3.1 Opening a Text Window . . . . . . . . . . . . . . . . . . . . . . . . 41
3.3.2 Selecting Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.3.3 Locating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.3.4 Wrapping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.4 TTY Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.4.1 Opening a TTY Window . . . . . . . . . . . . . . . . . . . . . . . 43
3.4.2 Locating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.4.3 Wrapping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.5 Special Purpose Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.5.1 Command Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.5.2 Help Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.5.3 Active Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
iv
4 Debugger 49
4.1 Starting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.3 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.4 Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5 Foreign Language Interface 55
5.1 Creating Dynamic Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.1.1 Solaris 2.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.1.2 SunOS 4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.1.3 IBM AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.1.4 DEC OSF1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.5 HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.6 SGI IRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.7 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.2 Writing FLI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6 FLI Function Reference 59
7 Language Fundamentals 65
7.1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.2 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
v
7.2.1 Executable Statements . . . . . . . . . . . . . . . . . . . . . . . . . 66
7.2.2 Nonexecutable Statements . . . . . . . . . . . . . . . . . . . . . . . 67
7.3 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
7.3.1 Main Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.3.2 Secondary Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.4 Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.5 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.6 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.6.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.6.2 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.6.3 Strings and String Arrays . . . . . . . . . . . . . . . . . . . . . . . 77
7.6.4 Character Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.6.5 Special Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
7.7 Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.8 Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.8.1 Looping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.8.2 Conditional Branching . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.8.3 Unconditional Branching . . . . . . . . . . . . . . . . . . . . . . . 88
7.9 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.10 Rules of Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
vi
7.10.1 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.10.2 Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.10.3 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.10.4 Extraneous Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.10.5 Symbol Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.10.6 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.10.7 Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . 91
7.10.8 Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.10.9 Indexing Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.10.10Arrays of Matrices and Strings . . . . . . . . . . . . . . . . . . . . 93
7.10.11Arrays of Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8 Operators 95
8.1 Element-by-Element Operators . . . . . . . . . . . . . . . . . . . . . . . . 95
8.2 Matrix Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.2.1 Numeric Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.2.2 Other Matrix Operators . . . . . . . . . . . . . . . . . . . . . . . . 100
8.3 Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.4 Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.5 Other Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.6 Using Dot Operators with Constants . . . . . . . . . . . . . . . . . . . . . 110
vii
9 Procedures and Keywords 111
9.1 Dening a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.1 Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.1.2 Local Variable Declarations . . . . . . . . . . . . . . . . . . . . . . 113
9.1.3 Body of Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.1.4 Returning from the Procedure . . . . . . . . . . . . . . . . . . . . 114
9.1.5 End of Procedure Denition . . . . . . . . . . . . . . . . . . . . . . 114
9.2 Calling a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.3 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.3.1 Dening a Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.3.2 Calling a Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.4 Passing Procedures to Procedures . . . . . . . . . . . . . . . . . . . . . . . 117
9.5 Indexing Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.6 Multiple Returns from Procedures . . . . . . . . . . . . . . . . . . . . . . 119
10 Libraries 121
10.1 Autoloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
10.1.1 Forward References . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
10.1.2 The Autoloader Search Path . . . . . . . . . . . . . . . . . . . . . 122
10.2 Global Declaration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.3.1 Using dec Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
viii
11 Compiler 133
11.1 Compiling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
11.1.1 Compiling a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
11.1.2 Compiling from EDIT Mode, DOS Only . . . . . . . . . . . . . . . 134
11.2 Saving the Current Workspace . . . . . . . . . . . . . . . . . . . . . . . . 134
11.3 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12 File I/O 137
12.1 ASCII Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
12.1.1 Matrix Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
12.1.2 General File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
12.2 Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
12.2.1 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
12.2.2 Creating Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
12.2.3 Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . 142
12.2.4 Distinguishing Character and Numeric Data . . . . . . . . . . . . . 143
12.3 Matrix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
12.4 File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
12.4.1 Small Matrix v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
12.4.2 Extended Matrix v89 . . . . . . . . . . . . . . . . . . . . . . . . . 147
12.4.3 Small String v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ix
12.4.4 Extended String v89 . . . . . . . . . . . . . . . . . . . . . . . . . . 148
12.4.5 Small Data Set v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
12.4.6 Extended Data Set v89 . . . . . . . . . . . . . . . . . . . . . . . . 149
12.4.7 Matrix v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
12.4.8 String v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
12.4.9 Data Set v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
12.4.10Matrix v96 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
12.4.11Data Set v96 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
13 Data Transformations 155
13.1 Data Loop Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
13.2 Using Other Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.3 Debugging Data Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.3.1 Translation Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.3.2 Compilation Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
13.3.3 Execution Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
13.4 Reserved Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
14 Data Loop Reference 159
15 Graphics Categorical Reference 175
15.1 Graph Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
x
15.2 Axes Control and Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
15.3 Text, Labels, Titles, and Fonts . . . . . . . . . . . . . . . . . . . . . . . . 176
15.4 Main Curve Lines and Symbols . . . . . . . . . . . . . . . . . . . . . . . . 176
15.5 Extra Lines and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
15.6 Window, Page, and Plot Control . . . . . . . . . . . . . . . . . . . . . . . 177
15.7 Output Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
15.8 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
16 Publication Quality Graphics 179
16.1 Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
16.2 General Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
16.3 Using Publication Quality Graphics . . . . . . . . . . . . . . . . . . . . . 180
16.3.1 Getting Started Right Away . . . . . . . . . . . . . . . . . . . . . . 180
16.3.2 Graphics Coordinate System . . . . . . . . . . . . . . . . . . . . . 183
16.4 Graphics Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
16.4.1 Using Window Functions . . . . . . . . . . . . . . . . . . . . . . . 185
16.4.2 Transparent Windows . . . . . . . . . . . . . . . . . . . . . . . . . 186
16.4.3 Saving Window Congurations . . . . . . . . . . . . . . . . . . . . 186
16.5 Interactive Draft Mode, DOS Only . . . . . . . . . . . . . . . . . . . . . . 186
16.6 Fonts and Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . 187
16.6.1 Selecting Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
xi
16.6.2 Greek and Mathematical Symbols . . . . . . . . . . . . . . . . . . 188
16.7 Hardcopy and Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
16.7.1 Printing the Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
16.7.2 Exporting Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
16.8 Global Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
17 Graphics Reference 205
18 Time and Date 257
18.1 Time and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
18.2 Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
18.2.1 Timed Iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
19 Utility: atog 263
19.1 Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
19.2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
19.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
19.4 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
20 Utility: liblist 279
20.1 Report Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
20.2 Using liblist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
xii
21 Categorical Reference 283
21.1 Window Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
21.2 Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
21.3 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
21.4 Error Handling and Debugging . . . . . . . . . . . . . . . . . . . . . . . . 285
21.5 Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
21.6 Program Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
22 Command Reference 287
23 Command Reference Introduction 331
23.1 Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
23.2 Global Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
23.2.1 Changing the Default Values . . . . . . . . . . . . . . . . . . . . . 332
23.2.2 The Procedure gausset . . . . . . . . . . . . . . . . . . . . . . . . 333
24 Commands by Category 335
24.1 Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
24.2 Matrix Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
24.3 Data Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
24.4 Compiler Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
24.5 Program Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
xiii
24.6 OS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
24.7 Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
24.8 Error Handling and Debugging . . . . . . . . . . . . . . . . . . . . . . . . 353
24.9 String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
24.10Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
24.11Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
24.12Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
25 Command Reference 357
A Fonts 973
B Performance Hints 979
B.1 Library System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
B.2 Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
B.3 Virtual Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
B.3.1 Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
B.3.2 Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
B.3.3 Hard Disk Maintenance . . . . . . . . . . . . . . . . . . . . . . . . 981
B.3.4 Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
B.3.5 CPU Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
C Reserved Words 983
xiv
D Operator Precedence 987
E Singularity Tolerance 989
E.1 Reading and Setting the Tolerance . . . . . . . . . . . . . . . . . . . . . . 989
E.2 Determining Singularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
F Saving Compiled Procedures 991
G transdat 993
H Error Messages 997
I Limits 1015
Index 1017
xv
xvi
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
Chapter 1
Installation and Operation
This chapter covers the basics of installing and running GAUSS on a UNIX
workstation. Please read the entire chapter before beginning. It is short and will save
time in the long run.
Please read the README* les that came with your shipment! They contain important
information that became available after the manual was printed.
1.1 Installing GAUSS
GAUSS is shipped on 3.5

oppy diskettes, 1/4

tape or DAT tape. This section gives


installation instructions for each. Each shipment also includes a hardcopy Installation
memo.
SEE THE INSTALLATION MEMO that came with your shipment! Instructions on the
memo, where dierent, override the instructions in this supplement.
If you are unfamiliar with UNIX, see your system administrator or system
documentation for information on the system commands referred to below. The device
names given are probably correct for your system.
1.1.1 Extracting the Files
Use mkdir to create a directory for GAUSS.
1
1. INSTALLATION AND OPERATION
mkdir gauss
Use cd to make the directory you created the current working directory.
cd gauss
Use tar to extract the les.
tar xvf device name
The following device names are suggestions. See your system administrator. If you are
using Solaris 2.x, see Section 1.1.2.
Operating System 3.5 inch diskette 1/4 inch tape DAT tape
Solaris 1.x SPARC /dev/rfd0 /dev/rst8
Solaris 2.x SPARC /dev/rfd0a (vol. mgt. o) /dev/rst12 /dev/rmt/1l
Solaris 2.x SPARC /vol/dev/aliases/floppy0 /dev/rst12 /dev/rmt/1l
Solaris 2.x x86 /dev/rfd0c (vol. mgt. o) /dev/rmt/1l
Solaris 2.x x86 /vol/dev/aliases/floppy0 /dev/rmt/1l
HP-UX /dev/rfloppy/c20Ad1s0 /dev/rmt/0m
IBM AIX /dev/rfd0 /dev/rmt.0
SGI IRIX /dev/rdsk/fds0d2.3.5hi
If GAUSS came on diskettes, repeat the tar command for each diskette.
1.1.2 Solaris 2.x Volume Management
If Solaris 2.x volume management is running, insert the oppy disk and type:
volcheck
to signal the system to mount the oppy. Then execute the tar command. When the
tar command nishes type:
eject
and remove the oppy if it is not automatically ejected.
The oppy device names for Solaris 2.x change when the volume manager is turned o
and on. To turn o volume management, become the superuser and type:
/etc/init.d/volmgt off
To turn on volume management, become the superuser and type:
/etc/init.d/volmgt on
2
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
1.1.3 Uncompressing
If the media was diskette, use the gunpack script to uncompress the les:
gunpack
1.1.4 Conguring GAUSS
GAUSSHOME environment variable
GAUSS needs an environment variable called GAUSSHOME. It should contain the
complete name of your GAUSS home directory. For example:
C shell
setenv GAUSSHOME /home/usr1/gauss
Korn, Bourne shell
GAUSSHOME=/home/usr1/gauss
export GAUSSHOME
GAUSS looks in the $GAUSSHOME directory for its conguration le, gauss.cfg.
gauss.cfg is a commented ASCII le that controls several startup defaults. It can be
edited before getting into GAUSS, allowing you to change any of the defaults. Anyone
who will be running GAUSS needs to have at least read access to gauss.cfg.
The standard GAUSS system directory layout is as follows:
$GAUSSHOME Base directory, executable les, conguration les
$GAUSSHOME/src Source les
$GAUSSHOME/lib Library les
$GAUSSHOME/examples Example les
$GAUSSHOME/wksp Workspace les, log les
As it is shipped, gauss.cfg assumes this directory structure and uses GAUSSHOME
to establish the base directory, so you dont have to edit it unless you change the
directory structure.
GAUSS creates temporary les during operation. Anyone who uses GAUSS must have
read/write/execute access to the directories where those les are located. As it is
shipped, this is the $GAUSSHOME/wksp directory.
You can specify a path to an alternate conguration le with the GAUSS CFG
environment variable. For example:
3
1. INSTALLATION AND OPERATION
C shell
setenv GAUSS_CFG /home/usr1/gauss/project1
Korn, Bourne shell
GAUSS_CFG=/home/usr1/gauss/project1
export GAUSS_CFG
The name of the le remains the same, i.e., gauss.cfg.
You can use the $() syntax in gauss.cfg to reference environment variables. For
example:
src_path = $(GAUSSHOME)/src
GAUSS uses an internal variable named gaussdir in gauss.cfg, so do not try to use an
environment variable named gaussdir in the le.
PATH environment variable
You should place a reference to the $GAUSSHOME directory in your system PATH
environment variable, so the operating system can nd the GAUSS executables.
1.2 Starting GAUSS
UNIX is case sensitive, so the commands below are case sensitive.
To start GAUSS in X Window mode, type:
gauss &
To start GAUSS in terminal or vanilla mode, type:
gauss -v
You must be in a UNIX terminal window such as an xterm or Command Tool. The
graphics and windowing functions are not available in terminal mode.
The GAUSS prompt looks like this:
(gauss)
4
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
1.3 Exiting GAUSS
1.3.1 X Window Mode
To end a GAUSS session, click on the Quit button.
1.3.2 Terminal Mode
If you are in terminal mode, type:
quit enter
at the GAUSS command prompt. See Section 1.6 for ways to stop a GAUSS program
that is executing.
1.4 Log Files
GAUSS creates an error log le and a command log le for each session. These will
need to be deleted periodically. They are generated with unique names containing the
process ID of the GAUSS session that created them. They are located in the directories
specied in the conguration le. The default is $GAUSSHOME/wksp.
1.5 Running GAUSS programs
To run a program from the GAUSS prompt, type
run lename
For example:
run max1.e
Programs to run can be listed on the command line when you start GAUSS. At the
UNIX command prompt, type
gauss lename [[lename...]]
GAUSS will run the programs specied, and return to the GAUSS command line.
5
1. INSTALLATION AND OPERATION
1.6 Quitting GAUSS Programs
1.6.1 X Window Mode
Click on Stop or Kill.
Use Kill only when necessaryit will always work, but it literally kills the compiler and
executer with no questions asked. It can leave your workspace in an indeterminate
state.
1.6.2 Terminal Mode
Esc enter
or
Esc! enter
or
stop enter
or
Ctrl-C
or
kill enter
You will be returned to the GAUSS command line.
If you have programs that expect to pick up Esc with the key function, you can turn
the trapping of Esc o in the conguration le. Either way, Esc! is active to stop a
program.
Use kill only when necessary, see above reference under X Window mode.
1.7 Editing Files
For the time being, you will have to use your own text editor to write GAUSS
programs. Several come with UNIX if you dont have one of your own. You can specify
a hook to an editor in the conguration le (see gauss.cfg for instructions). The
default editor is vi which is started by typing
edit myfile
from the GAUSS prompt.
6
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
1.8 Command Line Flags
There are several ags you can specify on the command line when starting GAUSS.
The following ags are supported:
-b run GAUSS in batch mode, look for keyboard input.
-B run GAUSS in batch mode, dont look for keyboard input. Use this
when you want to run GAUSS in the background.
-m turn o make.
-M turn on make.
-n do an implicit new before each program. Ignored if not in batch mode.
-s run stdin as a GAUSS program. During the execution of the program,
no keyboard input will be recognized. This ag cannot be combined with
others behind the same , and it must come after any other ags.
-T turn the translator on.
-t turn the translator o.
-v terminal or vanilla mode.
You can run GAUSS in batch mode. If your programs require user input, use the -b
ag. At the UNIX command prompt, type
gauss -b lename [[lename...]]
GAUSS will start up in batch mode, run the programs specied, then drop to the
UNIX command prompt. You can break the run with Ctrl-C, Esc, etc. (see below);
GAUSS will drop to command mode.
If your programs dont require user input, use the -B ag. At the UNIX command
prompt, type
gauss -B lename [[lename...]]
or
gauss -B lename [[lename...]] &
GAUSS will start up in batch mode, run the programs specied, then drop to the
system. You can break the run with Ctrl-C; GAUSS will drop to the GAUSS prompt.
All other keyboard input is ignored, including Esc. When you want to run GAUSS in
the background, use -B.
If you want to run stdin as a GAUSS program, use the -s ag. At the UNIX command
prompt, type
gauss [[lename...]] -s [[lename...]]
7
1. INSTALLATION AND OPERATION
Other programs can be run at the same time as stdin. GAUSS will start up in batch
mode, run the programs and stdin in the order listed, then drop to the system. The -s
ag forces GAUSS into the same mode as the -B ag; all keyboard input is ignored
except for Ctrl-C.
The -T and -t ags turn the translator on and o respectively, overriding the translator
setting in gauss.cfg.
The -n ag is used to execute a new command between programs to prevent any
symbol conicts if the programs use variables with the same names.
When the -M ag is on if you edit a le that contains symbols in use the le will be
recompiled.
1.9 Command Filtering
By default, when GAUSS is in terminal mode, most of the following commands are
available interactively at any time, even during compilation or execution of a GAUSS
program:
cancel cancel any pending commands
stop stop the current program politely
Esc, Esc! stop the current program politely
kill terminate current program immediately
quit terminate GAUSS and return to the OS
status list status, current command, pending commands
translator on[o turn data loop translator on or o
cong set compile-time and run-time options
help on-line help
dos exec a command shell
[[editor alias]] exec an editor (see gauss.cfg)
!! repeat previous command
debug run program under debugger
This is done by ltering them out of the keyboard input stream and handling them
immediately, rather than putting them in the compiler command queue. This can give
you unexpected results, e.g., if you type status as the input to a cons statement.
This ltering can be turned o during program execution. You can specify the default
command ltering mode for all GAUSS sessions by setting the cmd lter parameter in
the conguration le, or use the cong command (run options) to set the default
ltering mode for a single GAUSS session. You can also use the #lteron and
#ltero compiler directives to set the command ltering mode for a single program
run. #lteron and #ltero must be placed at the top of your program.
stop and dos can be used in GAUSS programs; the rest of the commands can only be
used interactively.
8
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
1.10 Running Programs Written for the PC
In general, you should be able to run GAUSS programs that were originally written for
the PC without any problems. The main limitations relate to the advanced hardware
control commands.
The coprocessor control commandsenable, disable, etc.are not available. All
coprocessor exceptions are currently masked.
The ags for the lib command are specied with a dash () instead of a slash (/).
For example:
lib gauss -n;
This is because the slash is a separator in UNIX le specications.
The new command cannot change the main program space size or the number of global
symbols available. These settings can be specied in gauss.cfg.
If youre working in a GAUSS X window, keyboard input works the same as on PCs.
If youre working in terminal mode, however, it doesnt. Because of the way the system
buers input, GAUSS doesnt see any keyboard input until you hit Enter. So, if you
are using the key command for single key input, you will have to enter
keystroke enter
If you are using cons or the key command for multiple key input, you can type in your
entire input, then hit Enter, and it will all be available to GAUSS.
If you want to input a carriage return, press Enter when there is no pending input, and
GAUSS will recognize it as input.
Programs written for the PC are generally written with an 80-character wide screen in
mind. So, if youre running under an X window manager, you should size your windows
to at least 80 columns to guarantee that your program output doesnt wrap.
1.11 atog
atog for UNIX has no interactive mode, and can only be run from within GAUSS by
using the shell command, i.e., shell atog. Execute atog without command line
arguments for a help screen. For general instructions on using atog, see the Utility:
atog chapter in Volume I.
9
1. INSTALLATION AND OPERATION
1.12 File Handling
Files are created with the following permissions:
Owner read/write
Group read
World read
This can be controlled from gauss.cfg.
1.12.1 Data Sets, Matrix Files and String Files
There are new formats available for data sets, matrix les and string les. See the File
I/O chapter in Volume I of the manual.
Data sets now consist of one le with a .dat extension, not two les with .dht and
.dat extensions.
The header has changed for matrix and string lesotherwise, theyre the same as
before.
We have a new utility, transdat, for converting these les from one format to another.
If you have data sets, matrix les or string les you want to transfer from your PC to
the workstation, you can use transdat to convert them. transdat must be run from the
UNIX prompt. Execute transdat with no arguments for a help screen. See G for details.
1.13 Cache Size
There is a line for cache size in the conguration le. Set it to the size of the CPU data
cache for your machine. The default is 32K.
This aects the choice of algorithms used for certain math functions. This can
dramatically aect performance for large matrices. Results will be the same.
1.14 Graphics Conguration File
The name and format of the graphics conguration le have been changed. The le is
now called .gaussrc instead of pqgrun.cfg; formatwise, it is a standard X Windows
resource le. GAUSS searches for .gaussrc in the following directories, in the order
listed:
10
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
1. The directory specied by GAUSS CFG, if it is dened
2. The users home directory
3. The $GAUSSHOME directory
4. The current working directory
The rst one found is used. If none is found, GAUSS creates a default .gaussrc (using
internal defaults) in the users home directory.
The following resources can be included in .gaussrc:
Resource
gauss.pqg.print.margin.left
gauss.pqg.print.margin.right
gauss.pqg.print.margin.top
gauss.pqg.print.margin.bottom
Denition Left/right/top/bottom print margin.
Options Any nonnegative decimal value. Interpreted as inches.
Default 1.00"
Resource
gauss.pqg.print.resolution
Denition Print resolution.
Options MinRes, LoRes, HighRes, MaxRes
Default MaxRes
Resource
gauss.pqg.print.filename
Denition Output lename when printing to le or converting graph.
Options String, any valid lename. File must be writeable.
Default none
Resource
gauss.pqg.print.placement
11
1. INSTALLATION AND OPERATION
Denition Placement of graph within margins. Aects xed aspect graphs only.
Options TopLeft, Top, TopRight, Left, Center, Right, BotLeft, Bottom, BotRight
Default Center
Resource
gauss.pqg.print.orientation
Denition Orientation of graph on page.
Options Landscape, Portrait
Default Landscape
Resource
gauss.pqg.print.dest
Denition Destination of graphics printout.
Options Printer, File
Default Printer
Resource
gauss.pqg.print.aspect
Denition Aspect ratio of printed graph. Fixed aspect graphs are printed within the
limits dened by the margins, whereas variable aspect graphs are stretched
to t the margins.
Options Fixed, Variable
Default Fixed
Resource
gauss.pqg.print.driver
Denition Driver used to convert graph to format suitable for your printer.
Options PS, EPS, HPLJET3, HPGL, PIC
The le prndev.tbl in the $GAUSSHOME directory lists additional
printer/le types that are available but not tested. You can try any of the
types listed there except the type 4 entries (i.e., those with a 4 in the
second eld), which are NOT supported.
12
I
n
s
t
a
l
l
a
t
i
o
n

a
n
d

O
p
e
r
a
t
i
o
n
1. INSTALLATION AND OPERATION
Default PS
Resource
gauss.pqg.print.command
Denition Command that will be executed to print a graph.
Options String, any valid print command.
Default lp -c $FILE
Resource
gauss.pqg.print.color
Denition Print color mode: black/white, color, or gray scale.
Options BW, RGB, Gray
Default BW
Resource
hpgl.pen.black
hpgl.pen.dark_grey
hpgl.pen.red
hpgl.pen.light_red
hpgl.pen.brown
hpgl.pen.light_brown
hpgl.pen.green
hpgl.pen.light_green
hpgl.pen.cyan
hpgl.pen.light_cyan
hpgl.pen.blue
hpgl.pen.light_blue
hpgl.pen.magenta
hpgl.pen.light_magenta
hpgl.pen.grey
hpgl.pen.white
Denition Pen color for HPGL-format output.
Options Integer, any valid pen number.
Default
13
1. INSTALLATION AND OPERATION
hpgl.pen.black 1
hpgl.pen.dark grey 1
hpgl.pen.red 5
hpgl.pen.light red 5
hpgl.pen.brown 7
hpgl.pen.light brown 7
hpgl.pen.green 3
hpgl.pen. 3
hpgl.pen.cyan 4
hpgl.pen.light cyan 4
hpgl.pen.blue 2
hpgl.pen.light blue 2
hpgl.pen.magenta 6
hpgl.pen.light magenta 6
hpgl.pen.grey 8
hpgl.pen.white 8
You may also see the following entries in .gaussrc:
gauss.pqg.print.size: 100%
gauss.pqg.print.scaling: ByPage
These are reserved for future development.
The WinPrintPQG command now works. Also, its functionality has been expanded to
include that of WinConvertPQG, and WinConvertPQG has been dropped. See the
on-line help for details on how to use WinPrintPQGit has a dierent syntax now.
You can now zoom multiple times in a graph.
Default Fonts
You can specify default normal and bold fonts for GAUSS to use in Text and TTY
windows by including gauss.font.normal and gauss.font.bold resources in the
.gaussrc le. Set them to any valid nonproportional font specication string.
14
T
u
t
o
r
i
a
l
Chapter 2
Tutorial
This tutorial will introduce you to the basics of GAUSS.
2.1 Loading and Exiting GAUSS
This lesson covers starting, stopping and suspending GAUSS.
2.1.1 Starting GAUSS
From the OS (operating system) prompt there are two ways to start GAUSS. The rst:
gauss &
will start up GAUSS in an X window. The second:
gauss -v
will start GAUSS in text mode in your current terminal.
2.1.2 Exiting GAUSS
To exit GAUSS when in X window mode, click on the Quit button. To exit GAUSS in
terminal mode, at the (gauss) prompt type:
quit
15
2. TUTORIAL
2.2 Matrices
This lesson covers the basic commands that create matrices.
2.2.1 The let Statement
Type this in and press Enter:
let x = { 1 2 3, 4 5 6, 7 8 9 };
You just created a 3x3 matrix called x. To print it out type:
print x;
Try it again without the let.
x = { 1 2 3, 4 5 6, 7 8 9 };
An assignment statement with the data enclosed in curly braces is an implicit let
statement. let statements are run-time initialization statements. Only a list of
constants is allowed to the right of the equal sign in a let statement.
Now lets create a column vector and print it out.
x = { 1,2,3,4,5,6,7,8,9 };
print x;
Now a row vector.
x = { 1 2 3 4 };
print x;
The constants in a let statement can be real or complex. Try the following:
x = { 1 2+3 4 5-6i 7 8i };
print x;
Complex constants can be entered in one of two ways. If a number has both a real and
an imaginary part, just join the two with the sign (+ or -). If a number has no real
part, append an i to it, and GAUSS will recognize it as imaginary. Notice that the
i can be appended even if the number has a real part.
16
T
u
t
o
r
i
a
l
2. TUTORIAL
2.2.2 Concatenation
The concatenation operators are used to create matrices from other matrices or from
expressions. Enter:
a = { 1.1 3.2 };
b = { 2.3 -4.5 };
Now try these statements:
hc = a~b;
print hc;
hcp = a+1~b+2;
print hcp;
vc = a|b;
print vc;
The is the horizontal concatenation operator, and the | is the vertical concatenation
operator.
2.2.3 Special Matrix Functions
To create a matrix of zeros or ones, or random numbers, try the following statements.
Zeros
x = zeros(4,4);
print x;
Ones
y = ones(2,4);
print y;
Uniform Random Numbers
z = rndu(6,3);
print z;
17
2. TUTORIAL
Normal Random Numbers
z = rndn(6,3);
print z;
Random Integers
rndint = ceil( rndu(6,4) * 100 );
print rndint;
Constant Matrix
To create a constant matrix, all you need to do is add the desired constant to a matrix
of zeros. For example, to create a 6x3 matrix of 7s, this statement will work:
sevens = 7 + zeros(6,3);
print sevens;
Identity Matrix
id = eye(3);
print id;
Additive Sequence
t1 = seqa(0,0.1,10);
print t1;
t2 = seqa(pi/4,pi/4,4);
print t2;
Multiplicative Sequence
t1 = seqm(2,2,10);
print t1;
18
T
u
t
o
r
i
a
l
2. TUTORIAL
Reshaping Matrices
x = seqa(1,1,3);
y = reshape(x,5,3);
print x;
print y;
2.2.4 Keyboard Input
The con function requests keyboard input of a matrix. Type this in.
x = con(3,3);
The ? is your prompt. The con function is requesting 9 numbers. Type in 9 numbers,
each followed by a space.
Are you back at the (gauss) prompt? If so, print your new matrix x.
The con function can accept complex numbers. It uses the same rules for entering
complex numbers as the let statement. Try entering some.
x = con(2,2);
print x;
Notice that the con function, like the let statement, only understands constants.
2.3 Strings
We will cover two ways to create a string.
2.3.1 String Constant
s = "This is a string.";
The double quotes enclose a string constant. Printing a string is like printing a matrix.
Try it.
19
2. TUTORIAL
2.3.2 Keyboard Input
The cons function requests keyboard input of a string. Type this in.
s = cons;
There is no visible prompt. Type something in and press Enter.
You should be back to the GAUSS prompt. Print s.
Now lets do it with a prompt so we can tell when we are being asked to type
something in.
print /flush "Enter the string: ";; s = cons;
Enter another string, then print s. The double semicolons at the end of the print
statement suppressed a line feed afterward so the cons statement would start requesting
input on the same line. The /ush ag forces immediate display of the prompt.
2.3.3 String Concatenation
Lets tack two strings together. Type this in.
s = s $+ "catfish";
print s;
The $+ is the string addition or concatenation operator.
2.4 Matrix Description and Printing
This is a short section on using some of the functions that describe matrices. You will
learn how to nd the number of rows and columns in a matrix and nd the largest and
smallest elements in a particular column or in the entire matrix. Also, you will be
introduced to some more features of the print statement.
To nd the number of rows and columns in a matrix, use the rows and cols functions.
Type in the following statements:
x = rndu(10,4);
r = rows(x);
c = cols(x);
print "Matrix x is: " r " by " c;
20
T
u
t
o
r
i
a
l
2. TUTORIAL
The print statement could have been written:
print "Matrix x is :" rows(x) " by " cols(x);
To nd the maximum and minimum elements of each column of a matrix, use the maxc
and minc functions. Try this:
print x;
print maxc(x);
print minc(x);
To nd the largest or smallest element in an entire matrix, call maxc and minc twice:
print "Maximum is: " maxc(maxc(x));
print "Minimum is: " minc(minc(x));
2.4.1 The print Statement
In entering the statement
print "Matrix x is: " r " by " c;
you probably noticed that the statement combined the printing of string constants (the
phrases between double quotes) and variables (r and c). GAUSS uses a space to
separate the individual expressions in a print statement. Therefore, extraneous spaces
are illegal in print statements. Try:
print 3 + 5;
The error you will get is:
(0) : error G0064 : Operand missing
GAUSS translated that as three expressions. The middle expression was the addition
operator with no operands. There are two ways to write the above statement correctly:
1. No extraneous spaces.
print 3+5;
2. Parentheses.
print (3 + 5);
21
2. TUTORIAL
2.4.2 The format Statement
If you are still using the default print format, then the statements:
print "Rows: " r;
print "Cols: " c;
print the number of rows and columns with 8 digits of precision.
Create a variable containing an integer value.
x = 5;
To change the print format, enter the following format statement:
format /rdn 1,0;
The /rdn ag indicates that numbers are right-justied in decimal format followed by
nothing. The 1 sets the eld width, which will be overridden if the number requires
more space, and the 0 sets the precision or number of places to the right of the decimal
point. This format statement is suitable for printing integers.
print "(" x ")";
Lets leave out the n and see what happens, type:
format /rd 1,0;
The /rd ag indicates that numbers are right-justied in decimal format followed by a
space, which is the default.
print "(" x ")";
As you can see, the number is now followed by a single space character. Try another
format and print x again.
format /len 12,4;
Any numbers printed after this format statement will be left-justied using scientic
notation in a 12-character eld followed by nothing with 4 decimal places of precision.
Type in the following:
22
T
u
t
o
r
i
a
l
2. TUTORIAL
let x = 1+2 3-4;
format /rds 4,2;
print x;
For complex numbers, the eld and precision settings refer to the eld width and
precision for each part of the number. Also, when the number is printed, the real and
imaginary parts are separated by a sign ( + or - ), and an i is appended to the
imaginary part. You will need to gure this in when you want to print complex
numbers in a nice format.
Lets change x a bit.
let x = { 1+2 3-4, 5 6i };
print x;
When the imaginary part of a complex number is 0, it is not printed at all. We do,
however, pad the place where the 0 would appear with spaces, to keep the rest of the
printout aligned.
Now reset the format to one more like the default format.
format /ro 12,4;
2.5 Indexing Matrices and Extracting Submatrices
This section describes how to index individual elements of a matrix and extract
submatrices of a matrix. First clear your workspace of all previously dened globals.
To do this, enter
new;
Now create a matrix using seqa and reshape:
x = reshape( seqa(1,1,32), 8, 4 );
print x;
2.5.1 Indexing
Now, lets extract the rst and third columns of x:
col1 = x[.,1];
print col1;
23
2. TUTORIAL
col3 = x[.,3];
print col3;
Now, extract a row, whose index might be variable:
i = 2;
row = x[i,.];
print row;
Now, index a set of rows. I will leave out the print statements from here on, except
when necessary. You can print whatever you want to take a look at.
idx = { 1 3 6 8 };
ridx = x[idx,.];
Finally, index a set of rows and columns:
rowidx = { 1 3 5 8 };
colidx = { 3 4 };
newmat = x[rowidx,colidx];
The matrix newmat consists of the intersection of rows 1, 3, 5, and 8 and columns 3
and 4.
newmat = x[1 3:6,2:4]
The matrix newmat now consists of the intersection of rows 1, 3-6 and columns 2-4.
The submat function can also be used to extract submatrices.
r = { 1 3 5 };
c = { 3 4 };
newmat = submat(x,r,c);
This will index rows 1, 3 and 5 and columns 3 and 4.
2.5.2 Using delif and selif
You may want to create a submatrix based on some selection or deletion criteria. This
section will show you one way to do this, using the selif and delif functions.
First, create a matrix of normally distributed random numbers:
y = rndn(100,4);
24
T
u
t
o
r
i
a
l
2. TUTORIAL
Now we will create a new matrix, which contains only those rows of y where column 2
is greater than 0.5. To do this, we will create a vector of 1s and 0s that has a 1 in each
row we want to select.
ex = y[.,2] .> 0.5;
print ex;
The vector ex should have a 1 wherever the corresponding entry in the second column
of y is greater than 0.5. The expression y1[.,2] .> 0.5 uses a dot operator which
returns a matrix of 1s and 0s with a 1 wherever the expression is true and a 0 wherever
it is false. The result of the expression above is a vector with the same number of rows
as y. Well use such a vector of 1s and 0s in the selif and delif statements.
Now, we want to create a submatrix of the matrix y containing all the rows in which
the second column is greater than 0.5. Here is how we would use the selif function to
create this submatrix:
suby = selif(y,ex);
Print suby to see that column 2 contains only numbers greater than 0.5.
Here is another example of a logical expression that can be used with the selif function.
ex2 = abs( y[.,1] ) .< 0.33 .and y[.,2] .> 0.66;
The delif function works in a complementary fashion. Instead of selecting elements to
go in the submatrix, you delete those elements that you dont want. For example:
ex = y[.,1] .< 0.33;
v = delif(y,ex);
Of course, this would be equivalent to this set of statements which use selif:
ex = y[.,1] .>= 0.33;
v = selif(y,ex);
The logical expression may almost always be nested inside of the call to the functions
that require them. The above two statements could be combined into one statement:
v = selif(y,y[.,1] .>= 0.33);
25
2. TUTORIAL
2.6 Running a Program
Up until nowwe have been executing single line commands. Now lets write a program.
Create a le called lesson1 and type this into the new le.
A = rndn(3,3);
b = rndn(3,1);
x = b/A;
print A;
print b;
print x;
Save your le without exiting your editor and at the (gauss) prompt type:
run lesson1;
from the GAUSS prompt.
You just solved a system of linear equations. This is an example of the / (slash)
operator. It is quite powerful.
The / operator is supposed to solve the linear system
Ax = b
Lets check it from the command line. If the equation above is true, A*x-b should be
zeros.
print A*x;
print b;
print A*x-b;
Its pretty close, isnt it? There will usually be a little rounding error when doing
calculations on real numbers.
Lets try the / operator on a dierent kind of problem. Edit your program so that the
whole thing looks like this:
x = { 1 2 3,
4 5 6,
7 8 9 };
y = 2;
z = x / y;
print x;
print;
print y;
print z;
26
T
u
t
o
r
i
a
l
2. TUTORIAL
The empty print statement just prints a carriage return/line feed.
Execute your new program.
The / operator is now doing standard division. You should have gotten:
1 2 3
4 5 6
7 8 9
2
0.5 1 1.5
2 2.5 3
3.5 4 4.5
2.7 Element-by-Element Operators
Now get back into your program and change the second and third lines so the program
looks like this:
x = { 1 2 3,
4 5 6,
7 8 9 };
y = { 1 2 3 }; /* row vector */
z = x ./ y; /* dot slash operator */
print x;
print;
print y;
print z;
The /* row vector */ statement is a comment. Comments dont do anything but you
can use them to make your programs easier to understand when you come back to
them six months later.
Execute your new program. You should have gotten:
1 2 3
4 5 6
7 8 9
1 2 3
1 1 1
4 2.5 2
7 4 3
27
2. TUTORIAL
This is element-by-element division. The dot slash always does element-by-element
division. This is an example of what we refer to as element-by-element conformability.
The row vector y was swept down the matrix x and the corresponding divisions were
done.
Get back into the le.
Make it look like this:
x = { 1 2 3,
4 5 6,
7 8 9 };
y = { 1, 2, 3 }; /* column vector */
z = x ./ y; /* use dot slash */
print x;
print y;
print z;
Execute it. You will get:
1 2 3
4 5 6
7 8 9
1
2
3
1 2 3
2 2.5 3
2.333 2.667 3
Here the column vector was swept across the matrix.
Now get out of GAUSS by typing quit or clicking on the Quit button. Get back into
GAUSS and run your program at the same time by typing either:
gauss lesson1
or
gauss -v lesson1
Lets make one nal change to your le. Add two lines to the program so it looks like:
28
T
u
t
o
r
i
a
l
2. TUTORIAL
x = { 1 2 3,
4 5 6,
7 8 9 };
x = complex(x,1); /* create complex matrix */
y = { 1, 2, 3 }; /* column vector */
y = complex(y,1); /* create complex matrix */
z = x ./ y; /* use dot slash */
format /rz 4,2; /* suitable format for x, y and z */
print x;
print y;
print z;
Run the program. The output should look like this:
1 + 1i 2 + 1i 3 + 1i
4 + 1i 5 + 1i 6 + 1i
7 + 1i 8 + 1i 9 + 1i
1 + 1i
2 + 1i
3 + 1i
1 1.5 0.5i 2 1i
1.8 0.4i 2.2 0.6i 2.6 0.8i
2.2 0.4i 2.5 0.5i 2.8 0.6i
This is an example of element-by-element complex division. Try using the .*
element-by-element multiplication operator to check the answer you just got. You can
do this from the command line.
a = z .* y;
print a;
a equals x (except for a little round-o error). Can you gure out why x ./ z doesnt
equal y?
2.8 Creating a Data Set
We will now create a small data set.
29
2. TUTORIAL
2.8.1 Reading an ASCII File
First we will create a small ASCII data le. In your editor create a le named rawdata.
Type in the following numbers.
1 3 2 1
3 2 7 4
9 2 6 3
5 1 2 7
4 8 5 2
1 7 5 7
Save rawdata. We can now load rawdata into a matrix.
load x[6,4] = rawdata;
print x;
This is the quick and dirty way to use load for small ASCII les. See load in the
COMMAND REFERENCE section for a way to use it that has more error checking.
See the Utility: atog chapter in Volume I of the manual for converting larger les.
To create a small GAUSS data set from the matrix x, we will use saved.
call saved(x,"mydata",0);
This statement created a data set called mydata.dat. Check to see if it was created.
If the third argument to saved is 0, the names for the columns of the data set will all
start with X. People using GAUSS for statistical analysis will use these for the names
of their variables. Each row of the data set is then a case or observation.
We can now get some statistics on this data set.
call dstat("mydata",0); call ols("mydata",0,0);
If you want to see what the arguments to the ols or dstat procedures mean, click on the
Help button or type help at the GAUSS prompt. You will be asked for the topic you
want help on. Answer with ols or dstat. Press the capitalized letter of the desired
option to page up and down, etc., in the le. Type q enter to exit the help system.
This on-line help is available for your own functions. Lets make one.
30
T
u
t
o
r
i
a
l
2. TUTORIAL
2.9 Writing a Procedure
Create a le named sumd.src in your text editor.
We will create a procedure that sums the columns of a data set and returns a vector of
the sums. We will go a line or two at a time and I will explain each statement.
proc sumd(name);
This is the beginning of a procedure denition. This is a user-dened function. It will
return 1 item. That is the default. It will take one argument which will be the name of
the data set.
local fp,sum;
These variables, fp and sum, are local variables. They only exist while this procedure is
being called.
open fp = ^name;
The open command opens a le. The argument, name, will be a string variable. The
other variable, fp, is going to be used as a le handle. Most le-related functions in
GAUSS take a le handle to identify which le you want to work on. The ^ (caret)
operator in the context of the open statement means that what follows is a string
variable and we need the contents of it.
if fp == -1;
errorlog "Cant open the file";
end;
endif;
The comparison operator is == instead of just one equal sign. We are testing to see if
the le handle is a -1 because the open command will set it to -1 if it cant open the
le. errorlog prints an error message to the screen and the error log le. If the le
cannot be opened, the program will end.
sum = 0;
We need to zero out the variable to contain the sums.
do until eof(fp);
We are going to start a loop. We will keep doing this loop until we get to the end of the
le.
31
2. TUTORIAL
sum = sum + sumc(readr(fp,50));
This line calls readr which will read 50 rows from the data set we opened under the
handle fp. The result of this read is passed to sumc which will return the sums of each
column. These sums are added to sum on each iteration of the loop. If there arent 50
rows left, then readr will read however many there are.
endo;
This is the end of the loop.
fp = close(fp);
Now we close the le, again using the le handle.
retp(sum);
The retp statement is used to return from the procedure. The vector of column sums is
returned.
endp;
The endp statement is the close of the procedure denition. Here is our complete
procedure.
proc sumd(name);
local fp,sum;
open fp = ^name;
if fp == -1;
errorlog "Cant open the file";
end;
endif;
sum = 0;
do until eof(fp);
sum = sum + sumc(readr(fp,50));
endo;
fp = close(fp);
retp(sum);
endp;
Save the procedure without exiting your editor as before.
We need to do one more thing to make this procedure available to GAUSS. Type this
in at the GAUSS command prompt:
32
T
u
t
o
r
i
a
l
2. TUTORIAL
lib user sumd.src
This adds a listing for all procedures and global variables in sumd.src (theres only
one) to the default library user.lcg. Now GAUSS knows where to nd the procedure
sumd when you call it.
sumd is also available to the help system. Click on Help (in terminal mode, type help
at the GAUSS prompt) and answer sumd at the help prompt.
This is how to get on-line help for your own functions. If you put a comment at the top
which explains what it is used for, your sumd procedure will be complete. Ill leave
that for you to do later if you think sumd would be a useful function to have around. If
not, you can delete the entry for it from the user library. For now, lets try to use it on
our data set. Type q enter to exit the help system.
sum = sumd("mydata");
print sum;
Since this returns a column vector, if you want the sum of the entire data set you could
use:
sum = sumc(sumd("mydata"));
print sum;
These procedures work just like any other function. This makes the GAUSS language
easy to extend to accommodate the routines specic to your profession.
2.10 Vectorizing for Speed
In this lesson, we will introduce you to the looping statements, and then discuss when
loops should and should not be used in GAUSS.
First, in your editor create a le called lesson2. Now type in the following program.
x = 1;
do until x+1 == 1;
eps = x;
x = x/2;
endo;
format /rz 1,8;
print "Machine epsilon: " eps;
33
2. TUTORIAL
This program nds the smallest number eps such that
eps +1 > 1
Now suppose you want to recode a vector, based on which elements fall into specic
categories.
Create a le called lesson3.
Next, create the vector you might want to recode:
r = 20;
v = ceil(100*rndu(r,1))/10;
Now, suppose you want to assign to a new vector, v1, a 1 if the corresponding element
in v is less than 3, a 2 if the corresponding element in v is between 3 and 7, and a 3
otherwise. You could do so with this loop:
v1 = zeros(r,1);
i = 1;
do until i > r;
if v[i] < 3;
v1[i] = 1;
elseif v[i] > 7;
v1[i] = 3;
else;
v1[i] = 2;
endif;
i = i + 1;
endo;
format /rd 8,1;
print v~v1;
This program illustrates the use of the do loop and the if statement for conditional
branching. Also, notice that in order to index into the vector v1, we had to rst
initialize it. In this program, we initialized it as a vector of zeros.
This isnt a particularly ecient way to accomplish the desired task, however. Tasks
like these can be vectorized. This one in particular can be written in one line, using
logical expressions.
Get back into the program. Now add the following statement to your program:
v2 = (v .< 3) +
( 3 .<= v .and v .<= 7 ) * 2 +
(v .> 7) * 3;
34
T
u
t
o
r
i
a
l
2. TUTORIAL
Remember that the dot operators create a vector or matrix of 1s and 0s.
Execute this program. Now, in the command line, we can check to make sure that v1
and v2 are identical. From the command line, type:
maxc(abs(v1-v2));
This will return the maximum dierence between any of the corresponding elements in
v1 and v2. This dierence should be 0.
Finally, lets time the dierent procedures for recoding our vector v. To time a segment
of code, well use the hsec function. Here is how you can time a segment of code:
et = hsec; /* Start timer */
/* Segment of code to be timed here */
et = (hsec - et)/100; /* Stop timer, convert to seconds */
The function hsec uses your computers clock to return the hundredths of seconds that
have passed since midnight. Add timer statements and change the value of r to 1000 at
the top of your program, so that lesson3 looks like:
r = 1000;
v = ceil(100*rndu(r,1))/10;
et1 = hsec;
v1 = zeros(r,1);
i = 1;
do until i > r;
if v[i] < 3;
v1[i] = 1;
elseif v[i] > 7;
v1[i] = 3;
else;
v1[i] = 2;
endif;
i = i + 1;
endo;
et1 = (hsec - et1)/100;
et2 = hsec;
v2 = (v .< 3) +
( 3 .<= v .and v .<= 7 ) * 2 +
(v .> 7) * 3;
et2 = (hsec - et2)/100;
35
2. TUTORIAL
format /rd 6,2;
print "Loop: " et1;
print "Vectorized: " et2;
print "Ratio L/V: " et1/et2;
The vectorized process should be over 10 times as fast as the loop. In general, any time
you can vectorize a process, do so. The vectorized process will usually be substantially
faster.
Another function you can use to recode data in the way we did above is subscat. See
the COMMAND REFERENCE for details on using this function.
36
W
i
n
d
o
w
s
Chapter 3
Windows
The current release of GAUSS for UNIX includes a simple programming interface to
Version 11 of the X Window System. It provides a wide variety of new window support
functions, allowing you to easily develop X Window compatible GAUSS programs.
Also, many previously existing commands have been modied to work within the new
window system.
Three types of GAUSS windows are currently supported:
PQG Windows - graphics windows for display of Publication Quality Graphics
Text Windows - text I/O windows with xed-sized rectangular buers
TTY Windows - text I/O windows with scrolling output history logs
These window types share certain common properties (each can be opened, closed,
moved, resized, panned, cleared, and refreshed), but they dier greatly in purpose and
functionality. (Many of the new GAUSS window functions are dened for a specic
window type only, and will generate errors if passed the handle of an incorrect window
type.)
This chapter is divided into ve sections. The rst section contains an overview of
general window operations. In the next three sections, each window type is examined in
more detail. Section ve describes the command and help windows, and the concept of
the active window and its role in GAUSS window programs.
3.1 General Window Operations
The following operations are basic window control functions, and can be done on any
window type. The details of the function calls vary by window type. The most
37
3. WINDOWS
recognizable dierence being that arguments for PQG windows are usually given in
pixels, while arguments for Text and TTY windows are usually given in rows and
columns. Several operations refer to the special purpose windows; see Section 3.5 for
denitions of those.
3.1.1 Opening a Window
WinOpenPQG opens (creates) a PQG window, WinOpenText opens a Text window,
WinOpenTTY opens a TTY window. See Sections 3.2.1, 3.3.1 and 3.4.1 for
information on window attributes and defaults.
3.1.2 Moving a Window
WinMove repositions a window on the screen. You can move a window partially or
completely o-screen. Arguments are in pixels. Nonintegral arguments are truncated.
3.1.3 Resizing a Window
WinResize resizes a window. There are no limits for sizing PQG windows or TTY
windows, but Text windows are limited by the size of their text buer. You can resize a
Text window smaller than its buer, but not larger. For PQG windows, arguments are
in pixels; for Text windows and TTY windows, arguments are in rows and columns.
Nonintegral arguments are truncated.
You can specify a window as nonresizeable when you open it. WinResize will return a
failure code on a nonresizeable window.
3.1.4 Panning a Window
WinPan pans through the contents of a window. For PQG windows, arguments are in
pixels; for Text and TTY windows, arguments are in rows and columns. Nonintegral
arguments are truncated.
WinPan is not supported for PQG windows.
For Text windows, panning is limited by the buer boundaries.
For TTY windows, you cannot pan above the rst line or to the left of the rst column.
You can pan the current output line to the top of the window (this is how cls and
WinClear clear TTY windows), and you can pan to the right as far as you like.
38
W
i
n
d
o
w
s
3. WINDOWS
3.1.5 Clearing a Window
WinClear clears a specied window, cls clears the active window. Windows are cleared
to the background color. For PQG windows, the graphics le is truncated to zero
length; For Text windows, the window buer is cleared; for TTY windows, the current
output line is merely panned to the top of the window. To clear the output log of a
TTY window, use WinClearTTYLog.
WinClearArea clears a specied region of a Text window to the background color.
Arguments are in rows and columns. As with Winclear, that region of the window
buer is cleared. WinClearArea is only supported for Text windows.
Closely related to WinClearArea, the scroll function allows you to scroll a region of
text in the active window. The area the text is scrolled away from is cleared to a
specied color. scroll is only supported for Text windows.
3.1.6 Closing a Window
WinClose closes (destroys) a window. WinCloseAll closes all windows except window 1
(the command window).
Closing a window does not mean iconizing it; closing a window destroys it. Once a
window is closed, there is no way to retrieve any information it contained.
3.1.7 Selecting a Font
Before using a font, it must be loaded from the system. When you are done with it you
should unload it, to conserve memory resources. FontLoad loads a font, FontUnload
unloads it.
Once a font is loaded, you have to let GAUSS know you want to use it for a particular
window. You can set the font either upon opening a window or when it is the active
window. font sets the font for the active window.
Changing the font in a window will generally result in a change in the number of rows
and columns displayed. Changing to a smaller font in a Text window can result in the
window being down-sized, since the window cannot be larger than its buer.
Setting the font of a PQG window, while not supported, will not cause an error.
3.1.8 Getting Input
The active window always has the keyboard focus in a GAUSS program. con, cons,
key, keyw, wait and waitc all get input from the active window.
39
3. WINDOWS
3.2 PQG Window
A PQG window is specically designed to display Publication Quality Graphics. Text
input and output is not supported for PQG windows.
3.2.1 Opening a PQG Window
WinOpenPQG opens a PQG window. You can specify the following on opening:
window position (pixels)
window size (text rows and columns)
colormap
foreground and background color
xed or variable aspect ratio
resizeability
Defaults are dened for each of these settings:
window position: (0,0) (upper left corner of screen)
window size: 640480
16 color colormap ( emulates PC EGA palette )
black background, white foreground
xed aspect ratio
resize by function or mouse
You can retain any or all of the default values on opening a window.
3.2.2 Selecting Colors
Each PQG window has an associated colormap. You can examine the colors in the
colormap with WinGetColorCells, and change them with WinSetColorCells. Out of
the colormap you can select the foreground and background colors for window output.
The foreground is the the default color of the lines, text, and other PQG output, and
the background is the color of the eld on which they are drawn. You can change the
foreground and background through the commands provided in the Publications
Quality Graphics interface.
Note: The graphics library used in Publication Quality Graphics is currently limited to
using the 16 color palette. While the appearance of the screen can be changed by the
selection of an alternate colormap, all output to the printer, and all le conversions are
treated as if the active colormap is 16 color.
40
W
i
n
d
o
w
s
3. WINDOWS
3.2.3 Aspect Ratio
PQG windows may be opened with either a xed or variable aspect ratio. For windows
opened with xed aspect ratio, both resizing and zooming are aected. The system
forces one dimension of the window or zoom box to change by an amount proportional
to any change in the other dimension. For the zoom feature, the X size of the zoom box
determines the Y size. For resizing, the window manager determines which dimension is
dominant, if any. The default for PQG windows is xed aspect ratio.
3.3 Text Window
A Text window is a text I/O window with an underlying text buer. All operations
take place with respect to the buer. A window cannot be resized larger than its buer.
3.3.1 Opening a Text Window
WinOpenText opens a Text window. You can specify the following on opening:
window location (pixels)
window size (text rows and columns)
buer size (text rows and columns)
text font
colormap
foreground and background color
text wrapping mode
refresh mode
resizeability
Defaults are dened for each of these settings:
window position: (0,0) (upper left corner of screen)
window size: 2580
buer size: 2580
system font
system colormap
system foreground and background
character wrap
refresh on newline (\n)
resize by function or mouse
You can retain any or all of the default values on opening a window.
41
3. WINDOWS
3.3.2 Selecting Colors
Each Text window has an associated colormap. You can examine the colors in the
colormap with WinGetColorCells, and change them with WinSetColorCells. Out of
the colormap you can select the foreground and background colors for Text window
output. The foreground is the color of the text itself, and the background is the color of
the eld on which it is printed. You can change the foreground color at any time, the
background color, however, may not be changed after the window has been opened.
The color command sets the foreground color for the active window.
3.3.3 Locating Text
Text windows give you full control over text location, allowing you to paint a screen
and set up output elds wherever you like. All text location functions operate with
respect to the window buer, NOT the current window appearance. Thus, you may
locate and print text in an area that is not currently visible.
WinSetCursor sets the cursor position in a specied window. locate sets the cursor
position in the active window. tab sets the cursor position on the current line of the
active window. You can tab forward and backward. You can also embed tab commands
within a print statement.
When you locate and print in a region that already has text, the existing text is
overwritten.
Nonintegral arguments to the text location functions are truncated; for example,
locate 13.25, 40.75;
is equivalent to:
locate 13, 40;
It is not necessary for location arguments to be located within the window buer. For
example,
locate 1,-5;
is allowed. You can think of the buer as covering a small region in text coordinate
space; text written within the buer bounds is remembered, text written outside it is
lost.
42
W
i
n
d
o
w
s
3. WINDOWS
3.3.4 Wrapping Text
Three text wrapping modes are supported:
word wrapping
character wrapping
clipping
Word wrapping: Lines are wrapped between words. A line wrap on the last row of the
buer forces an auto-scroll of the buer contents. Outputting a newline (\n) on the
last row also forces an auto-scroll.
Character wrapping: Lines are wrapped between characters. Auto-scrolling is the same
as for word wrapping.
Clipping: Lines are clipped at the buer edge. No auto-scrolling takes place, not even
when a newline (\n) is output to the last row of the buer. If you want to scroll the
contents of the buer, you must do it explicitly with the scroll command.
Again, all output commands in a Text window operate with respect to the buer, not
the window. So, in clipping mode, any text that goes beyond the width of the buer is
discarded and cannot be retrieved. Likewise, any time text is scrolled o the top of the
buer, it is permanently discarded.
3.4 TTY Window
A TTY window is a text I/O window that logs output for a user-specied number of
lines. Each line of output is saved in its entirety, and the window size, text wrap mode,
etc., merely determine how the output is displayed. The only time you lose information
in a TTY window is when you reach the output log limit and lines begin to scroll o
the top of the output log.
TTY windows have color support for foreground only. The color commands will run in
a TTY window, however, they will only eect the foreground color.
There are no sizing limits for TTY windows.
3.4.1 Opening a TTY Window
WinOpenTTY opens a TTY window. You can specify the following on opening:
43
3. WINDOWS
window location (pixels)
window size (text rows and columns)
output log size (number of lines)
text font
colormap
foreground and background color
text wrapping mode
refresh mode
resizeability
Defaults are dened for each of these settings:
window position: (0,0) (upper left corner of screen)
window size: 2580
output log size: 500 lines
system font
system colormap
system foreground and background
character wrap
refresh on newline (\n)
resize by function or mouse
You can retain any or all of the default values on opening a window.
3.4.2 Locating Text
TTY windows have minimal text location support. You can use tab and locate to tab
the cursor forward and backward in the active window, or WinSetCursor to tab the
cursor in a specied window. For locate and WinSetCursor, the row argument is
ignored.
When you tab backward and then print, the existing text is overwritten.
The tabbing commands operate with respect to the length of the current output line,
not the window appearance. This becomes signicant when a line gets longer than the
window width, and wraps. For example, if a window is 80 columns wide and the output
line is 90 columns wide, and you tab to column 85, the cursor will appear to be in
column 5. If you then widen the window to 100 columns, the output line will unwrap
and the cursor will appear where you expect it, in column 85.
44
W
i
n
d
o
w
s
3. WINDOWS
3.4.3 Wrapping Text
Three text wrapping modes are supported:
word wrapping
character wrapping
clipping
Word wrapping: Lines are wrapped between words. A line wrap on the last row of the
window forces an auto-scroll of the buer contents. Outputting a newline (\n) on the
last row also forces an auto-scroll.
Character wrapping: Lines are wrapped between characters. Auto-scrolling is the same
as for word wrapping.
Clipping: Lines are clipped at the window edge. Auto-scrolling takes place only when a
newline (\n) is output to the last row of the window. (Note the dierence between this
and a clipped Text window, which never auto-scrolls.)
The text wrap mode in a TTY window denes how output is displayed in the window;
it has nothing to do with how output is stored, as is the case in a Text window. So, the
word and character wrapping modes specify that each line of output should be
completely displayed within the window boundaries; nothing is hidden o-screen
(until it scrolls o the top of the window). If you resize the window, the entire display
will change as output is rewrapped accordingly. Likewise, clipping mode species that
the portions of a line beyond the edges of the window should be clipped from the
display, but nothing discarded. If you widen the window, you will see more of the text.
A nal note about auto-scrolling: if the current output line has been panned below the
bottom edge of the window, additional output will not scroll the window contents. The
output is still added to the output log; it just doesnt aect the display. This allows you
to study previous text during ongoing output. Pan the output line back within view,
and normal window updating and auto-scrolling will resume.
3.5 Special Purpose Windows
GAUSS recognizes three special purpose windows: the command window, the help
window, and the active window.
45
3. WINDOWS
3.5.1 Command Window
The command window ( window 1 ) is the main window used for controlling GAUSS.
It contains both the control buttons, and a TTY text pane for running GAUSS
interactively. ( If GAUSS is running in terminal mode, the system terminal window is
the command window. ) Since the window handle for the command window is 1, the
command window is sometimes referred to as window 1.
The top of the command window contains buttons which are used to control a GAUSS
session. (These replace the main interactive control commands used in the DOS
version.) The following buttons appear in window 1:
Help toggle GAUSS help system on/o
Status display program status, processes executing
Cong display/modify Compile and Run options
Trans toggle le translation on/o
Cancel cancel any commands pending in the command buer
Stop stop the currently executing progam
Kill terminate child processes
Quit quit GAUSS and exit to system.
The text pane portion of the command window is a standard TTY window. Most of
the GAUSS commands which are valid for user dened TTY windows are also valid for
the command window. To execute a GAUSS function on the command window, simply
set the window handle parameter of the command to 1. There are some functions
which are not dened for the command window, such as WinClose, and
WinSetRefresh. These are documented in the Command Reference. The command !!
may be used to repeat the last typed command.
3.5.2 Help Window
The help window is the window used for displaying output from the interactive help
system. The Help button on the command window toggles the help window on and o.
The help system is available at any time during a GAUSS session, with output directed
to a dedicated TTY window. The window handle for the help window is 2. ( If GAUSS
is running in terminal mode, the system terminal window is the help window. )
Most of the GAUSS commands which are valid for user dened TTY windows are also
valid for the help window. To execute a GAUSS function on the help window, simply
set the window handle parameter of the command to 2. There are some functions such
as WinClose and WinSetRefresh which are either not dened for the help window, or
which operate dierently on the help window. These are documented in the Command
Reference.
46
W
i
n
d
o
w
s
3. WINDOWS
3.5.3 Active Window
The active window refers to the default I/O window. All the input functions (con,
cons, key, keyw, wait and waitc) get their input from the active window, and all the
output and output-related commands that do not take a window handle as an
argument (locate, output, print, scroll, tab, etc.) operate on the active window. In
addition, certain functions that set window or output attributes (color, font, etc.)
operate on the active window.
WinSetActive and WinGetActive set and get the active window. Any window can be
the active window, and you can change the active window whenever you want. Many
windows can be visible simultaneously, but there is only one active window.
When you rst start GAUSS, the command window (window 1) is the active window.
It is possible not to have an active window; you can remove the active window by
unsetting it with WinSetActive or closing it with WinClose. If there is no active
window, the commands that operate on it will still runthey just wont have any eect
(for example, the output of a print statement will simply not be displayed anywhere).
If there is no active window when a GAUSS program ends, the command window
automatically becomes the active window.
Note: If you set the active window to a PQG window, no character I/O will be
processed.
47
3. WINDOWS
48
D
e
b
u
g
g
e
r
Chapter 4
Debugger
GAUSS for UNIX includes a source level debugger which executes a program one line
or opcode at a time, enabling the user to examine and modify program variables during
execution.
The debugger is a dynamically linked X Window application. The X libraries must be
available on the system when it is invoked.
4.1 Starting the Debugger
To start the debugger, enter:
debug lename
at the GAUSS prompt.
The debugger initially displays two windows: the Command window, which contains
buttons used to control program ow, and the Source window, which displays the
source code to be executed. Section 4.3 describes the other windows the debugger uses.
Debugger commands are issued by clicking on the buttons in the Command window.
49
4. DEBUGGER
4.2 Commands
Next Line Execute next source line
Step Line Execute next source line, enter procedure calls
Next Opcode Execute next opcode
Step Opcode Execute next opcode, enter procedure calls
Go Execute with no tracing
Verbose Execute with opcode tracing
Brkpts On[O Toggle breakpoint checking on and o
Brkpts Set Detailed information and control of breakpoints
Examine Examine and modify variable contents
History Toggle opcode history on and o
Stack Examine and modify stack contents
Procs List procedures and set breakpoints
Quit Exit debugger
Next Line Executes the currently highlighted source line. If the current line contains
any procedure calls, they are executed (along with any procedures which they
call) before the debugger pauses for input.
Step Line Executes the currently highlighted source line. If the current line contains a
procedure call, execution pauses at the rst line within the procedure. If the line
contains more than one procedure call, execution will pause at the rst line in
each procedure (assuming you continue pressing Step Line).
Next Opcode Executes the currently highlighted opcode. If the opcode is a procedure
call, the entire procedure is executed (along with any procedures which it calls)
before the debugger pauses for input.
Step Opcode Executes the currently highlighted opcode. If the opcode is a procedure
call, execution pauses at the rst opcode within the procedure.
Go Executes the program until reaching either a breakpoint or the end of the code.
Selecting Go automatically turns o the Opcode History window.
Verbose Executes the program until reaching either a breakpoint or the end of the
code. Selecting Verbose automatically turns on the Opcode History window.
Brkpts On[O Toggles breakpoint checking on and o. When breakpoint checking is
o, the debugger ignores all breakpoints. When breakpoint checking is on, the
debugger stops at the rst active breakpoint.
A small banner is displayed in the upper right corner of the Command window
when breakpoint checking is on.
50
D
e
b
u
g
g
e
r
4. DEBUGGER
Brkpts Set Opens/closes the Breakpoint window. The Breakpoint window displays
the data for all breakpoints currently specied in the program. You can modify
breakpoint settings in this window. See Section 4.4 for details.
Examine Requests a variable name, then opens an Examine window to display it. The
window is updated after each command. It remains open until it is explicitly
closed or the variable is no longer valid. Global variables are always valid; local
variables become invalid after a retp. The debugger will allow up to 100
variables to be monitored at any given time.
History Opens/closes the Opcode History window. When open, the Opcode History
window displays and logs opcodes as they are executed. It can log up to 4096
opcodes. This window is automatically opened whenever the Next Opcode,
Step Opcode, or Verbose command is issued, and closed whenever the Go
command is issued. While immensely useful for tracking down program errors,
generating the opcode history is very output intensive and greatly increases
program execution time while active.
Stack Opens/closes the Stack window. The Stack window displays the contents of the
stack for examination and modication. The window is automatically updated
after each command.
You will only see stack activity when youre selecting Next Opcode or Step
Opcode. If youre selecting Next Line or Step Line, the stack will appear to be
always empty.
Procs Opens/closes the Procedure window. The Procedure window lists the names of
all procedures and functions found in the source code. Procedure breakpoints
can be set and cleared from this window. See Section 4.4 for details.
Quit Ends the debugging session and exits the debugger.
4.3 Windows
The debugger utilizes a variety of dierent windows to display and edit the various
types of program data and debugger settings.
Window types include:
Command Command buttons, status indicators, debugger messages
Source Currently executing source code, highlight indicates next
source line to be executed
51
4. DEBUGGER
History Opcode history, highlight indicates next opcode to be
executed
Breakpoint Lists all dened breakpoints, allows editing of breakpoints,
highlight indicates currently selected breakpoint
Stack Displays current stack contents, highlight indicates
currently selected stack element, clicking on selected
item opens Examine window
Procedure Displays the names of all procedures and functions dened
in the current program, highlight indicates currently
selected procedure name
Matrix Examine Matrix window, displays the contents of matrix,
highlight indicates currently selected element, clicking
on selected element allows modication
String Examine String window, displays the contents of string,
no highlight is displayed (strings cannot be modied)
Edit Allows text/numeric entry into the debugger, highlight
indicates current cursor position
The windows have a given default size, but can be adjusted (within limits) to whatever
size is desired. Since there is often more information available than can be displayed
within the window, the debugger supports keystroke movement of the highlight or
window contents as follows:
Up move up one element
Down move down one element
Left move left one element
Right move right one element
Shift+Up move up one window height
Shift+Down move down one window height
Shift+Left move left one window width
Shift+Right move right one window width
Ctrl+Up go to top
Ctrl+Down go to bottom
Ctrl+Left go to far left
Ctrl+Right go to far right
PageUp move up one window height
PageDown move down one window height
Ctrl+PageUp go to top
Ctrl+PageDown go to bottom
52
D
e
b
u
g
g
e
r
4. DEBUGGER
Home go to upper left
End go to lower right
Enter select item or accept changes
Esc discard changes, close window
While the denition of element may vary according to the window type, every eort
has been made to keep the keystroke actions intuitive, and there should be no confusion.
4.4 Breakpoints
The debugger supports two types of breakpoints, procedure breakpoints and line
number breakpoints. Procedure breakpoints pause execution when the specied
procedure or function is entered. Line number breakpoints pause execution when the
specied line is reached. In either case, the break occurs before any of the GAUSS code
for the procedure or line is executed.
Procedure breakpoints can be set and cleared in the Procedure window by clicking on
the desired procedure name. You can also use the cursor keys to move the highlight to
the desired procedure, then press Enter to set/clear a breakpoint.
Line number breakpoints can be set and cleared in the Source window by clicking on
the desired line.
Breakpoints can be set, cleared and modied in the Breakpoints window, which is
opened and closed by the Brkpts Set command. This window displays all the
breakpoints dened for the current debugging session. You can select a breakpoint by
clicking on it with the mouse or moving the highlight with the cursor keys. Once
selected, the breakpoint settings can be modied as follows:
1. Clicking on the ON/OFF eld toggles the state of the breakpoint. Breakpoints
which are o remain dened, but are inactive. Active breakpoints are indicated
in the Procedure and Source windows with an inverse video tag [BP], inactive
breakpoints are indicated with the tag (BP) in normal video.
2. Clicking on the Skip eld opens an Edit window, which allows the skip value to
be changed. Breakpoint checking in the debugger skips over the breakpoint the
specied number of times. For example, 0 = dont skip, 24 = skip 24 times,
break on the 25th occurence. Skip counters are reset to 0 whenever the
breakpoint causes a break. For example, a skip value of 24 on a breakpoint
within a loop from 1 to 100 will break 4 times, at i = 25, 50, 75, and 100).
Note: The Skip eld is currently only valid for line number breakpoints.
3. Clicking on the Line # eld opens an Edit window, which allows the line
number to be changed.
53
4. DEBUGGER
54
F
o
r
e
i
g
n

L
a
n
g
u
a
g
e

I
n
t
e
r
f
a
c
e
Chapter 5
Foreign Language Interface
The Foreign Language Interface (FLI) allows users to create functions written in C,
FORTRAN, or other languages and call them from a GAUSS program. The functions
are placed in dynamic-link libraries (DLLs, also known as shared libraries or shared
objects) and linked in at run-time as needed. The FLI support functions are:
dlibrary Link and unlink dynamic libraries at run-time.
dllcall Call functions located in dynamic libraries.
GAUSS recognizes a default dynamic library directory, a directory where it will look
for your dynamic-link libraries when you call dlibrary. You can specify the default
directory in gauss.cfg by setting dlib path. As it is shipped, gauss.cfg species
$GAUSSHOME/dlib as the default directory.
5.1 Creating Dynamic Libraries
Assume you want to build a dynamic library named libmyfuncs.so, containing the
functions found in two source les, myfunc1.c and myfunc2.c. The following sections
show the compile and link commands you would use on the various platforms GAUSS
for Unix runs on, assuming youre using the ANSI C compiler oered for each platform.
The compiler command is rst, followed by the linker command, followed by remarks
regarding that platform.
The ANSI C compiler is included on some platforms; on others it is a separate purchase.
The compiler is usually called cc, the linker is usually called ld. On some platforms, the
linker is invoked by the compiler; on most platforms, we call it directly. Thus, the link
command is sometimes done with ld, sometimes with cc.
55
5. FOREIGN LANGUAGE INTERFACE
For explanations of the various ags used, see the man pages on your system. Two ags
are common to all platforms. The -c compiler ag means compile only, dont link.
Virtually all compilers will perform the link phase automatically unless you tell them
not to. When building a dynamic library we want to compile the source code les to
object (.o) les, then link the object les in a separate phase into a dynamic library.
The -o linker ag means name the output le as follows, and must be followed by the
name of the library you want to create, in this case libmyfuncs.so.
$(CFLAGS) indicates any optional compilation ags you might add.
You may have to use the -l ag to specify additional libraries on the link command line.
5.1.1 Solaris 2.x
cc -c $(CFLAGS) myfunc1.c myfunc2.c
ld -G -o libmyfuncs.so myfunc1.o myfunc2.o
5.1.2 SunOS 4.x
acc -pic -c $(CFLAGS) myfunc1.c myfunc2.c
ld -assert pure-text -assert definitions -o libmyfuncs.so
myfunc1.o myfunc2.o
5.1.3 IBM AIX
cc -pic -c $(CFLAGS) myfunc1.c myfunc2.c
cc -o libmyfuncs.so myfunc1.o myfunc2.o -bE:libmyfuncs.exp
-bM:SRE -e _nostart
The -bE:libmyfuncs.exp ag species the name of the export le. The AIX linker
requires that you specify the names of the symbols that will be exported, i.e., made
callable by other processes, from the dynamic library. The export le is just a text le
that lists the exported symbols, one per line. Assume that myfunc1.c and myfunc2.c
contain the functions func1(), func2(), and func3(), and a static function func4() that
is called by the others, but never directly from GAUSS. For this example, the export
le would look like this:
func1
func2
func3
56
F
o
r
e
i
g
n

L
a
n
g
u
a
g
e

I
n
t
e
r
f
a
c
e
5. FOREIGN LANGUAGE INTERFACE
5.1.4 DEC OSF1
cc -c $(CFLAGS) myfunc1.c myfunc2.c
ld -shared -o libmyfuncs.so myfunc1.o myfunc2.o -lc
Under OSF1, if your library calls functions in the standard C runtime library, libc.so,
you have to explicitly link it in. The -lc ag does this.
5.1.5 HP-UX
cc -c +z $(CFLAGS) myfunc1.c myfunc2.c
ld -b -c libmyfuncs.exp -o libmyfuncs.so myfunc1.o myfunc2.o
Like AIX, the HP-UX linker requires that you indicate the symbols to be exported. In
this case, however, the -c libmyfuncs.exp ag species the name of an indirect
command le. Indirect command les can contain any linker switches you want to place
in them; for our purposes, libmyfuncs.exp contains only +e, or mark symbol for
export , switches. Assuming the example described in the AIX section, libmyfuncs.exp
would look like this:
+e func1
+e func2
+e func3
5.1.6 SGI IRIX
cc -c $(CFLAGS) myfunc1.c myfunc2.c
ar cq myfuncs.a myfunc1.o myfunc2.o
ld -elf -rdata_shared -shared -all myfuncs.a -o libmyfuncs.so
IRIX requires an extra step. The object les produced by the compiler are combined
into a standard archive le using ar; this archive le becomes the input from which the
linker constructs the dynamic library.
5.1.7 Linux
gcc -fpic -c $(CFLAGS) myfunc1.c myfunc2.c
gcc -shared -o libmyfuncs.so myfunc1.o myfunc2.o -lc
Like the DEC, if your library calls functions in the standard C runtime library, libc.so,
you have to explicitly link it in under Linux. Once again, the -lc ag does this.
57
5. FOREIGN LANGUAGE INTERFACE
5.2 Writing FLI Functions
Your FLI functions should be written to the following specications:
1. Take 0 or more pointers to doubles as arguments.
This doesnt mean you cant pass strings to an FLI function. Just recast the
double pointer to a char pointer inside the function.
2. Take those arguments either in a list or a vector.
3. Return an integer.
In C syntax, then, your functions would take one of the following forms:
1. int func(void);
2. int func(double *arg1[[, double *arg2, etc.]]);
3. int func(double *argv[]);
Functions can be written to take a list of up to 100 arguments, or a vector (in C terms,
a 1-dimensional array) of up to 1000 arguments. This does not aect how the function
is called from GAUSS; the dllcall statement will always appear to pass the arguments
in a list. That is, the dllcall statement will always look as follows:
dllcall func(a,b,c,d[[,e...]]);
See dllcall in chapter 6 for details on calling your function, passing arguments to it and
getting data back, and what the return value means.
58
F
o
r
e
i
g
n

L
a
n
g
u
a
g
e

I
n
t
e
r
f
a
c
e
Chapter 6
FLI Function Reference
59
dlibrary 6. FLI FUNCTION REFERENCE
Purpose
Dynamically links and unlinks shared libraries.
Format
dlibrary lib1 [lib2...];
dlibrary -a lib1 [lib2...];
dlibrary -d;
dlibrary;
Input
lib1 lib2... literal, the base name of the library or the fully pathed name of the library.
dlibrary takes two types of arguments, base names and le names. Arguments
without any / path separators are assumed to be library base names, and are
expanded by adding the prex lib and the sux .so. They are searched for in
the default dynamic library directory. Arguments that include / path
separators are assumed to be le names, and are not expanded. Relatively
pathed le names are assumed to be specied relative to the current working
directory.
-a append ag, the DLLs listed are added to the current set of DLLs rather than
replacing them. For search purposes, the new DLLs follow the already active
ones. Without the -a ag, any previously linked libraries are dumped.
-d dump ag, ALL DLLs are unlinked and the functions they contain are no longer
available to your programs. If you use dllcall to call one of your functions after
executing a dlibrary -d, your program will terminate with an error.
Remarks
If no ags are used, the DLLs listed are linked into GAUSS and any previously linked
libraries are dumped. When you call dllcall, the DLLs will be searched in the order
listed for the specied function. The rst instance of the function found will be called.
dlibrary with no arguments prints out a list of the currently linked DLLs. The order in
which they are listed is the order in which they are searched for functions.
dlibrary recognizes a default directory in which to look for dynamic libraries. You can
specify this by setting the variable dlib path in gauss.cfg. Set it to point to a single
directory, not a sequence of directories. A new case (case 24) has also been added to
sysstate for getting and setting this default.
GAUSS maintains its own DLL, libgauss.so. libgauss.so is listed when you execute
dlibrary with no arguments, and searched when you call dllcall. By default,
60
F
o
r
e
i
g
n

L
a
n
g
u
a
g
e

I
n
t
e
r
f
a
c
e
6. FLI FUNCTION REFERENCE dlibrary
libgauss.so is searched last, after all other DLLs, but you can force it to be searched
earlier by listing it explicitly in a dlibrary statement. libgauss.so is always active. It
is not unlinked when you execute dlibrary -d. libgauss.so is located in the
$GAUSSHOME directory.
See also
dllcall, sysstatecase 24
61
dllcall 6. FLI FUNCTION REFERENCE
Purpose
Calls functions located in dynamic libraries.
Format
dllcall [-r] [-v] func[(arg1[,arg2...])];
dllcall works in conjunction with dlibrary. dlibrary is used to link dynamic-link libraries
(DLLs) into GAUSS; dllcall is used to access the functions contained in those DLLs.
dllcall searches the DLLs (see dlibrary for an explanation of the search order) for a
function named func, and calls the rst instance it nds. The default DLL,
libgauss.so, is searched last.
Input
func the name of a function contained in a DLL (linked into GAUSS with dlibrary).
If func is not specied or cannot be located in a DLL, dllcall will fail.
arg# arguments to be passed to func; optional. These must be elementary variables;
they cannot be expressions.
-r optional ag. If -r is specied, dllcall examines the value returned by func, and
fails if it is nonzero.
-v optional ag. Normally, dllcall passes parameters to func in a list. If -v is
specied, dllcall passes them in a vector. See below for more details.
Remarks
func should be written to:
1. Take 0 or more pointers to doubles as arguments.
2. Take arguments either in a list or a vector.
3. Return an integer.
In C syntax, func should take one of the following forms:
1. int func(void);
2. int func(double *arg1[,double *arg2...]);
3. int func(double *argv[]);
62
F
o
r
e
i
g
n

L
a
n
g
u
a
g
e

I
n
t
e
r
f
a
c
e
6. FLI FUNCTION REFERENCE dllcall
dllcall can pass a list of up to 100 arguments to func; if it requires more arguments
than that, you MUST write it to take a vector of arguments, and you MUST specify
the -v ag when calling it. dllcall can pass up to 1000 arguments in vector format. In
addition, in vector format dllcall appends a null pointer to the vector, so you can write
func to take a variable number of arguments and just test for the null pointer.
Arguments are passed to func by reference. This means you can send back more than
just the return value, which is usually just a success/failure code. (It also means that
you need to be careful not to overwrite the contents of matrices or strings you want to
preserve.) To return data from func, simply set up one or more of its arguments as
return matrices (basically, by making them the size of what you intend to return), and
inside func assign the results to them before returning.
See also
dlibrary, sysstatecase 24
63
dllcall 6. FLI FUNCTION REFERENCE
64
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
Chapter 7
Language Fundamentals
GAUSS is a compiled language. GAUSS is also an interpreter. These may seem
contradictory but it is necessary to understand each of these ideas to understand how
GAUSS works and how it can be used most eectively.
GAUSS is a compiled language because it scans the entire program once and translates
it into a binary code before it starts to execute the program. GAUSS is an interpreter
because the binary code is not the native code of the CPU. When GAUSS executes the
binary pseudocode it must interpret each instruction for the computer rather than
just turning loose the CPU to execute the binary code by itself.
How then can GAUSS be so fast if it is an interpreter? There are two reasons. The rst
is that GAUSS has a fast interpreter, and the binary compiled code is compact and
ecient. The second reason, and the most signicant one, is that GAUSS is a matrix
language. It is designed to tackle problems that can be solved in terms of matrix or
vector equations. Much of the time lost in interpreting the pseudocode is made up in
the matrix or vector operations.
In the following pages it will be necessary to understand the distinction between
compile time and execution time because these are two very dierent stages in the
life of a GAUSS program.
7.1 Expressions
An expression is a matrix, string, constant, function or procedure reference or any
combination of these joined by operators. An expression returns a result that can be
assigned to a variable with the assignment operator =.
65
7. LANGUAGE FUNDAMENTALS
7.2 Statements
A statement is a complete expression or command. Statements end with a semicolon.
y = x*3;
If an expression has no assignment operator (=), it will be assumed to be an implicit
print statement.
print x*3;
x*3;
The two statements above are equivalent.
output on;
This is an example of a statement that is a command rather than an expression.
Commands cannot be used as a part of an expression.
There can be multiple statements on the same line as long as each statement is
terminated with a semicolon.
7.2.1 Executable Statements
Executable statements are statements that can be executed over and over during the
execution phase of a GAUSS program. As an executable statement is compiled, binary
code is added to the program being compiled at the current location of the instruction
pointer. This binary code will be executed whenever the interpreter passes through this
section of the program. If this code is in a loop, it will be executed each iteration of the
loop.
Here are some examples of executable statements.
y = 34.25;
print y;
x = { 1 3 7 2 9 4 0 3 };
66
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
7.2.2 Nonexecutable Statements
Nonexecutable statements are statements that have an eect only at compile time.
They generate no executable code at the current location of the instruction pointer.
Here are some examples:
declare matrix x = { 1 2 3 4 };
external matrix ybar;
Procedure denitions are nonexecutable. They do not generate executable code at the
current location of the instruction pointer. Here is an example:
zed = rndn(3,3);
proc sqrtinv(x);
local y;
y = sqrt(x);
retp(y+inv(x));
endp;
zsi = sqrtinv(zed);
The two executable statements are the rst line and the last line. In the binary code
that is generated, the last line will follow immediately after the rst line. Everything in
the procedure denition is tucked away somewhere else. The last line is the call to the
procedure. This generates executable code. The procedure denition generates no code
at the current location of the instruction pointer.
There is code generated in the procedure denition, but it is isolated from the rest of
the program. It is executable only within the scope of the procedure and can be
reached only by calling the procedure.
7.3 Programs
A program is any set of statements that are run together at one time. This is a rather
loose denition, but it should suce. If the run statement is used from within a
program, it starts a new program. There are two distinct sections within a program
which need to be understood.
67
7. LANGUAGE FUNDAMENTALS
7.3.1 Main Section
The rst is the main section. The main section of the program is all of the code that is
compiled together WITHOUT relying on the autoloader. This means code that is in
the main le or is included in the compilation of the main le with an #include
statement. ALL executable code should be in the main section.
There is always a main section even if it only consists of a call to the one and only
procedure that is called in the program. The main program code is stored in an area of
memory that can be adjusted in size with the new command.
7.3.2 Secondary Sections
Secondary sections of the program are les that are neither run directly nor included in
the main section with #include statements.
The secondary sections of the program can be left to the autoloader to locate and
compile when they are needed. Secondary sections must have only procedure denitions
and other nonexecutable statements. If you violate this, you will have problems.
GAUSS does not currently enforce this, but it will in later versions.
#include statements are okay in secondary sections as long as the le being included
does not violate the above criteria. Here is an example of a secondary section.
declare matrix tol = 1.0e-15;
proc feq(a,b);
retp(abs(a-b) <= tol);
endp;
7.4 Compiler Directives
Compiler directives are commands that tell GAUSS how to process a program during
compilation. Directives determine what the nal compiled form of a program will be.
They can aect part or all of the source code for a program. Directives are not
executable statements and have no eect at run-time.
The #include statement mentioned above is actually a compiler directive. It tells
GAUSS to compile code from a separate le as though it were actually part of the le
being compiled. This code is compiled in at the position of the #include statement.
Here are the compiler directives available in GAUSS:
68
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
#dene Dene a case-insensitive text-replacement or ag variable.
#denecs Dene a case-sensitive text-replacement or ag variable.
#undef Undene a text-replacement or ag variable.
#ifdef Compile code block if a variable has been #dened.
#ifndef Compile code block if a variable has not been #dened.
#iight Compile code block if running GAUSS Light.
#ifdos Compile code block if running DOS.
#ifos2win Compile code block if running OS/2 or Windows.
#ifunix Compile code block if running Unix.
#else Else clause for #if-#else-#endif code block.
#endif End of #if-#else-#endif code block.
#include Include code from another le in program.
#lineson Compile program with line number and le name records.
#lineso Compile program without line number and le name records.
#srcle Insert source le name record at this point
(currently used when doing data loop translation).
#srcline Insert source le line number record at this point
(currently used when doing data loop translation).
The #dene statement can be used to dene abstract constants. For example, you
could dene the default graphics page size as:
#define hpage 9.0
#define vpage 6.855
You can then write your program using hpage and vpage, and GAUSS will replace
them with 9.0 and 6.855 when it compiles the program. This can make programs much
more readable.
The #ifdef#else#endif directives allow you to conditionally compile sections of a
program, depending on whether a particular ag variable has been #dened. For
example:
#ifdef log_10
y = log(x);
#else
y = ln(x);
#endif
This allows the same program to calculate answers using dierent base logarithms,
depending on whether or not the program has a #dene log 10 statement at the top.
#undef allows you to undene text-replacement or ag variables, so they no longer
aect a program, or so you can #dene them again with a dierent value for a
dierent section of the program. If you use #denecs to dene a case-sensitive
variable, you must use the right case when #undefing it.
69
7. LANGUAGE FUNDAMENTALS
With #lineson, #lineso, #srcline and #srcle you can include line number and le
name records in your compiled code, so that run-time errors will be easier to track
down. #srcline and #srcle are currently used by GAUSS when doing data loop
translation (see Chapter 13). For a discussion of line number tracking see the
Debugger, or Error Handling and Debugging chapter in your platform supplement. See
also #lineson in the COMMAND REFERENCE.
The syntax for #srcle and #srcline is a little dierent than for the other directives
that take arguments. Typically, directives do not take arguments in parentheses (i.e.
they look like keywords).
#define red 4
#srcle and #srcline, however, do take their arguments in parentheses (like
procedures).
#srcline(12)
This allows you to place #srcline statements in the middle of GAUSS commands, so
that line numbers are reported precisely as you want them. For example:
#srcline(1)
print "Here is a multi-line "
#srcline(2)
"sentence--if it contains a run-time error, "
#srcline(3) "you will know exactly "
#srcline(4) "which part of the sentence has the problem.";
The argument supplied to #srcle does not need quotes.
#srcfile(/gauss/test.e)
7.5 Procedures
A procedure allows you to dene a new function which you can then use as if it were an
intrinsic function. It is called in the same way as an intrinsic function.
y = myproc(a,b,c);
Procedures are isolated from the rest of your program and cannot be entered except by
calling them. Some or all of the variables inside a procedure can be local variables.
local variables are variables that exist only when the procedure is actually executing
and then disappear. Local variables cannot get mixed up with other variables of the
same name in your main program or in other procedures.
See Chapter 9 for details on dening and calling procedures.
70
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
7.6 Data Types
There are only two basic data types in GAUSS, matrices and strings. It is not
necessary to declare the type of a variable. The data type and size can change in the
course of a program.
The declare statement, used for compile-time initialization, enforces type checking and
it is good programming practice to respect the types of variables whenever possible.
Short strings of up to 8 bytes can be entered into elements of matrices, to form
character matrices. These are discussed in Section 7.6.4.
7.6.1 Constants
The following constant types are supported.
Decimal
Decimal constants can be either integer or oating point values.
1.34e-10
1.34e123
-1.34e+10
-1.34d-10
1.34d10
1.34d+10
123.456789345
Up to 18 consecutive digits before and after the decimal point(depending on the
platform) are signicant, but the nal result will be rounded to double precision if
necessary. The range is the same as for matrices. See Section 7.6.2.
String
String constants are enclosed in quotation marks.
This is a string.
71
7. LANGUAGE FUNDAMENTALS
Hexadecimal Integer
Hexadecimal integer constants are prexed with 0x.
0x0ab53def2
Hexadecimal Floating Point
Hexadecimal oating point constants are prexed with 0v. This allows you to input a
double precision value exactly as you want using 16 hexadecimal digits. The highest
order byte is to the left.
0vf8000000000000
7.6.2 Matrices
Matrices are 2-dimensional arrays of double precision numbers. All matrices are
implicitly complex, although if it consists only of zeros, the imaginary part may take up
no space. Matrices are stored in row major order. A 2x3 real matrix will be stored in
the following way from the lowest addressed element to the highest addressed element.
[1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
A 2x3 complex matrix will be stored in the following way from the lowest addressed
element to the highest addressed element.
(real part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
(imaginary part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
Conversion between complex and real matrices occurs automatically and is transparent
to the user in most cases. Functions are provided to provide explicit control when
necessary.
All numbers in GAUSS matrices are stored in double precision oating point format,
and each takes up 8 bytes of memory. This is the IEEE 754 format.
Bytes Data Type Signicant Range
Digits
8 oating point 1516 4.19x10
307
[X[ 1.67x10
+308
72
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
Matrices with only one number (1x1 matrices) are referred to as scalars, and matrices
with only one row or column (1xN or Nx1 matrices) are referred to as vectors.
Any matrix or vector can be indexed with 2 indices. Vectors can be indexed with one
index. Scalars can be indexed with one or two indices also, because scalars, vectors,
and matrices are the same data type to GAUSS
The majority of functions and operators in GAUSS take matrices as arguments. The
following functions and operators are used for dening, saving, and loading matrices:
[ ] indexing matrices
= assignment operator
| vertical concatenation
horizontal concatenation
con numeric input from keyboard
cons character input from keyboard
declare compile-time matrix or string initialization
let matrix denition statement
load load matrix (same as loadm)
readr read from a GAUSS le
save save matrices, procedures and strings to disk
saved convert a matrix to a GAUSS data set
stof convert string to matrix
submat extract a submatrix
writer write data to a GAUSS data set
Examples of matrix denition statements are:
let x = { 1 2 3, 4 5 6, 7 8 9 };
or
x = { 1 2 3, 4 5 6, 7 8 9 };
x =
1 2 3
4 5 6
7 8 9
An assignment statement followed by data enclosed in braces is an implicit let
statement. Only constants are allowed in let statements; operators are illegal. When
braces are used in let statements, commas are used to separate rows.
let x[3,3] = 1 2 3 4 5 6 7 8 9;
73
7. LANGUAGE FUNDAMENTALS
x =
1 2 3
4 5 6
7 8 9
let x[3,3] = 1;
x =
1 1 1
1 1 1
1 1 1
let x[3,3];
x =
0 0 0
0 0 0
0 0 0
let x = 1 2 3 4 5 6 7 8 9;
x =
1
2
3
4
5
6
7
8
9
let x[2,2] = 1+2i 3-4 5 6i;
x =
1 + 2i 3 4i
5 0 + 6i
Complex constants can be entered in a let statement. Note that in this case, the + or -
is not a mathematical operator, but connects the two parts of a complex number.
There can be no spaces between the + or - and the parts of the number. If a number
74
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
has both real and imaginary parts, the trailing i is not necessary. If a number has no
real part, you can indicate that it is imaginary by appending the i.
Complex constants can also be used with the declare, con and stof statements.
An empty matrix is a matrix that contains no data. Empty matrices are created with
the let statement.
x = {};
You must use the form of the let statement with curly braces to create an empty
matrix.
Empty matrices are currently supported ONLY by the rows and cols functions and the
concatenation (~,|) operators.
x = {};
hsec0 = hsec;
do until hsec-hsec0 > 6000;
x = x ~ data_in(hsec-hsec0);
endo;
You can test whether a matrix is empty by entering rows(x), cols(x) and scalerr(x). If
the matrix is empty rows and cols will return a 0, and scalerr will return 65535.
y = 12|34;
The is the horizontal concatenation operator and the | is the vertical concatenation
operator. This statement would be evaluated as:
y = (12)|(34);
because horizontal concatenation has precedence over vertical concatenation, and would
result in a 2x2 matrix.
1 2
3 4
y = 1+12*2|3-26/2;
75
7. LANGUAGE FUNDAMENTALS
This statement would be evaluated as:
y = ((1+1)(2*2))|((3-2)(6/2));
because the arithmetic operators have precedence over concatenation, and would result
in a 2x2 matrix. See also section 7.7.
2 4
1 3
let x[2,2] = 1 2 3 4;
The let command is used to initialize matrices with constant values. Unlike the
concatenation operators, it cannot be used to dene matrices in terms of expressions
such as:
y = x1-x2x2|x3*3x4;
y = x[1:3,5:8];
will put the intersection of the rst 3 rows and the fth through eighth columns of x
into the matrix y.
y = x[1 3 1,5 5 9];
will create a 3x3 matrix y with the intersection of the specied rows and columns
pulled from x (in the indicated order).
let r = 1 3 1;
let c = 5 5 9;
y = x[r,c];
will have the same eect as the example above, but is more general.
y[2,4] = 3;
76
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
will set the 2,4 element of the existing matrix y to 3. This statement is illegal if y does
not have at least 2 rows and 4 columns.
x = con(3,2);
will cause a ? to be printed on the screen, and will prompt the user until 6 numbers
have been entered from the keyboard.
load x[] = b:mydata.asc
will load data contained in an ASCII le into an Nx1 vector x (use rows(x) to nd out
how many numbers were loaded, and use reshape(x,N,K) to reshape it to an NxK
matrix).
load x;
will load the matrix x.fmt from disk (using the current load path) into the matrix x in
memory.
open d1 = dat1;
x = readr(d1,100);
will read the rst 100 rows of the GAUSS data set dat1.dat.
7.6.3 Strings and String Arrays
Strings
Strings can be used to store the names of les to be opened, messages to be printed,
entire les, or whatever else you might need. Any byte value is legal in a string from
0255. The buer where a string is stored always contains a terminating byte of ASCII
0. This allows passing strings as arguments to C functions through the foreign language
interface. Here is a partial list of the functions for manipulating strings.
77
7. LANGUAGE FUNDAMENTALS
$+ combines two strings into one long string.
^ interpret following name as a variable, not a literal.
chrs convert vector of ASCII codes to character string.
ftocv character representation of numbers in NxK matrix.
ftos character representation of numbers in 1x1 matrix.
getf load ASCII or binary le into string.
indcv nd index of element in character vector.
lower convert to lowercase.
stof convert string to oating point.
strindx nd index of a string within a second string.
strlen length of a string.
strsect extract substring of string.
upper convert to uppercase.
vals convert from string to numeric vector of ASCII codes.
Strings can be created like this:
x = "example string";
or
x = cons; /* keyboard input */
or
x = getf("myle",0); /* read a le into a string */
They can be printed like this:
print x;
A character matrix must have a $ prexed to it in a print statement.
print $x;
A string can be saved to disk with the save command in a le with a .fst extension
and then loaded with the load command as follows:
save x;
loads x;
or
loads x=x.fst;
The backslash is used as the escape character inside double quotes to enter special
characters. backslash escape character
"\b" backspace (ASCII 8)
"\e" escape (ASCII 27)
"\f" formfeed (ASCII 12)
"\g" beep (ASCII 7)
"\l" line feed (ASCII 10)
"\r" carriage return (ASCII 13)
"\t" tab (ASCII 9)
"\\" a backslash
"\###" the ASCII character whose decimal value is ###.
78
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
When entering DOS pathnames in double quotes two backslashes must be used to
insert one backslash.
st = "c:\\gauss\\myprog.prg";
An important use of strings (and also character elements of matrices; see below) is with
the substitution, or caret (^), operator.
In a command like the following:
create f1 = olsdat with x,4,2;
by default GAUSS will interpret the olsdat as a literal, i.e., the literal name of the
GAUSS data le that you want to create. It will also interpret the x as the literal prex
string for the variable names: x1 x2 x3 x4.
If you want to get the data set name from a string variable, the (^) caret operator
could be used as:
dataset="olsdat";
create f1=^dataset with x,4,2;
If you want to get the data set name from a string variable and the variable names
from a character vector, then use the following:
dataset="olsdat";
let vnames=age pay sex;
create f1=^dataset with ^vnames,0,2;
The (^) caret operator works with load, save, and dos also.
lpath="/gauss/procs";
name="mydata";
load path=^lpath x=^name;
command="dir *.fmt";
dos ^command;
The general syntax is:
^variable name
Expressions are not allowed. The following commands are supported with the
substitution operator.
create f1=^dataset with ^vnames,0,2;
create f1=^dataset using ^cmdle;
open f1=^dataset;
output le=^outle;
load x=^datale;
load path=^lpath x,y,z,t,w;
loadexe buf=^exele;
save ^name=x;
save path=^spath;
dos ^cmdstr;
run ^prog;
msym ^mstring;
79
7. LANGUAGE FUNDAMENTALS
String Arrays
String arrays are NxK matrices of strings. Here is a partial list of the functions for
manipulating string arrays:
80
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
$| vertical string array concatenation operator.
$~ horizontal string array concatenation operator.
[ ] extract subarrays or individual strings from their
corresponding array, or assign their values.
/ transpose operator.
./ bookkeeping transpose operator.
declare initializes variables at compile time.
delete deletes specied global symbols.
fgetsa reads multiple lines of text from a le.
fgetsat reads multiple lines of text from a le, discarding
newlines.
format denes output format for matrices, string arrays,
and strings.
fputs writes strings to a le.
fputst writes strings to a le, appending newlines.
let initializes matrices, strings, and string arrays.
loads loads a string or string array le (.fst file).
lprint prints expressioins to the printer.
lshow prints global symbol table to the printer.
print prints expressions on screen and/or auxiliary output.
reshape reshapes a matrix or string array to new dimensions.
save saves matrix, string array, string, procedure, function
or keyword to disk and gives the disk le either a .fmt,
.fst or .fcg extension.
show displays global symbol table.
sortcc quick-sorts rows of matrix or string array based on
character column.
type indicates whether variable passed as argument is matrix,
string, or string array.
typecv indicates whether variables named in argument are strings,
string arrays, matrices, procedures, functions or keywords.
varget accesses the global variable named by a string array.
varput assigns the global variable named by a string array.
vec stacks columns of a matrix or string array to form a
column vector.
vecr stacks rows of a matrix or string array to form a column vector.
81
7. LANGUAGE FUNDAMENTALS
String arrays are created through the use of the string array concatenation operators.
Below is a contrast of the horizontal string and horizontal string array concatenation
operators.
x = "age";
y = "pay";
n = "sex";
s = x $+ y $+ n;
sa = x $~ y $~ n;
s = agepaysex
sa = age pay sex
7.6.4 Character Matrices
Matrices can have either numeric or character elements. For convenience we refer to a
matrix containing character elements as a character matrix.
A character matrix is not a separate data type but just gives you the ability to store
and manipulate data elements that are composed of ASCII characters as well as
oating point numbers. For example, you may want to concatenate a column vector
containing the names of the variables in an analysis onto a matrix containing the
coecients, standard errors, t-statistic, and p-value. You can then print out the whole
matrix with a separate format for each column with one call to the function printfm.
The logic of the programs will dictate the type of data that is assigned to a matrix, and
the increased exibility allowed by being able to bundle both types of data together in
a single matrix can be very powerful. You could, for instance, create a moment matrix
from your data, concatenate a new row onto it containing the names of the variables
and save it to disk with the save command.
Numeric matrices are double precision, which means that each element is stored in
8 bytes. A character matrix can thus have elements of up to 8 characters. Character
matrices are ideal for the manipulation of the names of the columns in a data matrix,
which are limited to 8 characters.
GAUSS does not automatically keep track of whether a matrix contains character or
numeric information. The ASCII to GAUSS conversion program atog will record the
types of variables in a data set when it creates it. The create command will, too. The
function vartypef gets a vector of variable type information from a data set. This
vector of ones and zeros can be used by printfm when printing your data. Since
GAUSS does not know whether a matrix has character or numeric information, it is up
to the user to specify which type of data it contains when printing the contents of the
matrix. See print and printfm for details.
Most functions that take a string argument will take an element of a character matrix
also, interpreting it as a string of up to 8 characters.
82
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
7.6.5 Special Data Types
The IEEE oating point format has many encodings that have special meaning. The
print command will print them accurately so that you can tell if your calculation is
producing results that are meaningful.
NaN
There are many oating point encodings which do not correspond to a real number.
These encodings are referred to as NaNs. NaN stands for Not A Number.
Certain numerical errors will cause the math coprocessor to create a NaN called an
indenite. This will be printed as a -NaN when using the print command. These
values are created by the following operations.
+ plus
+ minus +
minus
0
/
0 / 0
Operations where one or both operands is a NaN
Trigonometric functions involving
INF
When the math coprocessor overows, the result will be a properly signed innity.
Most subsequent calculations will not deal with innities very well, and it is usually a
signal of an error in your program. The result of an operation involving an innity is
usually a NaN.
DEN, UNN
When some math coprocessors underow, they may do so gradually by shifting the
signicand of the number as necessary to keep the exponent in range. The result of this
83
7. LANGUAGE FUNDAMENTALS
is a denormal (DEN). When denormals are used in calculations, they are usually
handled automatically in an appropriate way. The result will either be an unnormal
(UNN), which like the denormal represents a number very close to zero, or a normal,
depending on how signicant the eect of the denormal was in the calculation. In some
cases the result will be a NaN. This can happen in GAUSS for DOS when the value
that is in a math coprocessor register in 80-bit format is an unnormal and has an
exponent that is within the range of the 64-bit double precision format. Therefore,
sometimes multiplying an unnormal by another number will result in a NaN. Following
are some procedures for dealing with these values.
The procedure isindef will return 1 (true) if the matrix passed to it contains any NaNs
that are the indenite mentioned above. The GAUSS missing value code as well as
GAUSS scalar error codes are NaNs, but this procedure tests only for indenite.
proc isindef(x);
retp(not x $/= __INDEFn);
endp;
Be sure to call gausset before calling isindef. gausset will initialize the value of the
global INDEFn to a platform specic encoding.
The procedure normal will return a matrix with all denormals and unnormals set to
zero.
proc normal(x);
retp(x .* (abs(x) .> 4.19e-307));
endp;
This procedure, isinf, will return 1 (true) if the matrix passed to it contains any
innities.
proc isinf(x);
local plus,minus;
plus = __INFp;
minus = __INFn;
retp(not x /= plus or not x /= minus);
endp;
Be sure to call gausset before calling isinf. gausset will initialize the value of the
globals INFn and INFp to platform specic encodings.
7.7 Operator Precedence
The order in which an expression is evaluated is determined by the precedence of the
operators involved and the order in which they are used. For example, the * and /
84
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
operators have a higher precedence than the + and - operators. In expressions which
contain the above operators, the operand pairs associated with the * or / operator are
evaluated rst. Whether * or / is evaluated rst depends on which comes rst in the
particular expression.
The precedence of all operators is listed in Appendix D.
The expression
-5+3/4+6*3
is evaluated as
(5) +(3/4) + (6 3)
Within a term, operators of equal precedence are evaluated from left to right.
The term
2^3^7
is evaluated
(2
3
)
7
In the expression
f1(x)*f2(y)
the function f1 is evaluated before f2.
Here are a few examples:
expression evaluation
a+b*c+d (a +(b c)) +d
-2+4-6*inv(8)/9 ((2) + 4) ((6 inv(8))/9)
3.14^5*6/(2+sqrt(3)/4) ((3.14
5
) 6)/(2 + (sqrt(3)/4))
-a+b*c^2 (a) + (b (c
2
))
a+b-c+d-e (((a +b) c) +d) e
a^b^c*d ((a
b
)
c
) d
a*b/d*c ((a b)/d) c
a^b+c*d (a
b
) + (c d)
2^4! (2
4
)!
2*3! 2 (3!)
85
7. LANGUAGE FUNDAMENTALS
7.8 Flow Control
A computer language needs facilities for decision making and looping to control the
order in which computations are done. GAUSS has several kinds of ow control
statements.
7.8.1 Looping
do loop
The do statement can also be used in GAUSS to control looping.
do while scalar expression; Loop if expression is true.
.
.
.
statements
.
.
.
endo;
do until scalar expression; Loop if expression is false.
.
.
.
statements
.
.
.
endo;
The scalar expression is any expression that returns a scalar result. The expression will
be evaluated as TRUE if its real part is nonzero and FALSE if it is zero. There is no
counter variable that is automatically incremented in a do loop. If one is used, it must
be set to its initial value before the loop is entered and explicitly incremented or
decremented inside the loop. The following example illustrates nested do loops that use
counter variables.
format /rdn 1,0;
space = " ";
comma = ",";
i = 1;
do while i <= 4;
j = 1;
do while j <= 3;
print space i comma j;;
j = j+1;
endo;
i = i+1;
print;
endo;
86
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
The example above will print the following.
1,1 1,2 1,3
2,1 2,2 2,3
3,1 3,2 3,3
4,1 4,2 4,3
Use the relational and logical operators without the dot . in the expression that
controls a do loop. These operators always return a scalar result.
break and continue are used within do loops to control execution ow. When break is
encountered, the program will jump to the statement following the endo. This
terminates the loop. When continue is encountered, the program will jump up to the
top of the loop and reevaluate the while or until expression. This allows you to
reiterate the loop without executing any more of the statements inside the loop.
do until eof(fp); /* continue jumps here */
x = packr(readr(fp,100));
if scalmiss(x);
continue; /* iterate again */
endif;
s = s + sumc(x);
count = count + rows(x);
if count >= 10000;
break; /* break out of loop */
endif;
endo;
mean = s / count; /* break jumps here */
for loop
The fastest looping construct in GAUSS is the for loop.
for counter (start , stop, step);
.
.
.
statements
.
.
.
endfor;
counter is the literal name of the counter variable. start , stop and step are scalar
expressions. start is the initial value, stop is the nal value and step is the increment.
break and continue are also supported by for loops. For more information see for in
the COMMAND REFERENCE.
87
7. LANGUAGE FUNDAMENTALS
7.8.2 Conditional Branching
The if statement controls conditional branching.
if scalar expression;
.
.
.
statements
.
.
.
elseif scalar expression;
.
.
.
statements
.
.
.
else;
.
.
.
statements
.
.
.
endif;
The scalar expression is any expression that returns a scalar result. The expression will
be evaluated as TRUE if its real part is nonzero and FALSE if it is zero.
GAUSS will test the expression after the if statement. If it is TRUE, then the rst list
of statements is executed. If it is FALSE, then GAUSS will move to the expression
after the rst elseif statement, if there is one, and test it. It will keep testing
expressions and will execute the rst list of statements that corresponds to a TRUE
expression. If no expression is TRUE, then the list of statements following the else
statement is executed. After the appropriate list of statements is executed, the program
will go to the statement following the endif and continue on.
Use the relational and logical operators without the dot . in the expression that
controls an if or elseif statement. These operators always return a scalar result.
if statements can be nested.
One endif is required per if clause. If an else statement is used, there may be only one
per if clause. There may be as many elseifs as are required. There need not be any
elseifs or any else statement within an if clause.
7.8.3 Unconditional Branching
The goto and gosub statements control unconditional branching. The target of both a
goto and a gosub is a label.
88
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
goto
A goto is an unconditional jump to a label with no return.
label:
.
.
goto label;
Parameters can be passed with a goto. The number of parameters is limited by
available stack space. This is handy for common exit routines.
.
.
goto errout("Matrix singular");
.
.
goto errout("File not found");
.
.
errout:
pop errmsg;
errorlog errmsg;
end;
gosub
With a gosub, the address of the gosub statement is remembered and when a return
statement is encountered, the program will resume executing at the statement following
the gosub.
Parameters can be passed with a gosub in the same way as a goto. With a gosub it is
also possible to return parameters with the return statement.
Subroutines are not isolated from the rest of your program and the variables referred to
between the label and the return statement can be accessed from other places in your
program.
Since a subroutine is only an address marked by a label, there can be subroutines inside
of procedures. The variables that are used in these subroutines are the same variables
that are known inside the procedure. They will not be unique to the subroutine, but
they may be locals that are unique to the procedure that the subroutine is in. See
gosub in the COMMAND REFERENCE for the details.
89
7. LANGUAGE FUNDAMENTALS
7.9 Functions
Single line functions that return one item can be dened with the fn statement.
fn area(r) = pi * r * r;
These functions can be called in the same way as intrinsic functions. The above
function could be used in the following program sequence.
diameter = 3;
radius = 3 / 2;
a = area(radius);
7.10 Rules of Syntax
This section lists the general rules of syntax for GAUSS programs.
7.10.1 Statements
A GAUSS program consists of a series of statements. A statement is a complete
expression or command. Statements in GAUSS end with a semicolon. See your
supplement for the maximum statement length in this implementation.
There is one exception to the rule that statements must end with a semicolon. From
the GAUSS command line, the nal semicolon in an interactive program is implicit if it
is not explicitly given.
(gauss) x=5; z=rndn(3,3); y=x+z
Column position is not signicant. Blank lines are allowed. Inside a statement and
outside of double quotes, the carriage return/line feed at the end of a physical line will
be converted to a space character as the program is compiled.
A statement containing a quoted string can be continued across several lines with a
backslash as follows.
s = "This is one really long string that would be "\
"difficult to assign in just a single line.";
7.10.2 Case
GAUSS does not distinguish between uppercase and lowercase except inside double
quotes.
With some operating systems, le names are case sensitive.
90
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
7.10.3 Comments
/* This kind of comment can be nested */
@ This kind cannot be nested @
7.10.4 Extraneous Spaces
Extraneous spaces are signicant in print and lprint statements where the space is a
delimiter between expressions.
print x y z;
In print and lprint statements, spaces can be used in expressions that are in parentheses.
print (x * y) (x + y);
7.10.5 Symbol Names
The names of matrices, strings, procedures, and functions can be up to 32 characters
long. The characters must be alphanumeric or the underscore. The rst character must
be alphabetic or an underscore.
7.10.6 Labels
A label is used as the target of a goto or a gosub. The rule for naming labels is the
same as for matrices, strings, procedures, and functions. A label is followed
immediately by a colon.
here:
The reference to a label does not use a colon.
goto here;
7.10.7 Assignment Statements
The equal sign = is the assignment operator.
y = x + z;
Multiple assignments must be enclosed in braces.
{ mant,pow } = base10(x);
The (equal to) comparison operator is two equal signs ==.
if x == y;
print "x is equal to y";
endif;
91
7. LANGUAGE FUNDAMENTALS
7.10.8 Function Arguments
The arguments to functions are enclosed in parentheses.
y = sqrt(x);
7.10.9 Indexing Matrices
Brackets [ ] are used to index matrices.
x = { 1 2 3,
3 7 5,
3 7 4,
8 9 5,
6 1 8 };
y = x[3,3];
z = x[1 2:4,1 3];
Vectors can be indexed with either 1 or 2 indices.
v = { 1 2 3 4 5 6 7 8 9 };
k = v[3];
j = v[1,6:9];
x[2,3] returns the element in the second row and the third column of x.
x[1 3 5,4 7] returns the submatrix that is the intersection of rows 1, 3 and 5 and
columns 4 and 7.
x[.,3] returns the third column of x.
x[3:5,.] returns the submatrix containing the third through the fth rows of x.
The indexing operator will take vector arguments for submatrix extraction or
submatrix assignments.
y = x[rv,cv];
y[rv,cv] = x;
rv and cv can be any expressions returning vectors or matrices. The elements of rv will
be used as the row indices and the elements of cv will be used as the column indices. If
rv is a scalar 0, then all rows will be used and if cv is a scalar 0, then all columns will
be used. If a vector is used in an index expression, then it is illegal to use the space
operator or the colon operator on the same side of the comma as the vector.
92
L
a
n
g
u
a
g
e

F
u
n
d
a
m
e
n
t
a
l
s
7. LANGUAGE FUNDAMENTALS
7.10.10 Arrays of Matrices and Strings
It is possible to index sets of matrices or strings using the varget function. Consider
the following example.
mvec = { x y z a };
i = 2;
g = inv(varget(mvec[i]));
In this example, a set of matrix names is assigned to mvec. The name y is indexed
from mvec and passed to varget which will return the global matrix y. The returned
matrix is inverted and assigned to g.
The following procedure can be used to index the matrices in mvec more directly.
proc imvec(i);
retp(varget(mvec[i]));
endp;
Then imvec(i) will equal the matrix whose name is in the i
th
element of mvec.
In the example above, the procedure imvec() was written so that it always operates on
the vector mvec. The following procedure makes it possible to pass in the vector of
names being used.
proc get(array,i);
retp(varget(array[i]));
endp;
Then get(mvec,3) will return the 3
rd
matrix listed in mvec.
proc put(x,array,i);
retp(varput(x,array[i]));
endp;
And put(x,mvec,3) will assign x to the 3
rd
matrix listed in mvec and return a 1 if
successful or a 0 if it fails.
7.10.11 Arrays of Procedures
It is also possible to index procedures. The ampersand (&) operator is used to return a
pointer to a procedure.
As an example, assume that f1, f2, and f3 are procedures that take a single argument.
The following code denes a procedure that will return the value of the i
th
procedure,
evaluated at x.
93
7. LANGUAGE FUNDAMENTALS
nms = &f1 | &f2 | &f3;
proc fi(x,i);
local f;
f = nms[i];
local f:proc;
retp( f(x) );
endp;
For instance, (x,2) will return f2(x). The ampersand is used to return the pointers to
the procedures. nms is just a numeric vector that contains a set of pointers. The local
statement is used twice. The rst one tells the compiler that f is a local matrix. The i
th
pointer (which is just a number) is assigned to f. Then the second local statement tells
the compiler to treat f as a procedure from this point on, and so the subsequent
statement f(x) is interpreted as a procedure call.
94
O
p
e
r
a
t
o
r
s
Chapter 8
Operators
8.1 Element-by-Element Operators
The operators described as element-by-element operators share common rules of
conformability. Some functions that have two arguments also operate according to the
same rules.
The element-by-element operators handle those situations in which matrices are not
conformable according to standard rules of matrix algebra. When a matrix is said to be
ExE conformable, it refers to this element-by-element conformability. The following
cases are supported.
matrix op matrix
matrix op scalar
scalar op matrix
matrix op vector
vector op matrix
vector op vector
In a typical expression involving an element-by-element operator:
z = x + y;
conformability is dened as follows.
95
8. OPERATORS
If x and y are the same size, the operations are carried out corresponding
element by corresponding element.
x =
1 3 2
4 5 1
3 7 4
y =
2 4 3
3 1 4
6 1 2
z =
3 7 5
7 6 5
9 8 6
If x is a matrix and y is a scalar, or vice versa, then the scalar is operated on
with respect to every element in the matrix. For example, x + 2 will add 2 to
every element of x.
x =
1 3 2
4 5 1
3 7 4
y = 2
z =
3 5 4
6 7 3
5 9 6
If x is an Nx1 column vector and y is an NxK matrix, or vice versa, the vector is
swept across the matrix.
vector matrix
1 2 4 3
4 3 1 4
3 6 1 2
result
3 5 4
7 5 8
9 4 5
If x is an 1xK column vector and y is an NxK matrix, or vice versa, then the
vector is swept down the matrix.
96
O
p
e
r
a
t
o
r
s
8. OPERATORS
vector 2 4 3

2 4 3
matrix 3 1 4
6 1 2
4 8 6
result 5 5 7
8 5 5
When one argument is a row vector and the other is a column vector, the result
of an element-by-element operation will be the table of the two.
row vector 2 4 3 1
3 5 7 6 4
column vector 2 4 6 5 3
5 7 9 8 6
If x and y are such that none of these conditions apply, then the matrices are not
conformable to these operations and an error message will be generated.
8.2 Matrix Operators
The following operators work on matrices. Some assume numeric data and others will
work on either character or numeric data.
8.2.1 Numeric Operators
See Section 8.1 for details on how matrix conformability is dened for
element-by-element operators.
+ Addition:
y = x + z;
97
8. OPERATORS
Performs element-by-element addition.
Subtraction or negation:
y = x z;
y = k;
Performs element-by-element subtraction or the negation of all elements,
depending on context.
* Matrix multiplication or multiplication:
y = x * z;
When z has the same number of rows as x has columns, this will perform matrix
multiplication (inner product). If x or z are scalar, this performs standard
element-by-element multiplication.
/ Division or linear equation solution.
x = b / A;
If A and b are scalars, it performs standard division. If one of the operands is a
matrix and the other is scalar, the result is a matrix the same size with the
results of the divisions between the scalar and the corresponding elements of the
matrix. Use ./ for element-by-element division of matrices.
If b and A are conformable, this operator solves the linear matrix equations.
Ax = b
Linear equation solution is performed in the following cases.
If A is a square matrix and has the same number of rows as b, then this
statement will solve the system of linear equations using an LU
decomposition.
If A is rectangular with the same number of rows as b, then this statement
will produce the least squares solutions by forming the normal equations
and using the Cholesky decomposition to get the solution.
y =
A

b
A

A
If trap 2 is set, missing values will be handled with pairwise deletion.
For least squares solutions on OS/2 and DOS, all computations and storage
of intermediate results are done in 80-bit precision. prcsn 64 can be
specied to force 64-bit precision for smaller matrices or when using these
platforms.
98
O
p
e
r
a
t
o
r
s
8. OPERATORS
% Modulo division:
y = x % z;
For integers, this returns the integer value that is the remainder of the integer
division of x by z. If x or z are noninteger, they will rst be rounded to the
nearest integer. This is an element-by-element operator.
! Factorial:
y = x!;
Computes the factorial of every element in the matrix x. Nonintegers are
rounded to the nearest integer before the factorial operator is applied. This will
not work with complex matrices. If x is complex, a fatal error will be generated.
.* Element-by-element multiplication:
y = x .* z;
If x is a column vector, and z is a row vector (or vice versa), then the outer
product or table of the two will be computed. See Section 8.1 for
conformability rules.
./ Element-by-element division:
y = x ./ z;
^ Element-by-element exponentiation.
y = x^z;
If x is negative, z must be an integer.
.^ Same as ^
.*. Kronecker (tensor) product:
y = x .*. z;
This results in a matrix in which every element in x has been multiplied (scalar
multiplication) by the matrix z. For example:
x = { 1 2,
3 4 };
z = { 4 5 6,
7 8 9 };
y = x .*. z;
99
8. OPERATORS
x =
1 2
3 4
z =
4 5 6
7 8 9
y =
4 5 6 8 10 12
7 8 9 14 16 18
12 15 18 16 20 24
21 24 27 28 32 36
Horizontal direct product.
z = x y;
x =
1 2
3 4
y =
5 6
7 8
z =
5 6 10 12
21 24 28 32
The input matrices x and y must have the same number of rows. The result will
have cols(x) * cols(y) columns.
8.2.2 Other Matrix Operators
/ Transpose operator
y = x

;
In the expression above the columns of y will contain the same values as the
rows of x and the rows of y will contain the same values as the columns of x.
For complex matrices this computes the complex conjugate transpose.
If an operand immediately follows the transpose operator, the

will be
interpreted as

*. Thus y = x

x is equivalent to y = x

*x.
.

Bookkeeping transpose operator


y = x.

;
This is provided primarily as a matrix handling tool for complex matrices. For
all matrices, the columns of y will contain the same values as the rows of x and
the rows of y will contain the same values as the columns of x. The complex
conjugate transpose is NOT computed when you use .

.
If an operand immediately follows the bookkeeping transpose operator, the .

will be interpreted as .

*. Thus y = x.

x is equivalent to y = x.

*x.
100
O
p
e
r
a
t
o
r
s
8. OPERATORS
| Vertical concatenation
z = x|y;
x =
1 2 3
3 4 5
y = 7 8 9
z =
1 2 3
3 4 5
7 8 9
Horizontal concatenation
z = xy;
x =
1 2
3 4
y =
5 6
7 8
z =
1 2 5 6
3 4 7 8
8.3 Relational Operators
See Section 8.1 for details on how matrix conformability is dened for
element-by-element operators.
Each of these operators has two equivalent representations. Either can be used (e.g., <
or lt), depending only upon preference. The alphabetic form should be surrounded by
spaces.
A third form of these operators has a $ and is used for comparisons between character
data and for comparisons between strings or string arrays. The comparisons are done
byte by byte starting with the lowest addressed byte of the elements being compared.
The equality comparison operators (<=, ==, >=, /=) and their dot equivalents can
be used to test for missing values and the NaN that is created by oating point
exceptions. Less than and greater than comparisons are not meaningful with missings
or NaNs, but equal and not equal will be valid. These operators are sign-insensitive for
missings, NaNs, and zeros.
The string $ versions of these operators can also be used to test missings, NaNs and
zeros. Because they do a strict byte-to-byte comparison, they are sensitive to the sign
101
8. OPERATORS
bit. Missings, NaNs, and zeros can all have the sign bit set to 0 or 1, depending on
how they were generated and have been used in a program.
If the relational operator is NOT preceded by a dot ., then the result is always a
scalar 1 or 0, based upon a comparison of all elements of x and y. All comparisons
must be true for the relational operator to return TRUE.
By this denition, then
if x /= y;
is interpreted as: is every element of x not equal to the corresponding element of y.
To check if two matrices are not identical, use:
if not x == y;
For complex matrices, the ==, /=, .== and ./= operators compare both the real and
imaginary parts of the matrices; all other relational operators compare only the real
parts.
Less than
z = x < y;
z = x lt y;
z = x $< y;
Less than or equal to
z = x <= y;
z = x le y;
z = x $<= y;
Equal to
z = x == y;
z = x eq y;
z = x $== y;
Not equal
z = x /= y;
z = x ne y;
z = x $/= y;
102
O
p
e
r
a
t
o
r
s
8. OPERATORS
Greater than or equal to
z = x >= y;
z = x ge y;
z = x $>= y;
Greater than
z = x > y;
z = x gt y;
z = x $> y;
If the relational operator IS preceded by a dot ., then the result will be a matrix of 1s
and 0s, based upon an element-by-element comparison of x and y.
Element-by-element less than
z = x .< y;
z = x .lt y;
z = x .$< y;
Element-by-element less than or equal to
z = x .<= y;
z = x .le y;
z = x .$<= y;
Element-by-element equal to
z = x .== y;
z = x .eq y;
z = x .$== y;
Element-by-element not equal to
z = x ./= y;
z = x .ne y;
z = x .$/= y;
Element-by-element greater than or equal to
z = x .>= y;
103
8. OPERATORS
z = x .ge y;
z = x .$>= y;
Element-by-element greater than
z = x .> y;
z = x .gt y;
z = x .$> y;
8.4 Logical Operators
The logical operators perform logical or Boolean operations on numeric values. On
input a nonzero value is considered TRUE and a zero value is considered FALSE. The
logical operators return a 1 if TRUE and a 0 if FALSE. Decisions are based on the
following truth table.
Complement
X not X
T F
F T
Conjunction
X Y X and Y
T T T
T F F
F T F
F F F
Disjunction
X Y X or Y
T T T
T F T
F T T
F F F
104
O
p
e
r
a
t
o
r
s
8. OPERATORS
Exclusive Or
X Y X xor Y
T T F
T F T
F T T
F F F
Equivalence
X Y X eqv Y
T T T
T F F
F T F
F F T
For complex matrices, the logical operators consider only the real part of the matrices.
The following operators require scalar arguments. These are the ones to use in if and
do statements.
Complement
z = not x;
Conjunction
z = x and y;
Disjunction
z = x or y;
Exclusive or
z = x xor y;
Equivalence
z = x eqv y;
If the logical operator is preceded by a dot ., the result will be a matrix of 1s and 0s
based upon an element-by-element logical comparison of x and y.
Element-by-element logical complement
z = .not x;
105
8. OPERATORS
Element-by-element conjunction
z = x .and y;
Element-by-element disjunction
z = x .or y;
Element-by-element exclusive or
z = x .xor y;
Element-by-element equivalence
z = x .eqv y;
8.5 Other Operators
Assignment Operator
Assignments are done with one equal sign.
y = 3;
(comma)
Commas are used to delimit lists.
clear x,y,z;
Commas are also used to separate row indices from column indices within brackets.
y = x[3,5];
And to separate arguments of functions within parentheses.
y = momentd(x,d);
(period)
Dots are used in brackets to signify all rows or all columns.
y = x[.,5];
106
O
p
e
r
a
t
o
r
s
8. OPERATORS
(space)
Spaces are used inside of index brackets to separate indices.
y = x[1 3 5,3 5 9];
No extraneous spaces are allowed immediately before or after the comma, or
immediately after the left bracket or before the right bracket.
Spaces are also used in print and lprint statements to separate the separate expressions
to be printed.
print x/2 2*sqrt(x);
Therefore, no extraneous spaces are allowed within expressions in print or lprint
statements unless the expression is enclosed in parentheses.
print (x / 2) (2 * sqrt(x));
(colon)
A colon is used within brackets to create a continuous range of indices.
y = x[1:5,.];
(ampersand)
The (&) ampersand operator will return a pointer to a procedure (proc) or function
(fn). It is used when passing procedures or functions to other functions and for
indexing procedures. See Section 9.5.
String Concatenation
x = "dog";
y = "cat";
z = x $+ y;
print z;
dogcat
107
8. OPERATORS
If the rst argument is of type STRING, the result will be of type STRING. If the rst
argument is of type MATRIX, the result will be of type MATRIX. See the following
examples:
y = 0 $+ "caterpillar";
The result will be a 1x1 matrix containing caterpil.
y = zeros(3,1) $+ "cat";
The result will be a 3x1 matrix, each element containing cat.
If we use the y created above in the following:
k = y $+ "fish";
The result will be a 3x1 matrix with each element containing catsh.
If we then use k created above:
t = "" $+ k[1,1];
The result will be a STRING containing catsh. If we used the same k to create z as
follows:
z = "dog" $+ k[1,1];
The resulting z will be a string containing dogcatsh.
String Array Concatenation
$| vertical string array concatenation.
x = "dog";
y = "fish";
k = x $| y;
print k;
dog
fish
$~ horizontal string array concatenation.
x = "dog";
y = "fish";
k = x $~ y;
print k;
dog fish
108
O
p
e
r
a
t
o
r
s
8. OPERATORS
String Variable Substitution
In a command like the following:
create f1 = olsdat with x,4,2;
by default GAUSS will interpret olsdat as the literal name of the GAUSS data le that
you want to create. It will also interpret x as the literal prex string for the variable
names: x1 x2 x3 x4.
If you want to get the data set name from a string variable, the substitution (^)
operator could be used as follows:
dataset = "olsdat";
create f1 = ^dataset with x,4,2;
If you want to get the data set name from a string variable and the variable names
from a character vector, use the following:
dataset = "olsdat";
vnames = { age, pay, sex };
create f1 = ^dataset with ^vnames,0,2;
The general syntax is:
^variable name
Expressions are not allowed.
The following commands are supported with the substitution operator in the current
version.
create f1 = ^dataset with ^vnames,0,2;
create f1 = ^dataset using ^cmdfile;
open f1 = ^dataset;
output file = ^outfile;
load x = ^datafile;
load path = ^lpath x,y,z,t,w;
loadexe buf = ^exefile;
save ^name = x;
save path = ^spath;
dos ^cmdstr;
run ^prog;
msym ^mstring;
109
8. OPERATORS
8.6 Using Dot Operators with Constants
When you use those operators preceded by a . (the dot operators) with a scalar
integer constant, make sure to put a space between the constant and any following dot
operator. Otherwise, the dot will be interpreted as part of the scalar, i.e., the decimal
point, and you may get results other than you expect. For example:
let y = 1 2 3;
x = 2.<y;
will return x as a scalar 0, not a vector of 0s and 1s, because
x = 2.<y;
is interpreted as
x = 2. < y;
not
x = 2 .< y;
Most of the time, it will be the dot relational (.<, .<=, .==, ./=, .>, .>=) operators
that will trip you up. The same problem can occur with other dot operators, though,
too. For example:
let x = 1 1 1;
y = x./2./x;
will return y as a scalar .5 rather than a vector of .5s, because
y = x./2./x;
is interpreted as
y = (x ./ 2.) / x;
not
y = (x ./ 2) ./ x;
The second division, then, is handled as a matrix division rather than an
element-by-element division.
110
P
r
o
c
e
d
u
r
e
s

a
n
d

K
e
y
w
o
r
d
s
Chapter 9
Procedures and Keywords
Procedures are multiple-line, recursive functions that can have either local or global
variables. Procedures allow a large computing task to be written as a collection of
smaller tasks. These smaller tasks are easier to work with and can hide the details of
their operation from the other parts of the program that do not need to know them.
This makes programs easier to understand and easier to maintain.
A procedure in GAUSS is basically a user-dened function that can be used as if it
were an intrinsic part of the language. They can be as small and simple or as large and
complicated as necessary to perform whatever task you need done. Procedures allow
people to build on their previous work and on the work of others rather than starting
over again and again to perform related tasks.
Any intrinsic command or function may be used in a procedure, as well as any
user-dened function or other procedure. Procedures can refer to any global variable
(that is, any variable that is in the main symbol table and that can be shown with the
show command). It is also possible to declare local variables within a procedure. These
variables are known only inside the procedure they are dened in and cannot be
accessed from other procedures or from the main level program code.
All labels and subroutines inside a procedure are local to that procedure and will not
be confused with labels of the same name in other procedures.
9.1 Dening a Procedure
A procedure denition consists of ve parts, four of which are denoted by explicit
GAUSS commands:
111
9. PROCEDURES AND KEYWORDS
1. Procedure declaration proc statement
2. Local variable declaration local statement
3. Body of procedure
4. Return from procedure retp statement
5. End of procedure denition endp statement
There is always one proc statement and one endp statement in a procedure denition.
Any statements that come between these two statements are part of the procedure.
Procedure denitions cannot be nested. local and retp statements are optional. There
can be multiple local and retp statements in a procedure denition. Here is an example
of a procedure denition:
proc (3) = regress(x, y);
local xxi,b,ymxb,sse,sd,t;
xxi = invpd(xx);
b = xxi * (xy);
ymxb = y-xb;
sse = ymxbymxb/(rows(x)-cols(x));
sd = sqrt(diag(sse*xxi));
t = b./sd;
retp(b,sd,t);
endp;
This could be used as a function that takes two matrix arguments and returns three
matrices as a result. An example of how it might be used is:
{ b,sd,t } = regress(x,y);
The ve parts of the procedure denition will now be discussed in more detail:
9.1.1 Procedure Declaration
The proc statement is the procedure declaration statement. The format is as follows:
proc [[(rets) =]] name([[arg1,arg2,...argN]]);
rets Optional constant, number of values returned by the procedure. Acceptable
values here are 0-1023, the default is 1.
name The name of the procedure, up to 32 alphanumeric characters or an underscore,
beginning with an alpha or an underscore.
arg# Names that will be used inside of the procedure for the arguments that are
passed to the procedure when it is called. There can be 0-1023 arguments.
These names will be known only in the procedure being dened. Other
procedures can use the same names, but they will be separate entities.
112
P
r
o
c
e
d
u
r
e
s

a
n
d

K
e
y
w
o
r
d
s
9. PROCEDURES AND KEYWORDS
9.1.2 Local Variable Declarations
The local statement is used to declare local variables. Local variables are variables
known only to the procedure being dened. The names used in the argument list of the
proc statement are always local. The format of the local statement is:
local x,y,f :proc,g:fn,z,h:keyword;
Local variables can be matrices or strings. If :proc, :fn, or :keyword follows the variable
name in the local statement, the compiler will treat the symbol as if it were a
procedure, function, or keyword respectively. This allows passing procedures, functions,
and keywords to other procedures. See Section 9.4.
Variables that are global to the system (that is, variables that are listed in the global
symbol table and can be shown with the show command) can be accessed by any
procedure without any redundant declaration inside of the procedure. If you want to
create variables that are known only to the procedure being dened, the names of these
local variables must be listed in a local statement. Once a variable name is encountered
in a local statement, further references to that name inside of the procedure will be to
the local rather than to a global having the same name. See clearg, varget, and varput
for ways of accessing globals from within procedures that have locals with the same
name.
The local statement does not initialize (set to a value) the local variables. If they are
not passed in as parameters, they must be assigned some value before they are accessed
or the program will terminate with a Variable not initialized error.
All local and global variables are dynamically allocated and sized automatically during
execution. Local variables, including those that were passed as parameters, can change
in size during the execution of the procedure.
Local variables exist only when the procedure is executing and then disappear. Local
variables cannot be listed with the show command.
The maximum number of locals is limited by stack space and the size of workspace
memory. The limiting factor applies to the total number of active local symbols at any
one time during execution. If cat has 10 locals and it calls dog which has 20 locals,
then there are 30 active locals whenever cat is called. See your supplement for the
maximum number of locals allowed in this implementation.
There can be multiple local statements in a procedure. They will aect only the code
in the procedure that follows. Therefore, for example, it is possible to refer to a global
x in a procedure and follow that with a local statement that declares a local x. In that
case all subsequent references to x would be to the local x. This is not good
programming practice, but it demonstrates the principle that the local statement
aects only the code that is physically below it in the procedure denition. Another
example of this is a symbol that is declared as a local and then declared as a local
procedure or function later in the same procedure denition. This allows doing
arithmetic on local function pointers before calling them, see Section 9.5.
113
9. PROCEDURES AND KEYWORDS
9.1.3 Body of Procedure
The body of the procedure can have any GAUSS statements necessary to perform the
task the procedure is being written for. Other user-dened functions and other
procedures can be referenced as well as any global matrices and strings.
GAUSS procedures are recursive, so the procedure can call itself as long as there is
logic in the procedure to prevent an innite recursion. The process would otherwise
terminate with either an Insucient workspace memory message or a Procedure
calls too deep message, depending on the space necessary to store the locals for each
separate invocation of the procedure.
9.1.4 Returning from the Procedure
The return from the procedure is accomplished with the retp statement.
retp;
retp(expression1,expression2,...expressionN);
The retp statement can have multiple arguments. The number of items returned must
coincide with the number of rets in the proc statement.
If the procedure is being dened with no items returned, then the retp statement is
optional. The endp statement which ends the procedure will generate an implicit retp
with no objects returned. If the procedure returns one or more objects, there must be
an explicit retp statement.
There can be multiple retp statements in a procedure, and they can be anywhere inside
the body of the procedure.
9.1.5 End of Procedure Denition
The endp statement marks the end of the procedure denition.
endp;
An implicit retp statement that returns nothing is always generated here so it is
impossible to run o the end of a procedure without returning. If the procedure was
dened to return one or more objects, then executing this implicit return will result in
a Wrong number of returns error message and the program will terminate.
114
P
r
o
c
e
d
u
r
e
s

a
n
d

K
e
y
w
o
r
d
s
9. PROCEDURES AND KEYWORDS
9.2 Calling a Procedure
Procedures are called like this:
dog(i,j,k); /* no returns */
y = cat(i,j,k); /* one return */
{ x,y,z } = bat(i,j,k); /* multiple returns */
call bat(i,j,k); /* ignore any returns */
Procedures are called in the same way that intrinsic functions are called. The
procedure name is followed by a list of arguments in parentheses. The arguments must
be separated by commas.
If there is to be no return value then use:
proc (0) = dog(x,y,z);
when dening the procedure and use:
dog(ak,4,3);
or
call dog(ak,4,3);
when calling it.
The arguments passed to procedures can be complicated expressions involving calls to
other functions and procedures. This calling mechanism is completely general. For
example:
y = dog(cat(3*x,bird(x,y))-2,1);
is legal.
9.3 Keywords
A keyword, like a procedure, is a subroutine that can be called interactively or from
within a GAUSS program. A keyword diers from a procedure in that a keyword
accepts exactly one string argument, and returns nothing. Keywords can perform many
tasks not as easily accomplished with procedures.
115
9. PROCEDURES AND KEYWORDS
9.3.1 Dening a Keyword
A keyword denition is much like a procedure denition. Keywords always are dened
with 0 returns and 1 argument. The beginning of a keyword denition is the keyword
statement.
keyword name(strarg);
name The name of the keyword, up to 32 alphanumeric characters or an underscore,
beginning with an alpha or an underscore.
strarg Name that will be used inside of the keyword for the argument that is passed to
the keyword when it is called. There is always 1 argument. The name is known
only in the keyword being dened. Other keywords can use the same name, but
they will be separate entities. This will always be a string. If the keyword is
called with no characters following the name of the keyword, this will be a null
string.
The rest of the keyword denition is the same as a procedure denition as in Section 9.1
above. Keywords always return nothing. Any retp statements, if used, should be empty.
retp;
9.3.2 Calling a Keyword
When a keyword is called, every character up to the end of the statement, excluding
the leading spaces, is passed to the keyword as one string argument.
keyword what(str);
print "The argument is: " str "";
endp;
The keyword above will print the string argument passed to it. The argument will be
printed enclosed in single quotes. For example if you type:
what is the argument;
The keyword will respond:
The argument is: is the argument
Here is another example:
116
P
r
o
c
e
d
u
r
e
s

a
n
d

K
e
y
w
o
r
d
s
9. PROCEDURES AND KEYWORDS
keyword add(s);
local tok,sum;
sum = 0;
do until s $== "";
{ tok, s } = token(s);
sum = sum + stof(tok);
endo;
format /rd 1,2;
print "Sum is: " sum;
endp;
To use this keyword, type:
add 1 2 3 4 5;
It will respond with:
Sum is: 15.00
9.4 Passing Procedures to Procedures
Procedures and functions can be passed to procedures in the following way:
proc max(x,y); /* procedure to return maximum */
if x>y;
retp(x);
else;
retp(y);
endif;
endp;
proc min(x,y); /* procedure to return minimum */
if x<y;
retp(x);
else;
retp(y);
endif;
endp;
fn lgsqrt(x) = ln(sqrt(x)); /* function to return
:: log of square root
*/
117
9. PROCEDURES AND KEYWORDS
proc myproc(&f1,&f2,x,y);
local f1:proc, f2:fn, z;
z = f1(x,y);
retp(f2(z));
endp;
The procedure myproc takes 4 arguments. The rst is a procedure f1 that has 2
arguments. The second is a function f2 that has one argument. It also has two other
arguments that must be matrices or scalars. In the local statement, f1 is declared to be
a procedure and f2 is declared to be a function. They can be used inside the procedure
in the usual way. f1 will be interpreted as a procedure inside of myproc, and f2 will be
interpreted as a function. The call to myproc is made as follows:
k = myproc(&max,&lgsqrt,5,7); /* log of square root of 7 */
k = myproc(&min,&lgsqrt,5,7); /* log of square root of 5 */
The ampersand (&) in front of the function or procedure name in the call to myproc
causes a pointer to the function or procedure to be passed. No argument list should
follow the name when it is preceded by the ampersand.
Inside of myproc, the symbol that is declared as a procedure in the local statement is
assumed to contain a pointer to a procedure. It can be called exactly like a procedure is
called. It cannot be saved but it can be passed on to another procedure. If it is to be
passed on to another procedure, use the ampersand in the same way.
9.5 Indexing Procedures
This example assumes there are a set of procedures named f1-f5 which are already
dened. A 1x5 vector procvec is dened by horizontally concatenating pointers to these
procedures. A new procedure, g(x,i ) is then dened which will return the value of the
i
th
procedure evaluated at x:
procvec = &f1 ~ &f2 ~ &f3 ~ &f4 ~ &f5;
proc g(x,i);
local f;
f = procvec[i];
local f:proc;
retp( f(x) );
endp;
Notice that the local statement is used twice. The rst time, f is declared to be a local
matrix. After f has been set equal to the i
th
pointer, f is declared to be a procedure
and is called as a procedure in the retp statement.
118
P
r
o
c
e
d
u
r
e
s

a
n
d

K
e
y
w
o
r
d
s
9. PROCEDURES AND KEYWORDS
9.6 Multiple Returns from Procedures
Procedures can return multiple items, up to 1023. The procedure is dened like this
example of a complex inverse:
proc (2) = cminv(xr,xi); /* (2) specifies number of
:: return values
*/
local ixy, zr, zi;
ixy = inv(xr)*xi;
zr = inv(xr+xi*ixy); /* real part of inverse. */
zi = -ixy*zr; /* imaginary part of inverse. */
retp(zr,zi); /* return: real part, imaginary part */
endp;
It can then be called like this:
{ zr,zi } = cminv(xr,xi);
To make the assignment, the list of targets must be enclosed in braces.
Also, a procedure that returns more than one argument can be used as input to
another procedure or function that takes more than one argument:
proc (2) = cminv(xr,xi);
local ixy, zr, zi;
ixy = inv(xr)*xi;
zr = inv(xr+xi*ixy); /* real part of inverse. */
zi = -ixy*zr; /* imaginary part of inverse. */
retp(zr,zi);
endp;
proc (2) = cmmult(xr,xi,yr,yi);
local zr,zi;
zr = xr*yr-xi*yi;
zi = xr*yi+xi*yr;
retp(zr,zi);
endp;
{ zr,zi } = cminv( cmmult(xr,xi,yr,yi) );
The two returned matrices from cmmult() are passed directly to cminv() in the
statement above. This is equivalent to the following statements:
{ tr,ti } = cmmult(xr,xi,yr,yi);
{ zr,zi } = cminv(tr,ti);
119
9. PROCEDURES AND KEYWORDS
This is completely general so the following program is legal:
proc (2) = cmcplx(x);
local r,c;
r = rows(x);
c = cols(x);
retp(x,zeros(r,c));
endp;
proc (2) = cminv(xr,xi);
local ixy, zr, zi;
ixy = inv(xr)*xi;
zr = inv(xr+xi*ixy); /* real part of inverse. */
zi = -ixy*zr; /* imaginary part of inverse. */
retp(zr,zi);
endp;
proc (2) = cmmult(xr,xi,yr,yi);
local zr,zi;
zr = xr*yr-xi*yi;
zi = xr*yi+xi*yr;
retp(zr,zi);
endp;
{ xr,xi } = cmcplx(rndn(3,3));
{ yr,yi } = cmcplx(rndn(3,3));
{ zr,zi } = cmmult( cminv(xr,xi),cminv(yr,yi) );
{ qr,qi } = cmmult( yr,yi,cminv(yr,yi) );
{ wr,wi } = cmmult(yr,yi,cminv(cmmult(cminv(xr,xi),yr,yi)));
120
L
i
b
r
a
r
i
e
s
Chapter 10
Libraries
The GAUSS library system allows for the creation and maintenance of modular
programs. The user can create libraries of frequently used functions that the GAUSS
system will automatically nd and compile whenever they are referenced in a program.
10.1 Autoloader
The autoloader resolves references to procedures, keywords, matrices, and strings that
are not dened in the program from which they are referenced. The autoloader
automatically locates and compiles the les containing the symbol denitions that are
not resolved during the compilation of the main le. The search path used by the
autoloader is rst the current directory, and then the paths listed in the src path
conguration variable in the order they appear. src path can be dened in the GAUSS
conguration le.
10.1.1 Forward References
When the compiler encounters a symbol that has not previously been dened, that is
called a forward reference. GAUSS handles forward references in two ways, depending
on whether they are left-hand side or right-hand side references.
Left-Hand Side
A left-hand side reference is usually a reference to a symbol on the left-hand side of the
equal sign in an expression.
121
10. LIBRARIES
x = 5;
Left-hand side references, since they are assignments, are assumed to be matrices. In
the statement above, x is assumed to be a matrix and the code is compiled accordingly.
If, at execution time, the expression actually returns a string, the assignment is made
and the type of the symbol x is forced to string.
Some commands are implicit left-hand side assignments. There is an implicit left-hand
side reference to x in each statement below:
clear x;
load x;
open x = myfile;
Right-Hand Side
A right-hand side reference is usually a reference to a symbol on the right-hand side of
the equal sign in an expression.
z = 6;
y = z + dog;
print y;
In the program above, since dog is not previously known to the compiler, the
autoloader will search for it in the active libraries. If it is found, the le containing it
will be compiled. If it is not found in a library, the autoload/autodelete state will
determine how it is handled.
10.1.2 The Autoloader Search Path
If the autoloader is OFF, no forward references are allowed. Every procedure, matrix,
and string referenced by your program must be dened before it is referenced. An
external statement can be used above the rst reference to a symbol, but the denition
of the symbol must be in the main le or in one of the les that are #included. No
global symbols are automatically deleted.
If the autoloader is ON, GAUSS searches for unresolved symbol references during
compilation using a specic search path as outlined below. If the autoloader is OFF, an
Undened symbol error will result for right-hand side references to unknown symbols.
When autoload is ON, the autodelete state controls the handling of references to
unknown symbols. The following search path will be followed to locate any symbols not
previously dened:
122
L
i
b
r
a
r
i
e
s
10. LIBRARIES
Autodelete ON
1. user library
2. User-specied libraries.
3. gauss library
4. Current directory, then src path for les with a .g extension.
Forward references are allowed and .g les need not be in a library. If there are symbols
that cannot be found in any of the places listed above, an Undened symbol error will
be generated and all uninitialized variables and all procedures with global references
will be deleted from the global symbol table. This autodeletion process is transparent
to the user, since the symbols are automatically located by the autoloader the next
time the program is run. This process results in more compile time, which may or may
not be signicant, depending on the speed of the computer and the size of the program.
Autodelete OFF
1. user library
2. User-specied libraries.
3. gauss library
All .g les must be listed in a library. Forward references to symbols that are not listed
in an active library are not allowed. For example:
x = rndn(10,10);
y = sym(x); /* Forward reference to sym */
proc sym(x);
retp(x+x);
endp;
Use an external statement for anything referenced above its denition if autodelete is
OFF.
external proc sym;
x = rndn(10,10);
y = sym(x);
proc sym(x);
retp(x+x);
endp;
When autodelete is OFF, symbols not found in an active library will not be added to
the symbol table. This prevents the creation of uninitialized procedures in the global
symbol table. No deletion of symbols from the global symbol table will take place.
123
10. LIBRARIES
Libraries
The rst place GAUSS looks for a symbol denition is in the active libraries. A
GAUSS library is a text le that serves as a dictionary to the source les that contain
the symbol denitions. When a library is active, GAUSS will look in it whenever it is
looking for a symbol it is trying to resolve. The library statement is used to make a
library active. Library les should be located in the subdirectory listed in the lib path
conguration variable. Library les have a .lcg extension.
Suppose you have several procedures that are all related and you would like to have
them all dened in the same le. You can create such a le, and, with the help of a
library, the autoloader will be able to nd the procedures dened in that le whenever
they are called.
First, create the le that is to contain your desired procedure denitions. By
convention, we usually name these les with an .src extension, but you can use any
name and any le extension you wish. In that le, put all the denitions of related
procedures you wish to use. Here is an example of such a le. It is called norm.src.
/*
** norm.src
**
** This is a file containing the definitions of three
** procedures which return the norm of a matrix x.
** The three norms calculated are the 1-norm, the
** inf-norm and the E-norm.
*/
proc onenorm(x);
retp(maxc(sumc(abs(x))));
endp;
proc infnorm(x);
retp(maxc(sumc(abs(x))));
endp;
proc Enorm(x);
retp(sumc(sumc(x.*x)));
endp;
Next, create a library le that contains the name of the le you want access to, and the
list of symbols dened in it. This can be done with the lib command. See lib in the
COMMAND REFERENCE.
A library le entry has a lename that is ush left. The drive and path can be included
to speed up the autoloader. Indented below the lename are the symbols included in
124
L
i
b
r
a
r
i
e
s
10. LIBRARIES
the le. There can be multiple symbols listed on a line with spaces between. The
symbol type follows the symbol name with a colon delimiting it from the symbol name.
The valid symbol types are:
fn user-dened single line function.
keyword keyword.
proc procedure.
matrix matrix, numeric or character.
string string.
If the symbol type is missing, the colon must not be present and the symbol type is
assumed to be proc. Both library les below are valid.
125
10. LIBRARIES
/*
** math
**
** This library lists files and procedures for mathematical routines.
*/
norm.src
onenorm:proc infnorm:proc Enorm:proc
complex.src
cmmult:proc cmdiv:proc cmadd:proc cmsoln:proc
poly.src
polychar:proc polyroot:proc polymult:proc
/*
** math
**
** This library lists files and procedures for mathematical routines.
*/
c:\gauss\src\norm.src
onenorm : proc
infnorm : proc
Enorm : proc
c:\gauss\src\complex.src
cmmult : proc
cmdiv : proc
cmadd : proc
cmsoln : proc
c:\gauss\src\fcomp.src
feq : proc
fne : proc
flt : proc
fgt : proc
fle : proc
fge : proc
c:\gauss\src\fcomp.dec
_fcmptol : matrix
Once the autoloader nds, via the library, the le containing your procedure denition,
everything in that le will be compiled. For this reason, you will probably want to
combine related procedures in the same le to minimize the compiling of procedures
not needed by your program. In other words, do not combine unrelated functions in
one .src le because if one function in an .src le is needed, the whole le will be
compiled. This does not apply to library (.lcg) les.
126
L
i
b
r
a
r
i
e
s
10. LIBRARIES
user Library
This is a library for user-created procedures. If the autoloader is ON, the user library is
the rst place GAUSS looks when trying to resolve symbol references.
You can update the user library with the lib command as follows:
lib user myfile.src
This will update the user library by adding a reference to myfile.src.
No user library is shipped with GAUSS. It will be created the rst time you use the lib
command to update it.
See the COMMAND REFERENCE for a detailed discussion of the parameters
available with the lib command.
G Files
If autoload and autodelete are ON and a symbol is not found in a library, the
autoloader will assume it is a procedure and look for a le that has the same name as
the symbol and a .g extension. For example, if you have dened a procedure called
square, you could put the denition in a le called square.g on one of the
subdirectories listed in your src path. If autodelete is OFF, the .g le needs to be
listed in an active library, for example, in the user library. See user Library above.
10.2 Global Declaration Files
If your application makes use of several global variables, you will probably want to
create a le containing declare statements. In our code, we use les with the extension
.dec to assign default values to global matrices and strings with declare statements. A
le with an .ext extension containing the same symbols in external statements can
also be created and #included at the top of any le that references these global
variables. An appropriate library le should contain the name of the .dec les and the
names of the globals they declare. The example below demonstrates more specically
how these les work together.
Here is an example that illustrates the way in which .dec, .ext, .lcg and .src les
work together. We always begin the names of global matrices or strings with to
distinguish them easily from procedures.
127
10. LIBRARIES
/*
** fcomp.src
**
** These functions use _fcmptol to fuzz the comparison operations
** to allow for roundoff error.
**
** The statement: y = feq(a,b);
**
** is equivalent to: y = a eq b;
**
** Returns a scalar result, 1 (true) or 0 (false)
**
** y = feq(a,b);
** y = fne(a,b);
*/
#include fcomp.ext;
proc feq(a,b);
retp(abs(a-b) <= _fcmptol);
endp;
proc fne(a,b);
retp(abs(a-b) > _fcmptol);
endp;
/*
** fcomp.dec - global declaration file for fuzzy comparisons.
*/
declare matrix _fcmptol != 1e-14;
/*
** fcomp.ext - external declaration file for fuzzy comparisons.
*/
external matrix _fcmptol;
/*
** fcomp.lcg - fuzzy compare library
128
L
i
b
r
a
r
i
e
s
10. LIBRARIES
*/
fcomp.dec
_fcmptol:matrix
fcomp.src
feq:proc
fne:proc
With the exception of the library (.lcg) les, these les must be located along your
src path. The library les must be on your lib path. With these les in place, the
autoloader will be able to nd everything needed to run the following programs:
library fcomp;
x = rndn(3,3);
xi = inv(x);
xix = xi*x;
if feq(xix,eye(3));
print "Inverse within tolerance.";
else;
print "Inverse not within tolerance.";
endif;
If the default tolerance of 1e 14 is too tight, the tolerance could be relaxed.
library fcomp;
x = rndn(3,3);
xi = inv(x);
xix = xi*x;
_fcmptol = 1e-12; /* reset tolerance */
if feq(xix,eye(3));
print "Inverse within tolerance.";
else;
print "Inverse not within tolerance.";
endif;
10.3 Troubleshooting
Below is a partial list of errors you may encounter in using the library system, followed
by the most probable cause of these errors.
(4) : error G0290 : /gauss/lib/prt.lcg : Library not found
The autoloader is looking for a library le called tt prt.lcg, because it has been
activated in a library statement. Check the subdirectory listed in your lib path
conguration variable for a le called prt.lcg.
129
10. LIBRARIES
(0) : error G0292 : prt.dec : File listed in library not found
The autoloader cant nd a le called prt.dec. Check for this le. It should exist
somewhere along your src path, if you have it listed in prt.lcg.
Undefined symbols:
PRTVEC /gauss/src/tstprt.g(2)
The symbol prtvec could not be found. Check if the le containing prtvec is in the
src path. You may have not activated the library which contains your symbol
denition. Activate the library in a library statement.
/gauss/src/prt.dec(3) : Redefinition of __vnames
(proc)__vnames being declared external matrix
You are trying to illegally force a symbol to another type. You probably have a name
conict that needs to be resolved by renaming one of the symbols.
/gauss/lib/prt.lcg(5) : error G0301 : prt.dec : Syntax error in library
Undefined symbols:
__VNAMES /gauss/src/prt.src(6)
Check your library to see that all lenames are ush left and that all the symbols
dened in that le are indented by at least one space.
10.3.1 Using dec Files
Below is some advice you are encouraged to follow when constructing your own library
system:
Whenever possible, declare variables in a le that contains only declare
statements. When your program is run again without clearing the workspace,
the le containing the variable declarations will not be compiled and declare
warnings will be prevented.
Provide a function containing regular assignment statements to reinitialize the
global variables in your program if they ever need to be reinitialized on the y or
between runs. Put this in a separate le from the declarations.
proc (0) = globset;
_vname = "X";
_con = 1;
_row = 0;
_title = "";
endp;
130
L
i
b
r
a
r
i
e
s
10. LIBRARIES
Never declare any global in more than one le.
Never declare a global more than once in any one le. A global should only be
declared ONCE. By observing this advice, you will avoid meaningless
redenition errors and declare warnings. Redenition error messages and
declare warnings are meant to help you prevent name conicts, and will be
useless to you if your code generates them normally.
The point of the above is to make sure that any declare warnings and redenition
errors you get are meaningful . By knowing that such warnings and errors are
signicant, you will be able to debug your programs more eciently.
131
10. LIBRARIES
132
C
o
m
p
i
l
e
r
Chapter 11
Compiler
GAUSS allows you to compile your large frequently used programs to a le that can be
run over and over with no compile time. The compiled image is usually smaller than
the uncompiled source. This is not a native code compiler; rather, it compiles to a form
of pseudo-code. The le will have a .gcg extension.
The compile command will compile an entire program to a compiled le, or a le can
be compiled directly from the GAUSS editor. An attempt to edit a compiled le will
cause the source code to be loaded into the editor if it is available to the system. The
run command assumes a compiled le if no extension is given and a le with a .gcg
extension is in the src path. A saveall command is available to save the current
contents of memory in a compiled le for instant recall later. The use command will
instantly load a compiled program or set of procedures at the beginning of an ASCII
program before compiling the rest of the ASCII program le.
Since the compiled les are encoded binary les, the compiler is useful for developers
who do not want to distribute their source code.
11.1 Compiling Programs
Programs can be compiled with the compile command or directly from the GAUSS
editor.
11.1.1 Compiling a File
Source code program les that can be run with the run command can be compiled to
.gcg les with the compile command.
133
11. COMPILER
compile qxy.e;
All procedures, global matrices and strings, and the main program segment will be
saved in the compiled le. The compiled le can be run later using the run command.
Any libraries used in the program will need to be present and active during the
compile, but will not need to be present or active when the program is run. If the
program uses the loadexe command, the .rex les will need to be present when the
program is run and the loadexe path will need to be set to the correct subdirectory.
This will usually be automatically handled in your startup le, but should be kept in
mind if the program is run on a dierent computer than it was compiled on.
11.1.2 Compiling from EDIT Mode, DOS Only
Press Alt-X,C to get the Compile Options menu. The compile to le mode (among
other things) can be set here. There are four compile modes:
OFF the compiled program is not saved when the program is executed (default).
ONCE the compiled program is saved when the program is executed and the
compile mode is toggled to OFF.
ON the compiled program will be saved when the program is executed.
ONLY the program will be compiled and saved, but it will not be executed.
Press Alt-X,R to get the Run Options menu. From here, you can select whether to
compile the program with or without line number records. A program compiled with
line number records will be a little slower and 10-20% larger than it would be if
compiled without line number records.
When you run the program by pressing F2 or Alt-X,X, a compiled version of the
program will be saved on the same subdirectory the source is located on.
If you use the compile ON or ONLY option, dont forget to turn it o or you will be
creating lots of compiled les you dont want.
11.2 Saving the Current Workspace
The simplest way to create a compiled le containing a set of frequently used
procedures is to use saveall and an external statement.
library pgraph;
external proc xy,logx,logy,loglog,hist;
saveall pgraph;
134
C
o
m
p
i
l
e
r
11. COMPILER
Just list the procedures you will be using in an external statement and follow it with a
saveall statement. You do not need to list procedures that you do not explicitly call
but are called from another procedure because the autoloader will nd them
automatically before the saveall command is executed. You also do not need to be
exhaustive in listing every procedure you will be calling unless the source will not be
available when the compiled le is used.
Remember that the list of active libraries is NOT saved in the compiled le so you may
still need a library statement in a program that is useing a compiled le.
11.3 Debugging
If you are using compiled code in a development situation where debugging is
important, you should compile the le with line number records. After the development
is over you can recompile without line number records if the maximum possible
execution speed is important. If you want to guarantee that all procedures contain line
number records, put a new statement at the top of your program and turn line number
tracking on.
135
11. COMPILER
136
F
i
l
e

I
/
O
Chapter 12
File I/O
Following is a partial list of the I/O commands in the GAUSS programming language.
close close a le.
closeall close all open les.
colsf number of columns in a le.
create create GAUSS data set.
dfree space remaining on disk.
eof test for end of le.
fcheckerr check error status of a le.
fclearerr check error status of a le and clear error ag.
ush ush a les output buer.
fgets read a line of text from a le.
fgetsa read multiple lines of text from a le.
fgetsat read multiple lines of text from a le, discarding newlines.
fgetst read a line of text from a le, discarding newline.
leinfo returns names and info of les matching a specication.
les returns a list of les matching a specication.
lesa returns a list of les matching a specication.
fopen open a le.
fputs write strings to a le.
fputst write strings to a le, appending newlines.
fseek reposition le pointer.
fstrerror get explanation of last le I/O error.
ftell get position of le pointer.
getf load a le into a string.
getname get variable names from data set.
137
12. FILE I/O
iscplxf returns whether a data set is real or complex.
load load matrix le or small ASCII le (same as loadm).
loadd load a small GAUSS data set into a matrix.
loadm load matrix le or small ASCII le.
loads load string le.
open open a GAUSS data set.
output control printing to an auxiliary output le or device.
readr read a specied number of rows from a le.
rowsf number of rows in le.
save save matrices, strings, procedures.
saved save a matrix in a GAUSS data set.
seekr reset read/write pointer in a data set.
sortd sort a data set.
typef get type of data set (bytes per element).
writer write data to a data set.
12.1 ASCII Files
GAUSS has facilities for reading and writing ASCII les. Most other software can also
read and write ASCII les so this provides a way of sharing data between GAUSS and
many other kinds of programs.
12.1.1 Matrix Data
Reading
Files containing numeric data that are delimited with spaces or commas and are small
enough to t into a single matrix or string can be read with load. Larger ASCII data
les can be converted to GAUSS data sets with the atog utility program which is
documented in the UTILITIES section of this manual. atog can convert packed ASCII
les as well as delimited les.
For small delimited data les, the load statement can be used to load the data directly
into a GAUSS matrix. The limit here is that the resulting GAUSS matrix must be no
larger than the limit for a single matrix.
load x[] = dat1.asc;
This will load the data in the le dat1.asc into an Nx1 matrix x. This is the preferred
method because rows(x) can be used to determine how many elements were actually
loaded and the matrix can be reshaped to the desired form.
138
F
i
l
e

I
/
O
12. FILE I/O
load x[] = dat1.asc;
if rows(x) eq 500;
x = reshape(x,100,5);
else;
errorlog "Read Error";
end;
endif;
For quick interactive loading without error checking you can use:
load x[100,5] = dat1.asc;
This will load the data into a 100x5 matrix. If there are more or fewer than 500
numbers in the data set, the matrix will be automatically reshaped to 100x5.
Writing Using Auxiliary Output
To write data to an ASCII le the print or printfm commands are used to print to the
auxiliary output. The resulting les are standard ASCII les, and can be edited with
GAUSSs editor or another text editor.
The output and outwidth commands are used to control the auxiliary output. print or
printfm commands are used to control what is sent to the output le.
The screen can be turned on and o using screen. When printing a large amount of
data to the auxiliary output, the screen can be turned o using the command:
screen off;
This will speed things up considerably, especially if the auxiliary output is a disk le.
It is easy to forget to turn the screen on again, and you may think your computer is
broken. It is therefore good practice to use the end statement to terminate your
programs. end will automatically perform screen on and output o.
The following commands can be used to control printing to the auxiliary output:
format controls format for printing a matrix.
output open, close, rename auxiliary output le or device.
outwidth auxiliary output width.
printfm formatted matrix print.
print print matrix or string.
screen Turn printing to the screen on and o.
The following example illustrates printing a matrix to a le:
139
12. FILE I/O
format /rd 8,2;
outwidth 132;
output file = myfile.asc reset;
screen off;
print x;
output off;
screen on;
The numbers in the matrix x will be printed with a eld width of 8 spaces per number,
and with 2 places beyond the decimal point. The resulting le will be an ASCII data
le. It will have 132 column lines maximum.
A more extended example is given below. This program will write the contents of the
GAUSS le mydata.dat into an ASCII le called mydata.asc. If there were an existing
le by the name of mydata.asc, it would be overwritten:
output file = mydata.asc reset;
screen off;
format /rd 1,8;
open fp = mydata;
do until eof(fp);
print readr(fp,200);;
endo;
fp = close(fp);
end;
The output ... reset command will create an auxiliary output le called mydata.asc to
receive the output. The screen is turned o to speed up the process. The GAUSS data
le mydata.dat is opened for read and 200 rows will be read per iteration until the end
of the le is reached. The data that are read will be printed to the auxiliary output
mydata.asc only, because the screen is o.
12.1.2 General File I/O
getf will read a le and return it in a string variable. Any kind of le can be read in
this way as long as it will t into a single string variable.
To read les sequentially, use fopen to open the le and use fgets, fputs and associated
functions to read and write the le. The current position in a le can be determined
with ftell. The procedure below uses these functions to copy an ASCII text le.
proc copy(src, dest);
local fin, fout, str;
140
F
i
l
e

I
/
O
12. FILE I/O
fin = fopen(src, "rb");
if not fin;
retp(1);
endif;
fout = fopen(dest, "wb");
if not fin;
call close(fin);
retp(2);
endif;
do until eof(fin);
str = fgets(fin, 1024);
if fputs(fout, str) /= 1;
call close(fin);
call close(fout);
retp(3);
endif;
endo;
call close(fin);
call close(fout);
retp(0);
endp;
12.2 Data Sets
GAUSS data sets are the preferred method of storing data for use within GAUSS. Use
of these data sets allows extremely fast reading and writing of data. Many library
functions are designed to read data from these data sets.
12.2.1 Layout
GAUSS data sets are arranged as matrices. That is, they are organized in terms of
rows and columns. The columns in a data le are assigned names, and these names are
stored in the header, or in the case of the v89 format, in a separate header le.
The limit on the number of rows in a GAUSS data set is determined by disk size. The
limit on the number of columns is listed in your supplement. Data can be stored in 2,
4, or 8 bytes per number, rather than just 8 bytes as in the case of GAUSS matrix les.
141
12. FILE I/O
The ranges of the dierent formats is as follows:
Bytes Type Significant Range
Digits
2 integer 4 32768 <= X <= 32767
4 single 6 7 8.43E 37 <= [X[ <= 3.37E +38
8 double 15 16 4.19E 307 <= [X[ <= 1.67E +308
12.2.2 Creating Data Sets
Data sets can be created with the create command. The names of the columns, the
type of data, etc., can be specied. See create in the COMMAND REFERENCE for
complete details.
Data sets, unlike matrices, cannot change from real to complex or vice-versa. Data sets
are always stored a row at a time. The rows of a complex data set, then, have the real
and imaginary parts interleaved, element by element. For this reason, you cannot write
rows from a complex matrix to a real data setthere is no way to interleave the data
without rewriting the whole data set. If you need to do so, explicitly convert the rows
of data rst using the real and imag functions (see the COMMAND REFERENCE),
then write them to the data set. Rows from a real matrix CAN be written to a complex
data set; GAUSS simply supplies 0s for the imaginary part.
To create a complex data set, include the complex ag in your create command.
12.2.3 Reading and Writing
The basic functions in GAUSS for reading data les are open and readr:
open f1 = dat1;
x = readr(f1,100);
The readr function here will read in 100 rows from dat1.dat. The data will be
assigned to a matrix x.
loadd and saved can be used for loading and saving small data sets.
The following code illustrates the creation of a GAUSS data le by merging
(horizontally concatenating) two existing data sets:
file1 = "dat1";
file2 = "dat2";
142
F
i
l
e

I
/
O
12. FILE I/O
outfile = "daty";
open fin1 = ^file1 for read;
open fin2 = ^file2 for read;
varnames = getname(file1)|getname(file2);
otyp = maxc(typef(fin1)|typef(fin2));
create fout = ^outfile with ^varnames,0,otyp;
nr = 400;
do until eof(fin1) or eof(fin2);
y1 = readr(fin1,nr);
y2 = readr(fin2,nr);
r = maxc(rows(y1)|rows(y2));
y = y1[1:r,.] ~ y2[1:r,.];
call writer(fout,y);
endo;
closeall fin1,fin2,fout;
In this example, data sets dat1.dat and dat2.dat are opened for reading. The
variable names from each data set are read using getname and combined in a single
vector called varnames. A variable called otyp is created which will be equal to the
larger of the two data types of the input les. This will insure that the output is not
rounded to less precision than the input les. A new data set daty.dat is created using
the create ... with ... command. Then, on every iteration of the loop, 400 rows are
read in from each of the two input data sets, horizontally concatenated, and written
out to daty.dat. When the end of one of the input les is reached, reading and writing
will stop. The closeall command is used to close all the les.
12.2.4 Distinguishing Character and Numeric Data
Although GAUSS itself does not distinguish between numeric and character columns in
a matrix or data set, some of the GAUSS Application programs do, so it is important
when creating a data set to indicate the type of data in the various columns. The
following discusses two ways of doing this.
Using Type Vectors
The v89 data set format distinguished between character and numeric data in data sets
by the case of the variable names associated with the columns. The v96 data set
format, however, stores this type information separately, resulting in a much cleaner
and more robust method of tracking variable types, and greater freedom in the naming
of data set variables.
When you create a data set, you can supply a vector indicating the type of data in each
column of the data set. For example:
143
12. FILE I/O
data = { M 32 21500,
F 27 36000,
F 28 19500,
M 25 32000 };
vnames = { "Sex" "Age" "Pay" };
vtypes = { 0 1 1 };
create f = mydata with ^vnames, 3, 8, vtypes;
call writer(f,data);
f = close(f);
To retrieve the type vector you use vartypef.
open f = mydata for read;
vn = getnamef(f);
vt = vartypef(f);
print vn;
print vt;
Sex Age Pay
0 1 1
Note that the function getnamef in this example returns a string array rather than a
character vector, so you can print it without the $ prex.
Using the Uppercase/Lowercase Convention
The following method for distinguishing character/numeric data is in the process of
being obsoleted; you should use the approach described above.
To distinguish numeric variables from character variables in GAUSS data sets, some
GAUSS Application programs recognize an uppercase/lowercase convention: if the
variable name is uppercase, the variable is assumed to be numeric, and if it is
lowercase, the variable is assumed to be character. The atog utility program
implements this convention when you use the # and $ operators to toggle between
character and numeric variable names listed in the invar statement and you have
specied nopreservecase.
It should be remembered that GAUSS does not make this distinction internally and it
is up to the program to keep track of and make use of the information recorded in the
case of the variable names in a data set.
When creating a data set using the saved command, this convention can be established
as follows:
144
F
i
l
e

I
/
O
12. FILE I/O
data = { M 32 21500,
F 27 36000,
F 28 19500,
M 25 32000 };
dataset = "mydata";
vnames = { "sex" AGE PAY };
call saved(data,dataset,vnames);
It is necessary to put sex into quotes in order to prevent it from being forced to
uppercase.
The procedure getname can be used to retrieve the variable names:
print $getname("mydata");
The names are:
sex
AGE
PAY
When you are writing or creating a data set (as the above example using saved does)
the case of the variable names is important. This is especially true if the GAUSS
Applications programs will be used on the data set.
12.3 Matrix Files
GAUSS matrix les are les created by the save command.
The save command takes a matrix in memory, adds a header that contains information
on the number of rows and columns in the matrix, and stores it on disk. Numbers are
stored in double precision just as they are in matrices in memory. These les have the
extension .fmt.
Matrix les can be no larger than a single matrix. No variable names are associated
with matrix les.
GAUSS matrix les can be loaded into memory using the load or loadm commands or
they can be opened with the open command and read with the readr command. With
the readr command a subset of the rows can be read. With the load command, the
entire matrix is loaded.
GAUSS matrix les can be opened for read, but not for append, or for update.
If a matrix le has been opened and assigned a le handle, rowsf and colsf can be used
to determine how many rows and columns it has without actually reading it into
memory. seekr and readr can be used to jump to particular rows and to read them into
memory. This can be useful when only a subset of rows is needed at any time. This
procedure will save memory and can be much faster than loading the entire matrix
into memory.
145
12. FILE I/O
12.4 File Formats
This section discusses the GAUSS binary le formats.
There are 4 currently supported matrix le formats:
Version Extension Support
Small Matrix v89 .fmt Obsolete, read on Intel x86 processors only
Extended Matrix v89 .fmt Obsolete, read on Intel only
Matrix v92 .fmt Obsolete, read on Unix only
Universal Matrix v96 .fmt Supported for read/write
There are 4 currently supported string le formats:
Version Extension Support
Small String v89 .fst Obsolete, read on Intel x86 processors only
Extended String v89 .fst Obsolete, read on Intel only
String v92 .fst Obsolete, read on Unix only
Universal String v96 .fst Supported for read/write
There are 4 currently supported data set formats:
Version Extension Support
Small Data Set v89 .dat, .dht Obsolete, read on Intel x86 processors only
Extended Data Set v89 .dat, .dht Obsolete, read on Intel only
Data Set v92 .dat Obsolete, read on Unix only
Universal Data Set v96 .dat Supported for read/write
12.4.1 Small Matrix v89
Matrix les are binary les, and cannot be read with a text editor. They are created
with save. Matrix les have a .fmt extension and a 16-byte header formatted as
follows:
oset description
0-1 DDDD hex, identication ag
2-3 rows, unsigned 2-byte integer
4-5 columns, unsigned 2-byte integer
6-7 size of le minus 16-byte header, unsigned 2-byte integer
8-9 type of le, 0086 hex for real matrices, 8086 hex for complex matrices
10-15 reserved, all 0s
146
F
i
l
e

I
/
O
12. FILE I/O
The body of the le starts at oset 16 and consists of IEEE format double precision
oating point numbers or character elements of up to 8 characters. Character elements
take up 8 bytes and are padded on the right with zeros. The size of the body of the le
is 8*rows*cols rounded up to the next 16-byte paragraph boundary. Numbers are
stored row by row. A 2x3 real matrix will be stored on disk in the following way from
the lowest addressed element to the highest addressed element:
[1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
For complex matrices, the size of the body of the le is 16*rows*cols. The entire real
part of the matrix is stored rst, then the entire imaginary part. A 2x3 complex matrix
will be stored on disk in the following way from the lowest addressed element to the
highest addressed element:
(real part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
(imaginary part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]
12.4.2 Extended Matrix v89
In older 32-bit versions, matrices with more than 8190 elements were saved in a format
that cannot be read by the 16-bit version. These extended les have a 16-byte header
formatted as follows:
oset description
0-1 EEDD hex, identication ag
2-3 type of le, 0086 hex for real matrices, 8086 hex for complex matrices
4-7 rows, unsigned 4-byte integer
8-11 columns, unsigned 4-byte integer
12-15 size of le minus 16-byte header, unsigned 4-byte integer
The size of the body of an extended matrix le is 8*rows*cols (not rounded up to a
paragraph boundary). Aside from this, the dierences in the le header, and the
number of elements allowed in the le, extended matrix les conform to the matrix le
description specied above.
12.4.3 Small String v89
String les are created with save. String les have a 16-byte header formatted as
follows:
oset description
0-1 DFDF hex, identication ag
2-3 1, unsigned 2-byte integer
4-5 length of string plus null byte, unsigned 2-byte integer
6-7 size of le minus 16-byte header, unsigned 2-byte integer
8-9 001D hex, type of le
10-15 reserved, all 0s
147
12. FILE I/O
The body of the le starts at oset 16. It consists of the string terminated with a null
byte. The size of the le is the 16-byte header plus the length of the string and null
byte rounded up to the next 16-byte paragraph boundary.
12.4.4 Extended String v89
In the 32-bit version, strings with more than 65519 characters are saved in a format
that cannot be read by the 16-bit version. These extended les have a 16-byte header
formatted as follows:
oset description
0-1 EEDF hex, identication ag
2-3 001D hex, type of le
4-7 1, unsigned 4-byte integer
8-11 length of string plus null byte, unsigned 4-byte integer
12-15 size of le minus 16-byte header, unsigned 4-byte integer
The body of the le starts at oset 16. It consists of the string terminated with a null
byte. The size of the le is the 16-byte header plus the length of the string and null
byte rounded up to the next 8-byte boundary.
12.4.5 Small Data Set v89
The .dat le is used with the .dht descriptor le. The format of the .dat le is binary
data. It will be in one of three types:
8-byte IEEE oating point
4-byte IEEE oating point
2-byte signed binary integer, twos complement
Numbers are stored row by row.
The .dht le is used in conjunction with the .dat le as a descriptor le and as a place
to store names for the columns in the .dat le. Its format is as follows:
oset description
0-1 DADA hex, identication ag
2-5 reserved, all 0s
6-7 columns, unsigned 2-byte integer
8-9 row size in bytes, unsigned 2-byte integer
10-11 header size in bytes, unsigned 2-byte integer
12-13 data type in .dat le (2 4 8), unsigned 2-byte integer
14-17 reserved, all 0s
18-21 reserved, all 0s
22-23 control ags, unsigned 2-byte integer
24-127 reserved, all 0s
148
F
i
l
e

I
/
O
12. FILE I/O
Column names begin at oset 128 and are stored 8 bytes each in ASCII format. Names
with less than 8 characters are padded on the right with bytes of 0.
The number of rows in the .dat le is calculated in GAUSS using the le size, columns,
and data type. This means that users can modify the .dat le by adding or deleting
rows with other software without updating the header information.
Names for the columns should be lowercase for character data if you want to be able to
distinguish them from numeric data with vartype.
GAUSS currently examines only the 4s bit of the control ags. This bit is set to 0 for
real data sets, 1 for complex data sets. All other bits are 0.
Data sets are always stored a row at a time. A real data set with 2 rows and 3 columns
(not an overlarge data set!) will be stored on disk in the following way from the lowest
addressed element to the highest addressed element:
[1, 1] [1, 2] [1, 3]
[2, 1] [2, 2] [2, 3]
The rows of a complex data set are stored with the real and imaginary parts
interleaved, element by element. A 2x3 complex data set, then, will be stored on disk in
the following way from the lowest addressed element to the highest addressed element:
[1, 1]r [1, 1]i [1, 2]r [1, 2]i [1, 3]r [1, 3]i
[2, 1]r [2, 1]i [2, 2]r [2, 2]i [2, 3]r [2, 3]i
12.4.6 Extended Data Set v89
In the 32-bit version, data sets with more than 8175 columns are saved in a format that
cannot be read by the 16-bit version. These extended les have a .dht descriptor le
formatted as follows:
oset description
0-1 EEDA hex, identication ag
2-3 data type in .dat le (2 4 8), unsigned 2-byte integer
4-7 reserved, all 0s
8-11 columns, unsigned 4-byte integer
12-15 row size in bytes, unsigned 4-byte integer
16-19 header size in bytes, unsigned 4-byte integer
20-23 reserved, all 0s
24-27 reserved, all 0s
28-29 control ags, unsigned 2-byte integer
30-127 reserved, all 0s
Aside from the dierences in the descriptor le and the number of columns allowed in
the data le, extended data sets conform to the v89 data set description specied above.
149
12. FILE I/O
12.4.7 Matrix v92
oset description
0-3 always 0
4-7 always 0xEECDCDCD
8-11 reserved
12-15 reserved
16-19 reserved
20-23 0 - real matrix, 1 - complex matrix
24-27 number of dimensions
0 - scalar
1 - row vector
2 - column vector, matrix
28-31 header size, 128 + number of dimensions
* 4, padded to 8-byte boundary
32-127 reserved
If the data is a scalar, the data will directly follow the header.
If the data is a row vector, an unsigned integer equaling the number of columns in the
vector will precede the data, along with 4 padding bytes.
If the data is a column vector or a matrix, there will be two unsigned integers preceding
the data. The rst will represent the number of rows in the matrix and the second will
represent the number of columns.
The data area always begins on an even 8-byte boundary. Numbers are stored in
double precision (8 bytes per element, 16 if complex). For complex matrices, all of the
real parts are stored rst, followed by all imaginary parts.
12.4.8 String v92
oset description
0-3 always 0
4-7 always 0xEECFCFCF
8-11 reserved
12-15 reserved
16-19 reserved
20-23 size of string in units of eight bytes
24-27 length of string plus null terminator in bytes
28-127 reserved
The size of the data area is always divisible by 8, and is padded with nulls if the length
of the string is not evenly divisible by 8. If the length of the string is evenly divisible by
8 the data area will be the length of the string plus 8. The data area follows
immediately after the 128-byte header.
150
F
i
l
e

I
/
O
12. FILE I/O
12.4.9 Data Set v92
oset description
0-3 always 0
4-7 always 0xEECACACA
8-11 reserved
12-15 reserved
16-19 reserved
20-23 rows in data set
24-27 columns in data set
28-31 0 for real data set, 1 for complex data set
32-35 type of data in data set, 2, 4, or 8
36-39 header size in bytes is 128 + columns * 9
40-127 reserved
The variable names begin at oset 128 and are stored 8 bytes each in ASCII format.
Each name corresponds to one column of data. Names less than 8 characters are
padded on the right with bytes of zero.
The variable type ags immediately follow the variable names. They are 1-byte binary
integers, one per column, padded to an even 8-byte boundary. A 1 indicates a numeric
variable and a 0 indicates a character variable.
The contents of the data set follow the header and start on an 8-byte boundary. Data is
either 2-byte signed integer, 4-byte single precision oating point or 8-byte double
precision oating point.
151
12. FILE I/O
12.4.10 Matrix v96
oset description
0-3 always 0xFFFFFFFF
4-7 always 0
8-11 always 0xFFFFFFFF
12-15 always 0
16-19 always 0xFFFFFFFF
20-23 0xFFFFFFFF for forward byte order, 0 for backward byte order
24-27 0xFFFFFFFF for forward bit order, 0 for backward bit order
28-31 always 0xABCDEF01
32-35 currently 1
36-39 reserved
40-43 oating point type, 1 for IEEE 754
44-47 1008 (double precision data)
48-51 8, the size in bytes of a double matrix
52-55 0 for real matrix, 1 for complex matrix
56-59 1 - imaginary part of matrix follows real part (standard GAUSS style)
2 - imaginary part of each element immediately follows real part
(FORTRAN style)
60-63 number of dimensions
0 scalar
1 row vector
2 column vector or matrix
64-67 1 for row major ordering of elements, 2 for column major
68-71 always 0
72-75 header size, 128 + dimensions * 4, padded to 8-byte boundary
76-127 reserved
If the data is a scalar, the data will directly follow the header.
If the data is a row vector, an unsigned integer equaling the number of columns in the
vector will precede the data, along with 4 padding bytes.
If the data is a column vector or a matrix, there will be two unsigned integers preceding
the data. The rst will represent the number of rows in the matrix and the second will
represent the number of columns.
The data area always begins on an even 8-byte boundary. Numbers are stored in
double precision (8 bytes per element, 16 if complex). For complex matrices, all of the
real parts are stored rst, followed by all the imaginary parts.
152
F
i
l
e

I
/
O
12. FILE I/O
12.4.11 Data Set v96
oset description
0-3 always 0xFFFFFFFF
4-7 always 0
8-11 always 0xFFFFFFFF
12-15 always 0
16-19 always 0xFFFFFFFF
20-23 0xFFFFFFFF for forward byte order, 0 for backward byte order
24-27 0xFFFFFFFF for forward bit order, 0 for backward bit order
28-31 0xABCDEF02
32-35 version, currently 1
36-39 reserved
40-43 oating point type, 1 for IEEE 754
44-47 12 for signed 2-byte integer
1004 for single precision oating point
1008 for double precision oat
48-51 2, 4, or 8, the size of an element in bytes
52-55 0 for real matrix, 1 for complex matrix
56-59 1 - imaginary part of matrix follows real part (standard GAUSS style)
2 - imaginary part of each element immediately follows real part
(FORTRAN style)
60-63 always 2
64-67 1 for row major ordering of elements, 2 for column major
68-71 always 0
72-75 header size, 128 + columns * 33, padded to 8-byte boundary
76-79 reserved
80-83 rows in data set
84-87 columns in data set
88-127 reserved
The variable names begin at oset 128 and are stored 32 bytes each in ASCII format.
Each name corresponds to one column of data. Names less than 32 characters are
padded on the right with bytes of zero.
The variable type ags immediately follow the variable names. They are 1-byte binary
integers, one per column, padded to an even 8-byte boundary. A 1 indicates a numeric
variable and a 0 indicates a character variable.
Contents of the data set follow the header and start on an 8-byte boundary. Data is
either 2-byte signed integer, 4-byte single precision oating point or 8-byte double
precision oating point.
153
12. FILE I/O
154
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
Chapter 13
Data Transformations
GAUSS allows expressions that directly reference variables (columns) of a data set.
This is done within the context of a data loop.
dataloop infile outfile;
drop wagefac wqlec shordelt foobly;
csed = ln(sqrt(csed));
select csed > 0.35 and married $== "y";
make chfac = hcfac + wcfac;
keep csed chfac stid recsum voom;
endata;
GAUSS translates the data loop into a procedure that does the required operations and
then calls the procedure automatically at the location (in your program) of the data
loop. It does this by translating your main program le into a temporary le and then
executing the temporary le.
A data loop may be placed only in the main program le. Data loops in les that are
#included or autoloaded are not recognized.
13.1 Data Loop Statements
A data loop begins with a dataloop statement and ends with an endata statement.
Inside of a data loop, the following statements are supported:
155
13. DATA TRANSFORMATIONS
code create variable based on a set of logical expressions.
delete delete rows (observations) based on a logical expression.
drop specify variables NOT to be written to data set.
extern allows access to matrices and strings in memory.
keep specify variables to be written to output data set.
lag lag variables a number of periods.
listwise controls deletion of missing values.
make create new variable.
outtyp specify output le precision.
recode change variable based on a set of logical expressions.
select select rows (observations) based on a logical expression.
vector create new variable from a scalar returning expression.
In any expression inside of a data loop, all text symbols not immediately followed by a
left parenthesis ( are assumed to be data set variable (column) names. Text symbols
followed by a left parenthesis are assumed to be procedure names. Any symbol listed in
an extern statement is assumed to be a matrix or string already in memory.
13.2 Using Other Statements
All program statements in the main le and not inside of a data loop are passed
through to the temporary le without modication. Program statements within a data
loop that are preceded by a # are passed through to the temporary le without
modication. The adept user who is familiar with the code generated in the temporary
le can use this to do out-of-the-ordinary operations inside the data loop.
13.3 Debugging Data Loops
The translator that processes data loops can be turned on and o. When the translator
is on, there are three distinct phases in running a program.
Translation translation of main program le to temporary le.
Compilation compilation of temporary le.
Execution execution of compiled code.
13.3.1 Translation Phase
In the translation phase, the main program le is translated into a temporary le. Each
data loop is translated into a procedure and a call to this procedure is placed in the
156
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
13. DATA TRANSFORMATIONS
temporary le at the same location as the original data loop. The data loop itself is
commented out in the temporary le. All the data loop procedures are placed at the
end of the temporary le.
Depending upon the status of line number tracking, error messages encountered in this
phase will be printed with the le name and line numbers corresponding to the main
le.
13.3.2 Compilation Phase
In the compilation phase, the temporary le $xrun$.tmp is compiled. Depending upon
the status of line number tracking, error messages encountered in this phase will be
printed with the le name and line numbers corresponding to both the main le and
the temporary le.
13.3.3 Execution Phase
In the execution phase, the compiled program is executed and error messages will
include line number references from both the original le and the temporary le,
depending upon the status of line number tracking.
13.4 Reserved Variables
The following local variables are created by the translator and used in the produced
code:
x cv x iptr x ncol x plag
x drop x keep x nlag x ptrim
x fpin x lval x nrow x shft
x fpout x lvar x ntrim x tname
x i x n x out x vname
x in x name x outtyp x x
These variables are reserved, and should not be used within a dataloop... endata
section.
157
13. DATA TRANSFORMATIONS
158
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
Chapter 14
Data Loop Reference
159
code 14. DATA LOOP REFERENCE
Purpose
Creates new variables with dierent values based on a set of logical expressions.
Format
code [[#]] [[$]] var [[default defval ]] with
val 1 for expression 1,
val 2 for expression 2,
.
.
.
val n for expression n;
Input
var literal, the new variable name.
defval scalar, the default value if none of the expressions are TRUE.
val scalar, value to be used if corresponding expression is TRUE.
expression logical scalar-returning expression that returns nonzero TRUE or zero
FALSE.
Remarks
If $ is specied, the new variable will be considered a character variable. If # or
nothing is specied, the new variable will be considered numeric.
The logical expressions must be mutually exclusive, i.e., only one may return TRUE for
a given row (observation).
Any variables referenced must already exist, either as elements of the source data set,
as externs, or as the result of a previous make, vector, or code statement.
If no default value is specied, 999 is used.
Example
code agecat default 5 with
1 for age < 21,
2 for age >= 21 and age < 35,
3 for age >= 35 and age < 50,
4 for age >= 50 and age < 65;
code $ sex with
"MALE" for gender == 1,
"FEMALE" for gender == 0;
See also
recode
160
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE dataloop
Purpose
Species the beginning of a data loop.
Format
dataloop inle outle;
Input
inle string variable or literal, the name of the source data set.
Output
outle string variable or literal, the name of the output data set.
Remarks
The statements between the dataloop... endata commands are assumed to be
metacode to be translated at compile time. The data from inle is manipulated by the
specied statements, and stored to the data set outle. Case is not signicant within
the dataloop... endata section, except for within quoted strings. Comments can be
used as in any GAUSS code.
Example
src = "source";
dataloop ^src dest;
make newvar = x1 + x2 + log(x3);
x6 = sqrt(x4);
keep x6, x5, newvar;
endata;
Here, src is a string variable requiring the caret (^) operator, while dest is a string
literal.
161
delete 14. DATA LOOP REFERENCE
Purpose
Removes specic rows in a data loop based on a logical expression.
Format
delete logical expression;
Remarks
Deletes only those rows for which logical expression is TRUE. Any variables referenced
must already exist, either as elements of the source data set, as externs, or as the result
of a previous make, vector, or code statement.
GAUSS expects logical expression to return a row vector of 1s and 0s. The relational
and other operators (e.g. <) are already interpreted in terms of their dot equivalents
(. <), but it is up to the user to make sure that function calls within logical expression
result in a vector.
Example
delete age < 40 or sex == FEMALE;
See also
select
162
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE drop
Purpose
Species columns to be dropped from the output data set in a data loop.
Format
drop variable list;
Remarks
Commas are optional in variable list.
Deletes the specied variables from the output data set. Any variables referenced must
already exist, either as elements of the source data set, or as the result of a previous
make, vector, or code statement.
If neither keep nor drop is used, the output data set will contain all variables from the
source data set, as well as any dened variables. The eects of multiple keep and drop
statements are cumulative.
Example
drop age, pay, sex;
See also
keep
163
extern 14. DATA LOOP REFERENCE
Purpose
Allows access to matrices or strings in memory from inside a data loop.
Format
extern variable list;
Remarks
Commas in variable list are optional.
extern tells the translator not to generate local code for the listed variables, and not to
assume they are elements of the input data set.
extern statements should be placed before any reference to the symbols listed. The
specied names should not exist in the input data set, or be used in a make statement.
Example
This example shows how to assign the contents of an external vector to a new variable
in the data set, by iteratively assigning a range of elements to the variable. The
reserved variable x x contains the data read from the input data set on each iteration.
The external vector must have at least as many rows as the data set.
base = 1; /* used to index a range of elements from exvec */
dataloop oldata newdata;
extern base, exvec;
make ndvar = exvec[seqa(base,1,rows(x_x))];
# base = base + rows(x_x); /* execute command literally */
endata;
164
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE keep
Purpose
Species columns (variables) to be saved to the output data set in a data loop.
Format
keep variable list;
Remarks
Commas are optional in variable list.
Retains only the specied variables in the output data set. Any variables referenced
must already exist, either as elements of the source data set, or as the result of a
previous make, vector, or code statement.
If neither keep nor drop is used, the output data set will contain all variables from the
source data set, as well as any newly dened variables. The eects of multiple keep and
drop statements are cumulative.
Example
keep age, pay, sex;
See also
drop
165
lag 14. DATA LOOP REFERENCE
Purpose
Lags variables a specied number of periods.
Format
lag nv1 = var1:p1 [[nv2 = var2:p2...]];
Input
var name of the variable to lag.
p scalar constant, number of periods to lag.
Output
nv name of the new lagged variable.
Remarks
You can specify any number of variables to lag. Each variable can be lagged a dierent
number of periods. Both positive and negative lags are allowed.
Lagging is executed before any other transformations. If the new variable name is
dierent from that of the variable to lag, the new variable is rst created and appended
to a temporary data set, _lagtmp_.dat, on the default directory. This temporary data
set becomes the input data set for the dataloop, and is then automatically deleted.
166
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE listwise
Purpose
Controls listwise deletion of missing values.
Format
listwise [[read]]|[[write]];
Remarks
If read is specied, the deletion of all rows containing missing values happens
immediately after reading the input le and before any transformations. If write is
specied, the deletion of missing values happens after any transformations and just
before writing to the output le. If no listwise statement is present, rows with missing
values are not deleted.
The default is read.
167
make 14. DATA LOOP REFERENCE
Purpose
Species the creation of a new variable within a data loop.
Format
make [[#]] numvar = numeric expression;
make $ charvar = character expression;
Remarks
A numeric expression is any valid expression returning a numeric vector. A
character expression is any valid expression returning a character vector. If neither $
nor # is specied, # is assumed.
The expression may contain explicit variable names and/or GAUSS commands. Any
variables referenced must already exist, either as elements of the source data set, as
externs, or as the result of a previous make, vector, or code statement. The variable
name must be unique. A variable cannot be made more than once, or an error is
generated.
Example
make sqvpt = sqrt(velocity * pressure * temp);
make $ sex = lower(sex);
See also
vector
168
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE outtyp
Purpose
Species the precision of the output data set.
Format
outtyp num constant ;
Remarks
num constant must be 2, 4, or 8, to specify integer, single precision, or double
precision, respectively.
If outtyp is not specied, the precison of the output data set will be that of the input
data set. If character data is present in the data set the precision will be coerced to
double.
Example
outtyp 8;
169
recode 14. DATA LOOP REFERENCE
Purpose
Changes the value of a variable with dierent values based on a set of logical
expressions.
Format
recode [[#]] [[$]] var WITH
val 1 for expression 1,
val 2 for expression 2,
.
.
.
val n for expression n;
Input
var literal, the new variable name.
val scalar, value to be used if corresponding expression is true.
expression logical scalar-returning expression that returns nonzero TRUE or zero
FALSE.
Remarks
If $ is specied, the variable will be considered a character variable. If # is specied,
the variable will be considered numeric. If neither is specied, the type of the variable
will be left unchanged.
The logical expressions must be mutually exclusive, that is only one may return TRUE
for a given row (observation).
If none of the expressions is TRUE for a given row (observation), its value will remain
unchanged.
Any variables referenced must already exist, either as elements of the source data set,
as externs, or as the result of a previous make, vector, or code statement.
Example
recode age with
1 for age < 21,
2 for age >= 21 and age < 35,
3 for age >= 35 and age < 50,
4 for age >= 50 and age < 65,
5 for age >= 65;
170
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE recode
recode $ sex with
"MALE" for sex == 1,
"FEMALE" for sex == 0;
recode # sex with
1 for sex $== "MALE",
0 for sex $== "FEMALE";
See also
code
171
select 14. DATA LOOP REFERENCE
Purpose
Selects specic rows (observations) in a data loop based on a logical expression.
Format
select logical expression;
Remarks
Selects only those rows for which logical expression is TRUE. Any variables referenced
must already exist, either as elements of the source data set, as externs, or as the result
of a previous make, vector, or code statement.
Example
select age > 40 AND sex $== MALE;
See also
delete
172
D
a
t
a

T
r
a
n
s
f
o
r
m
a
t
i
o
n
s
14. DATA LOOP REFERENCE vector
Purpose
Species the creation of a new variable within a data loop.
Format
vector [[#]] numvar = numeric expression;
vector $ charvar = character expression;
Remarks
A numeric expression is any valid expression returning a numeric value. A
character expression is any valid expression returning a character value. If neither $
nor # is specied, # is assumed.
vector is used in place of make when the expression returns a scalar rather than a
vector. vector forces the result of such an expression to a vector of the correct length.
vector could actually be used anywhere that make is used, but would generate slower
code for expressions that already return vectors.
Any variables referenced must already exist, either as elements of the source data set,
as externs, or as the result of a previous make, vector, or code statement.
Example
vector const = 1;
See also
make
173
vector 14. DATA LOOP REFERENCE
174
G
r
a
p
h
i
c
s
Chapter 15
Graphics Categorical Reference
This chapter summarizes all of the procedures and global variables available within the
Publication Quality Graphics System. A general usage description and command
reference may be found in Chapters 16 and 17 respectively.
15.1 Graph Types
xy Graph X,Y using Cartesian coordinate system.
logx Graph X,Y using logarithmic X axis.
logy Graph X,Y using logarithmic Y axis.
loglog Graph X,Y using logarithmic X and Y axes.
bar Generate bar graph.
hist Compute and graph frequency histogram.
histf Graph a histogram given a vector of frequency counts.
histp Graph a percent frequency histogram of a vector.
box Graph data using the box graph percentile method.
xyz Graph X, Y, Z using 3-D Cartesian coordinate system.
surface Graph a 3-D surface.
contour Graph contour data.
draw Supply additional graphic elements to graphs.
15.2 Axes Control and Scaling
175
15. GRAPHICS CATEGORICAL REFERENCE
paxes Turn axes on or o.
pcross Control where axes intersect.
pgrid Control major and minor grid lines.
pxpmax Control precision of numbers on X axis.
pypmax Control precision of numbers on Y axis.
pzpmax Control precision of numbers on Z axis.
pxsci Control use of scientic notation on X axis.
pysci Control use of scientic notation on Y axis.
pzsci Control use of scientic notation on Z axis.
pticout Control direction of tick marks on axes.
scale Scale X,Y axes for 2-D plots.
scale3d Scale X,Y,Z axes for 3-D plots.
xtics Scale X axis and control tick marks.
ytics Scale Y axis and control tick marks.
ztics Scale Z axis and control tick marks.
15.3 Text, Labels, Titles, and Fonts
plegctl Set location and size of plot legend.
plegstr Specify legend text entries.
pmsgctl Control message position.
pmsgstr Specify message text.
paxht Control size of axes labels.
pnumht Control size of axes numeric labels.
pnum Axes numeric label control and orientation.
pdate Date string contents and control.
ptitlht Control main title size.
xlabel X axis label.
ylabel Y axis label.
zlabel Z axis label.
title Specify main title for graph.
asclabel Dene character labels for tick marks.
fonts Load fonts for labels, titles, messages and legend.
15.4 Main Curve Lines and Symbols
pboxctl Control box plotter.
pboxlim Output percentile matrix from box plotter.
176
G
r
a
p
h
i
c
s
15. GRAPHICS CATEGORICAL REFERENCE
plctrl Control main curve and frequency of data symbols.
pcolor Control line color for main curves.
pltype Control line style for main curves.
plwidth Control line thickness for main curves.
pstype Control symbol type for main curves.
psymsiz Control symbol size for main curves.
pzclr Z level color control for contour and surface.
15.5 Extra Lines and Symbols
parrow Create arrows.
parrow3 Create arrows for 3-D graphs.
pline Plot extra lines and circles.
pline3d Plot extra lines for 3-D graphs.
psym Plot extra symbols.
psym3d Plot extra symbols for 3-D graphs.
perrbar Plot error bars.
15.6 Window, Page, and Plot Control
pagesiz Control size of graph for printer output.
pageshf Shift the graph for printer output.
plotsiz Control plot area size.
plotshf Control plot area position.
protate Rotate the graph 90 degrees.
margin Control graph margins.
axmargin Control axes margins and plot size.
begwind Window initialization procedure.
endwind End window manipulation, display graphs.
window Create tiled windows of equal size.
makewind Create window with specied size and position.
setwind Set to specied window number.
nextwind Set to next available window number.
getwind Get current window number.
savewind Save window conguration to a le.
loadwind Load a window conguration from a le.
axmargin is preferred to the older plotsiz and plotshf globals for establishing an
absolute plot size and position.
177
15. GRAPHICS CATEGORICAL REFERENCE
15.7 Output Options
pnotify Control interactive mode and progress reports.
pscreen Control graphics output to screen.
psilent Control nal beep.
pzoom Specify zoom parameters.
ptek Control creation and name of graphics .tkf le.
graphprt Generate print, conversion le.
15.8 Miscellaneous
pbox Draw a border around window/screen.
pframe Draw a frame around 2-D, 3-D plots.
pcrop Control cropping of graphics data outside axes area.
pmcolor Control colors to be used for axes, title, x.
and y labels, date, box and background.
pxmem Memory control for graphics .rex les.
view Set 3-D observer position in workbox units.
viewxyz Set 3-D observer position in plot coordinates.
volume Set length, width and height ratios of 3-D workbox.
rerun Display most recently created graph.
graphset Reset all PQG globals to default values.
178
G
r
a
p
h
i
c
s
Chapter 16
Publication Quality Graphics
GAUSS Publication Quality Graphics is a set of routines built on the graphics
functions in GraphiC by Scientic Endeavors Corp.
The main graphics routines include xy, xyz, surface, polar and log plots, as well as
histograms, bar, and box graphs. Users can enhance their graphs by adding legends,
changing fonts, and adding extra lines, arrows, symbols and messages.
The user can create a single full size graph, inset a smaller graph into a larger one, tile
a screen with several equally sized graphs or place several overlapping graphs on the
screen. Window size and location are all completely under the users control.
16.1 Conguration
Before using the Publication Quality Graphics system, you may need to congure the
system for the hardware. See the graphics conguration section in the platform
supplement for your platform.
16.2 General Design
GAUSS Publication Quality Graphics consists of a set of main graphing procedures and
several additional procedures and global variables for customizing the output.
179
16. PUBLICATION QUALITY GRAPHICS
bar Bar graphs.
box Box plots.
contour Contour plots.
draw Draws graphs using only global variables.
hist Histogram.
histp Percentage histogram.
histf Histogram from a vector of frequencies.
loglog Log scaling on both axes.
logx Log scaling on X axis.
logy Log scaling on Y axis.
polar Polar plots.
surface 3-D surface with hidden line removal.
xy Cartesian graph.
xyz 3-D Cartesian graph.
All of the actual output to the screen happens during the call to these main routines.
16.3 Using Publication Quality Graphics
16.3.1 Getting Started Right Away
There are four basic parts to a graphics program. These elements should be in any
program that uses graphics routines. The four parts are header, data setup, graphics
format setup, and graphics call.
1. Header
In order to use the graphics procedures, the pgraph library must be active. This
is done in the library statement at the top of your program or command le.
The next line in your program will typically be a command to reset the graphics
global variables to the default state. The top two lines of your graphics program
should look something like this:
library mylib, pgraph;
graphset;
2. Data Setup
The data to be graphed must be in matrices.
x = seqa(1,1,50);
y = sin(x);
3. Graphics Format Setup
Most of the graphics elements contain defaults which allow the user to generate
a plot without modication. These defaults, however, may be overridden by the
180
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
user through the use of global variables and graphics procedures. Some of the
elements custom congurable by the user are axes numbering, labeling,
cropping, scaling, line and symbol sizes and types, legends and colors.
4. Calling Graphics Routines
It is in the main graphics routines where all of the work for the graphics
functions get done. The graphics routines take as input the user data and global
variables which have previously been set up. It is in these routines where the
graphics le is created and displayed.
Here are three Publication Quality Graphics examples. The rst two programs are
dierent versions of the same graph. The variables that begin with p are the global
control variables used by the graphics routines. See Section 16.8 for a detailed
description of the global control variables.
If using UNIX, a graphics window will have to be opened with the WinOpenPQG
function, see the COMMAND REFERENCE section in the UNIX supplement.
Example 1:
The routine being called here is a simple XY plot. The entire screen will be used. Four
sets of data will be plotted with the line and symbol attributes automatically selected.
This graph will include a legend, title, and a time/date stamp (time stamp is on by
default).
library pgraph; /* activate PGRAPH library */
graphset; /* reset global variables */
x = seqa(.1,.1,100); /* generate data */
y = sin(x);
y = y ~ y*.8 ~ y*.6 ~ y*.4; /* 4 curves plotted against x */
_plegctl = 1; /* legend on */
title("Example xy Graph"); /* Main title */
xy(x,y); /* Call to main routine */
Example 2:
Here is the same graph with more of the graphics format controlled by the user. The
rst two data sets will be plotted using symbols at graph points only (observed data),
and the data in the second two sets will be connected with lines (predicted results).
library pgraph; /* activate PGRAPH library */
graphset; /* reset global variables */
x = seqa(.1,.1,100); /* generate data */
y = sin(x);
y = y ~ y*.8 ~ y*.6 ~ y*.4; /* 4 curves plotted against x */
_pdate = ""; /* date is not printed */
181
16. PUBLICATION QUALITY GRAPHICS
_plctrl = { 1, 1, 0, 0 }; /* 2 curves w/symbols, 2 without */
_pltype = { 1, 2, 6, 6 }; /* dashed, dotted, solid lines */
_pstype = { 1, 2, 0, 0 }; /* symbol types circles, squares */
_plegctl= { 2, 3, 1.7, 4.5 }; /* legend size and locations */
_plegstr= "Sin wave 1.\0"\ /* 4 lines legend text */
"Sin wave .8\0"\
"Sin wave .6\0"\
"Sin wave .4";
ylabel("Amplitude"); /* Y axis label */
xlabel("X Axis"); /* X axis label */
title("Example xy Graph"); /* main title */
xy(x,y); /* call to main routine */
Example 3:
In this example, two graphics windows are drawn. The rst window is a full-sized
surface representation, and the second is a half-sized inset containing a contour of the
same data located in the lower left corner of the screen.
library pgraph; /* activate pgraph library */
/* Generate data for surface and contour plots */
x = seqa(-10,0.1,71); /* note x is a row vector */
y = seqa(-10,0.1,71); /* note y is a column vector */
z = cos(5*sin(x) - y); /* z is a 71x71 matrix */
begwind; /* initialize graphics windows */
makewind(9,6.855,0,0,0); /* first window full size */
makewind(9/2,6.855/2,1,1,0); /* second window inset to first */
setwind(1); /* activate first window */
graphset; /* reset global variables */
_pzclr = { 1, 2, 3, 4 }; /* set Z level colors */
title("cos(5*sin(x) - y)"); /* set main title */
xlabel("X Axis"); /* set X axis label */
ylabel("Y Axis"); /* set Y axis label */
scale3d(miss(0,0),miss(0,0),-5|5); /* scale Z axis */
surface(x,y,z); /* call surface routine */
nextwind; /* activate second window. */
graphset; /* reset global variables */
_pzclr = { 1, 2, 3, 4 }; /* set Z level colors */
_pbox = 15; /* white border */
contour(x,y,z); /* call contour routine */
endwind; /* Display windows */
While the structure has changed somewhat, the four basic elements of the graphics
program are all here. The additional routines begwind, endwind, makewind, nextwind,
and setwind are all used to control the graphics windows.
182
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
As Example 3 illustrates, the code between window functions (i.e. setwind or
nextwind) may include assignments to global variables, a call to graphset, or may set
up new data to be passed to the main graphics routines.
At this point, you may want to look through Chapter 15 to get an overview of the
capabilities of the Publication Quality Graphics, or proceed directly to Section 16.8 and
Chapter 17 for in-depth information on the Publication Quality Graphics functions and
global control variables. For more information on how to create graphics windows,
continue reading the section below.
You are encouraged to run the example programs supplied with GAUSS. Analyzing
these programs is perhaps the best way to learn how to use the Publication Quality
Graphics system. The example programs are located on the examples subdirectory.
16.3.2 Graphics Coordinate System
The Publication Quality Graphics uses a 4190x3120 pixel resolution on a 9.0x6.855 inch
hardcopy output screen or page. There are 3 units of measure supported with most of
the graphics global elements.
Inch Coordinates
Inch coordinates are based on the dimensions of the full-size 9.0x6.855 inch output
page. The origin is (0,0) at the lower left corner of the page. If the picture is rotated
the origin is at the upper left. See Inch Units in Graphics Windows in Section 16.4.1.
Plot Coordinates
Plot coordinates refer to the coordinate system of the graph in the units of the users
X, Y and Z axes.
Pixel Coordinates
Pixel coordinates refer to the 4096x3120 pixel coordinates of the full-size output page.
The origin is (0,0) at the lower left corner of the page. If the picture is rotated the
origin is at the upper left.
16.4 Graphics Windows
Multiple windows for graphics are supported. These windows allow the user to display
multiple graphs on one screen or page.
183
16. PUBLICATION QUALITY GRAPHICS
A window is any rectangular subsection of the screen or page. Windows may be any
size and position on the screen and may be tiled or overlapping, transparent or
nontransparent.
Tiled Windows
Tiled windows do not overlap. The screen can easily be divided into any number of
tiled windows with the window command. window takes three parameters: number of
rows, number of columns, and window attribute (1=transparent, 0=nontransparent).
window(nrows,ncols,attr);
window(2,3,0);
This command will divide the screen into 6 equally sized windows. There will be two
rows of three windows, 3 windows in the upper half of the screen and 3 in the lower
half. In this case, the attribute value of 0 is arbitrary since there are no other windows
beneath them.
Overlapping Windows
Overlapping windows are laid on top of one another as they are created, much as if you
were using the cut and paste method to place several graphs together on one page. An
overlapping window is created with the makewind command:
makewind(hsize,vsize,hpos,vpos,attr);
window(2,3,0);
makewind(4,2.5,1,1.5,0);
This makewind command will create an overlapping window of size 4 inches
horizontally by 2.5 inches vertically and positioned 1 inch from the left edge of the page
and 1.5 inches from the bottom of the page. It will be nontransparent.
Nontransparent Windows
A nontransparent window is one which is blanked before graphics information is
written to it. Therefore, information in any previously drawn windows that lie under it
will not be visible.
184
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
Transparent Windows
A transparent window is one which is not blanked, allowing the window beneath it to
show through. Transparent windows are useful for adding information to the page
without erasing information below it. For example, using a transparent window, the
user can add an arrow which begins in one window and ends in another.
16.4.1 Using Window Functions
The following is a summary of the available window functions:
begwind Window initialization procedure.
endwind End window manipulations, display graphs.
window Partition screen into tiled windows.
makewind Create window with specied size and position.
setwind Set to specied window number.
nextwind Set to next available window number.
getwind Get current window number.
savewind Save window conguration to a le.
loadwind Load window conguration from a le.
The following example creates 4 tiled windows and one window which overlaps the
other four:
library pgraph;
graphset;
begwind;
window(2,2,0); /* Create four tiled windows (2 rows, 2 columns) */
xsize = 9/2; /* Create window that overlaps the tiled windows */
ysize = 6.855/2;
makewind(xsize,ysize,xsize/2,ysize/2,0);
x = seqa(1,1,1000); /* Create X data */
y = (sin(x) + 1) * 10.; /* Create Y data */
setwind(1); /* Graph #1, upper left corner */
xy(x,y);
nextwind; /* Graph #2, upper right corner */
logx(x,y);
nextwind; /* Graph #3, lower left corner */
logy(x,y);
nextwind; /* Graph #4, lower right corner */
loglog(x,y);
nextwind; /* Graph #5, center, overlayed */
bar(x,y);
endwind; /* End window processing, display graph */
185
16. PUBLICATION QUALITY GRAPHICS
Inch Units in Graphics Windows
Some global variables allow coordinates to be input in inches. If a coordinate value is in
inches and is being used in a window, that value will be scaled to window inches and
positioned relative to the lower left corner of the window. A window inch is a true inch
in size only if the window is scaled to the full screen, otherwise X coordinates will be
scaled relative to the horizontal window size and Y coordinates will be scaled relative
to the vertical window size.
For help in nding the exact inch coordinates on the output page for positioning text
and other items, see Section 16.5.
16.4.2 Transparent Windows
Lines, symbols, arrows, error bars and other graphics objects may extend from one
window to the next by using transparent windows. First create the desired window
conguration. Then create a full screen, transparent window using the makewind or
the window command. Set the appropriate global variables to position the desired
object on the transparent window. Use the draw procedure to draw it. This window
will act as a transparent overlay on top of the other windows. Transparent windows
can be used to add text or to superimpose one window on top of another.
16.4.3 Saving Window Congurations
The functions savewind and loadwind allow the user to save window congurations.
Once windows are created (using makewind and window) savewind may be called.
This will save to disk the global variables containing information about the current
window conguration. To load this conguration again, call loadwind. See Chapter 17.
16.5 Interactive Draft Mode, DOS Only
Interactive Draft mode allows the user to nd inch position coordinates on the graph
interactively using a mouse or cursor keys. This is useful for locating coordinates for
text, symbols, lines and other items which will be added to the graph.
Draft mode is selected by setting pnotify to 2. This will cause the graph to be drawn
while the graphics le is being created. When each window is complete, the program
will pause before drawing any other windows. At this point, type P. A cursor will
appear and the cursor location will be printed in the lower right corner of the screen.
186
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
The cursor may be positioned with the arrow keys (holding down the Shift key causes
ner movement) or with a mouse.
If the cursor enters the most recent window, two sets of coordinates will be displayed.
The upper coordinates are in window inches relative to the current window. The lower
coordinates are absolute full-page coordinates. See Inch Units in Graphics Windows in
Section 16.4.1.
To exit the interactive mode, press the Esc key.
This function is available on CGA, EGA, and VGA displays only. Thick lines show up
as normal width.
16.6 Fonts and Special Characters
Graphics text elements, such as titles, messages, axes labels, axes numbering and
legends can be modied and enhanced by changing fonts, adding superscripting,
subscripting and special mathematical symbols.
To make these modications and enhancements, the user can embed escape codes in the
text strings which are passed to title, xlabel, ylabel and asclabel or assigned to
pmsgstr and plegstr.
The escape codes used for graphics text are:
\000 String termination character (null byte).
[ Enter superscript mode, leave subscript mode.
] Enter subscript mode, leave superscript mode.
@ Interpret next character as literal.
\20n Select font number n. (see discussion on fonts below)
The escape code \L can be embedded into title strings to create a multiple line title:
title("This is the first line\lthis is the second line");
A null byte \000 is used to separate strings in plegstr and pmsgstr:
_pmsgstr = "First string\000Second string\000Third string";
or
_plegstr = "Curve 1\000Curve 2";
Use the [..] to create the expression M(t) = E(e
tx
):
_pmsgstr = "M(t) = E(e[tx])";
Use the @ to use [ and ] in an X axis label:
xlabel("Data used for x is: data@[.,1 2 3@]");
187
16. PUBLICATION QUALITY GRAPHICS
16.6.1 Selecting Fonts
Four fonts are supplied with Publication Quality Graphics. They are Simplex,
Complex, Simgrma, and Microb. To see the characters in these fonts, see Appendix A.
Fonts are loaded by passing to the fonts procedure a string containing the names of all
fonts to be loaded. For example, this statement will load all four fonts:
fonts("simplex complex microb simgrma");
The fonts command must be called before any of the fonts may be used in text strings.
One of these fonts may then be selected by embedding an escape code of the form
\20n in the string which is to be written in the new font. The n will be 1, 2, 3 or 4,
depending on the order in which the fonts were loaded in fonts. If fonts were loaded as
they are in the above example, then the escape characters for each of the fonts would
be:
\201 Simplex
\202 Complex
\203 Microb
\204 Simgrma
Now select a font for each string to be written:
title("\201This is the title using Simplex font");
xlabel("\202This is the label for X using Complex font");
ylabel("\203This is the label for Y using Microb font");
Once a font is selected, all succeeding text will use that font until another font is
selected. If no fonts are selected by the user, a default font (Simplex) is loaded and
selected automatically for all text work.
16.6.2 Greek and Mathematical Symbols
The following examples illustrate the use of the Simgrma font. This example assumes
that Simgrma was the fourth font loaded. The Simgrma font table in Appendix A lists
the characters available and their numbers. The Simgrma characters are specied by
either:
1. The character number, preceeded by a \.
2. The regular text character with the same number.
188
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
For example, to get an integral sign

in Simgrma, embed either a \044 or a , in


the string that has been currently set to use Simgrma font.
To produce the title f(x) = sin
2
(x), the following title string should be used:
title("\201f(x) = sin[2](\204p\201x)");
The p (character 112) corresponds to in Simgrma.
To number the major X axis tick marks with multiples of /4, the following could be
passed to asclabel:
lab = "\2010 \204p\201/4 \204p\201/2 3\204p\201/4 \204p";
asclabel(lab,0);
xtics(0,pi,pi/4,1);
xtics is used to make sure that major tick marks are placed in the appropriate places.
This example will number the X axis tick marks with the labels
2
,
1
, 1, , and
2
:
lab = "\204m\201[-2] \204m\201[-1] 1 \204m m\201[2]";
asclabel(lab,0);
This example illustrates the use of several of the special Simgrma symbols:
_pmsgstr = "\2041\2011/2\204p ,\201e[-\204m[\2012]\201/2]d\204m";
This produces:

1/2

2
/2
d
16.7 Hardcopy and Exporting
When a graphics procedure is called, a graphics le is created. This le contains
graphics commands which may be used later for viewing or printing.
When the graph is displayed on the screen, the user may, in DOS, press the Enter key
to obtain a menu containing available options. If using OS/2 or Unix simply select one
of the menu bar options. These options allow the user to print the graph, zoom in, or
convert the le to another format.
189
16. PUBLICATION QUALITY GRAPHICS
16.7.1 Printing the Graph
The graph may be printed by selecting one of the interactive print options: normal or
draft. The normal print uses a resolution level taken from the PQG conguration le.
The fast draft print always uses a low resolution print. Most of the print parameters
such as page size, margins, and orientation may be changed by editing the
conguration le or by using the graphprt procedure. See Chapter 17 for more
information on graphprt.
If you have purchased the optional DOS play.exe program you may choose to print
your graph using the options available with it. play.exe is documented in the DOS
supplement.
Zooming
To zoom in on a graph interactively, press Z from the graphics display, or select zoom
from the menu bar. An arrow will appear in the center of the graph with a rubberband
box. You may size the box using the the cursor keys or by moving the mouse. Pressing
the right mouse button (or Ctrl-Cursor keys, DOS only) will allow you to move the box.
Pressing the Enter key or left mouse button will select the box as the area to zoom.
Press Esc to cancel zoom mode.
The user may bypass the interactive menu by using a global variable to pass zoom
parameters to the graphics routines. The parameters are set with a 3x1 matrix named
pzoom. See Section 16.8 for a description of this global.
16.7.2 Exporting Graphs
By pressing C, in DOS, from either the graphics menu or the displayed graph, or
selecting File from the menu bar, in OS/2, the graphics le may be converted into other
formats. These formats are widely used by other applications for importing graphs into
word processing and desktop publishing programs. The currently available format
types are:
Encapsulated PostScript le.
Lotus .PIC le
HP-GL Plotter le
PCX bitmap image
DOS only
Other export options are available with the optional program play.exe. For a
complete description of command parameters to play.exe, see the DOS supplement.
190
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
UNIX only
The convert menu option will convert the graph to the le type specied by the
gauss*print.driver variable located in the .gaussrc le. Other export le options
are located in the prndev.tbl le.
16.8 Global Control Variables
The following global variables are used to control various graphics elements. Default
values are provided. Any and all of these variables may be set before calling one of the
main graphing routines. The default values may be modied by changing the
declarations in pgraph.dec and the statements in the procedure graphset in
pgraph.src. graphset may be called anytime the user wishes to reset these variables to
their default values.
pageshf 2x1 vector, the graph will be shifted to the right and up if this is not
zero. If this is zero, the graph will be centered on the output page. The
default is 0.
Note: Used internally, see axmargin for the same functionality. This is
used by the graphics window routines. The user must not set this when
using the window procedures.
pagesiz 2x1 vector, size of the graph in inches on the printer output. Maximum
size is 9.0 x 6.855 inches (unrotated) or 6.855 x 9.0 inches (rotated). If
this is 0, the maximum size will be used. The default is 0.
Note: Used internally, see axmargin for the same functionality. This is
used by the graphics window routines. The user must not set this when
using the window procedures.
parrow Mx11 matrix, draws one arrow per row M of the input matrix. If scalar
zero, no arrows will be drawn.
[M,1] x starting point.
[M,2] y starting point.
[M,3] x ending point.
[M,4] y ending point.
[M,5] ratio of the length of the arrow head to half its width.
[M,6] size of arrow head in inches.
[M,7] type and location of arrow heads. This integer number will be
interpreted as a decimal expansion mn, for example: if 10, then
m = 1, n = 0
m, form of arrow head
191
16. PUBLICATION QUALITY GRAPHICS
0 solid.
1 empty.
2 open.
3 closed.
n, location of arrow head
0 none.
1 at the nal end.
2 at both ends.
[M,8] color of arrow.
[M,9] coordinate units for location.
1 x,y starting and ending locations in plot coordinates.
2 x,y starting and ending locations in inches.
3 x,y starting and ending locations in pixels.
[M,10] line type
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
[M,11] Controls. thickness of lines used to draw arrow. This value may
be zero or greater. A value of zero is normal line width.
The following statement could be used to create two single-headed
arrows. They will be located using inches.
_parrow = { 1 1 2 2 3 0.2 11 10 2 6 0,
3 4 2 2 3 0.2 11 10 2 6 0 };
parrow3 Mx12 matrix, draws one 3-D arrow per row of the input matrix. If scalar
zero, no arrows will be drawn.
[M,1] x starting point in 3-D plot coordinates.
[M,2] y starting point in 3-D plot coordinates.
[M,3] z starting point in 3-D plot coordinates.
[M,4] x ending point in 3-D plot coordinates.
[M,5] y ending point in 3-D plot coordinates.
[M,6] z ending point in 3-D plot coordinates.
[M,7] ratio of the length of the arrow head to its half width.
[M,8] size of arrow head in inches.
192
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
[M,9] type and location of arrow heads. This integer number will be
interpreted as a decimal expansion mn, for example:
if 10, then m = 1, n = 0
m, form of arrow head
0 solid.
1 empty.
2 open.
3 closed.
n, location of arrow head
0 none.
1 at the nal end.
2 at both ends.
[M,10] color of arrow.
[M,11] line type.
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
[M,12] controls thickness of lines used to draw arrow. This value may
be zero or greater. A value of zero is normal line width.
The following statement could be used to create two single-headed
arrows. They will be located using plot coordinates.
_parrow3 = { 1 1 1 2 2 2 3 0.2 11 10 6 0,
3 4 5 2 2 2 3 0.2 11 10 6 0 };
paxes scalar, 2x1, or 3x1 vector for independent control for each axis. The rst
element controls the X axis, the second controls the Y axis, and the
third (if set) will control the Z axis. If 0 the axis will not be drawn.
Default is 1.
If this is a scalar, it will be expanded to that value.
For example:
_paxes = { 1, 0 }; /* turn X axis on, Y axis off */
_paxes = 0; /* turn all axes off */
_paxes = 1; /* turn all axes on */
paxht scalar, size of axes labels in inches. If 0, a default size will be computed.
Default 0.
193
16. PUBLICATION QUALITY GRAPHICS
pbartyp global 1x2 or Kx2 matrix. Controls bar shading and colors in bar graphs
and histograms.
The rst column controls the bar shading:
0 no shading.
1 dots.
2 vertical cross-hatch.
3 diagonal lines with positive slope.
4 diagonal lines with negative slope.
5 diagonal cross-hatch.
6 solid.
The second column controls the bar color.
pbarwid global scalar, width of bars in bar graphs and histograms. The valid
range is 0-1. If this is 0, the bars will be a single pixel wide. If this is 1,
the bars will touch each other. The default is 0.5, so the bars take up
about half the space open to them.
pbox scalar, draws a box (border) around the entire graph. Set to desired
color of box to be drawn. Use 0 if no box is desired. Default 0.
pboxctl 5x1 vector, controls box plot style, width, and color. Used by procedure
box only.
[1] box width between 0 and 1. If zero, the box plot is drawn as two
vertical lines representing the quartile ranges with a lled circle
representing the 50
th
percentile.
[2] box color. If this is set to 0, the colors may be individually
controlled using global variable pcolor.
[3] Min/max style for the box symbol. One of the following:
1 Minimum and maximum taken from the actual limits of the
data. Elements 4 and 5 are ignored.
2 Statistical standard with the minimum and maximum
calculated according to interquartile range as follows:
intqrange = 75
th
25
th
min = 25
th
1.5intqrange
max = 75
th
+ 1.5intqrange
Elements 4 and 5 are ignored.
3 Minimum and maximum percentiles taken from elements 4
and 5.
[4] Minimum percentile value (0-100) if pboxctl[3] = 3.
[5] Maximum percentile value (0-100) if pboxctl[3] = 3.
194
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
pboxlim 5xM output matrix containing computed percentile results from
procedure box. M corresponds to each column of input y data.
[1,M] minimum whisker limit according to pboxctl[3].
[2,M] 25th percentile (bottom of box).
[3,M] 50th percentile (median).
[4,M] 75th percentile (top of box).
[5,M] maximum whisker limit according to pboxctl[3].
pcolor scalar or Kx1 vector, colors for main curves in xy, xyz and log graphs.
To use a single color set for all curves set this to a scalar color value. If
0, use default colors. Default 0.
The default colors come from a global vector called pcsel. This vector
can be changed by editing pgraph.dec to change the default colors.
pcsel is not documented elsewhere.
pcrop scalar or 1x5 vector, allows plot cropping for dierent graphic elements
to be individually controlled. Valid values are 0 (disabled) or 1
(enabled). If cropping is enabled, any graphical data sent outside the
axes area will not be drawn. If this is scalar, pcrop is expanded to a
1x5 vector using the given value for all elements. All cropping is enabled
by default.
[1] Crop main curves/symbols.
[2] Crop lines generated using pline.
[3] Crop arrows generated using parrow.
[4] Crop circles/arcs generated using pline.
[5] Crop symbols generated using psym.
_pcrop = { 1 1 0 1 0 };
This will crop main curves, and lines and circles drawn by pline.
pcross scalar. If 1, the axes will intersect at the (0,0) X-Y location if it is
visible. The default is 0, meaning the axes will be at the lowest end of
the X-Y coordinates.
pdate date string. If this contains characters, the date will be appended and
printed. The default is set as follows (note the rst character is a font
selection escape code):
_pdate = "\201GAUSS ";
If this is set to a null string, no date will be printed. See Section 16.6 for
more information on using fonts within strings.
195
16. PUBLICATION QUALITY GRAPHICS
perrbar Mx9 matrix, draws one error bar per row of the input matrix. If scalar
0, no error bars will be drawn.
[M,1] x location in plot coordinates.
[M,2] left end of error bar.
[M,3] right end of error bar.
[M,4] y location in plot coordinates.
[M,5] bottom of error bar.
[M,6] top of error bar.
[M,7] line type.
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
[M,8] color.
[M,9] line thickness.. This value may be zero or greater. A value of
zero is normal line width.
The following statement could be used to create one error bar using solid
lines:
_perrbar = { 1 0 2 2 1 3 6 2 0 };
pframe 2x1 vector, controls frame around axes area. On 3-D plots this is a cube
surrounding the 3-D workspace.
[1] 1 frame on.
0 frame o.
[2] 1 tick marks on frame.
0 no tick marks.
The default is a frame with tick marks.
pgrid 2x1 vector to control grid.
[1] grid through tick marks.
0 no grid.
1 dotted grid.
2 ne dotted grid.
3 solid grid.
196
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
[2] grid subdivisions between major tick marks.
0 no subdivisions.
1 dotted lines at subdivisions.
2 tick marks only at subdivisions.
The default is no grid and tick marks at subdivisions.
plctrl scalar or Kx1 vector to control whether lines and/or symbols will be
displayed for the main curves. This also controls the frequency of
symbols on main curves. The rows (K) is equal to the number of
individual curves to be plotted in the graph. Default 0.
0 draw line only.
>0 draw line and symbols every plctrl points.
<0 draw symbols only every plctrl points.
1 all of the data points will be plotted with no connecting lines.
_plctrl = { 0, 10, -5 };
This example draws a line for the rst curve, draws a line and plots a
symbol every 10 data points for the second curve, and plots symbols
only every 5 data points for the third curve.
plegctl scalar or 1x4 vector, legend control variable.
If scalar 0, no legend is drawn (default). If nonzero scalar, create legend
in the default location in the lower right of the page.
If 1x4 vector, set as follows:
[1] Legend position coordinate units.
1 Coordinates are in plot coordinates.
2 Coordinates are in inches.
3 Coordinates are in pixels.
[2] Legend text font size. 1 size 9. Default 5.
[3] x coordinate of lower left corner of legend box.
[4] y coordinate of lower left corner of legend box.
_plegctl = 1;
This example puts a legend in the lower right corner.
_plegctl = { 2 3 2.5 1 };
This example creates a smaller legend and positions it 2.5 inches from
the left and 1 inch from the bottom.
197
16. PUBLICATION QUALITY GRAPHICS
plegstr string, legend entry text. Text for multiple curves is separated by a null
byte (\000).
For example:
_plegstr = "Curve 1\000Curve 2\000Curve 3";
plev Mx1 vector, user-dened contour levels for contour. Default 0. See
contour.
pline Mx9 matrix, to draw lines, circles, or radii. Each row controls one item
to be drawn. If this is a scalar zero, nothing will be drawn. The default
is 0.
[M,1] item type and coordinate system.
1 line in plot coordinates.
2 line in inch coordinates.
3 line in pixel coordinates.
4 circle in plot coordinates.
5 circle in inch coordinates.
6 radius in plot coordinates.
7 radius in inch coordinates.
[M,2] line type.
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
[M,3-7] coordinates and dimensions.
( 1 ) Line in plot coordinates.
[M,3] x starting point in plot coordinates.
[M,4] y starting point in plot coordinates.
[M,5] x ending point in plot coordinates.
[M,6] y ending point in plot coordinates.
[M,7] 0 if this is a continuation of a curve, 1 if this begins a
new curve.
( 2 ) Line in inches.
[M,3] x starting point in inches.
[M,4] y starting point in inches.
[M,5] x ending point in inches.
[M,6] y ending point in inches.
[M,7] 0 if this is a continuation of a curve, 1 if this begins a
new curve.
198
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
( 3 ) Line in pixel coordinates.
[M,3] x starting point in pixels.
[M,4] y starting point in pixels.
[M,5] x ending point in pixels.
[M,6] y ending point in pixels.
[M,7] 0 if this is a continuation of a curve, 1 if this begins a
new curve.
( 4 ) Circle in plot coordinates.
[M,3] x center of circle in plot coordinates.
[M,4] y center of circle in plot coordinates.
[M,5] radius in x plot units.
[M,6] starting point of arc in radians.
[M,7] ending point of arc in radians.
( 5 ) Circle in inches.
[M,3] x center of circle in inches.
[M,4] y center of circle in inches.
[M,5] radius in inches.
[M,6] starting point of arc in radians.
[M,7] ending point of arc in radians.
( 6 ) Radius in plot coordinates.
[M,3] x center of circle in plot coordinates.
[M,4] y center of circle in plot coordinates.
[M,5] beginning point of radius in x plot units, 0 is the center
of the circle.
[M,6] ending point of radius.
[M,7] angle in radians.
( 7 ) Radius in inches.
[M,3] x center of circle in inches.
[M,4] y center of circle in inches.
[M,5] beginning point of radius in inches, 0 is the center of the
circle
[M,6] ending point of radius in inches.
[M,7] angle in radians.
[M,8] color.
[M,9] Controls line thickness. This value may be zero or greater. A
value of zero is normal line width.
pline3d Mx9 matrix. Allows extra lines to be added to an xyz or surface graph
in 3-D plot coordinates.
199
16. PUBLICATION QUALITY GRAPHICS
[M,1] x starting point.
[M,2] y starting point.
[M,3] z starting point.
[M,4] x ending point.
[M,5] y ending point.
[M,6] z ending point.
[M,7] color.
[M,8] line type.
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
[M,9] Line thickness, 0 = normal width.
[M,10] Hidden line ag, 1 = obscured by surface, 0 = not obscured.
plotshf 2x1 vector, distance of plot from lower left corner of output page in
inches. [1] is x distance, [2] is y distance. If scalar 0, there will be no
shift. Default 0.
Note: Used internally, see axmargin for the same functionality. This is
used by the graphics window routines. The user must not set this when
using the window procedures.
plotsiz 2x1 vector, size of the axes area in inches. If scalar 0, the maximum size
will be used.
Note: Used internally, see axmargin for the same functionality. This is
used by the graphics window routines. The user must not set this when
using the window procedures.
pltype scalar or Kx1 vector, line type for the main curves. If this is a nonzero
scalar, all lines will be this type. If scalar 0, line types will be default
styles. The default is 0.
1 dashed.
2 dotted.
3 short dashes.
4 closely spaced dots.
5 dots and dashes.
6 solid.
200
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
The default line types come from a global vector called plsel. This
vector can be changed by editing pgraph.dec to change the default line
types. plsel is not documented elsewhere.
plwidth scalar or Kx1 vector, line thickness for main curves. This value may be
zero or greater. A value of zero is normal (single pixel) line width.
Default 0.
pmcolor 9x1 vector, color values to use for plot
[1] axes.
[2] axes numbers.
[3] X axis label.
[4] Y axis label.
[5] Z axis label.
[6] title.
[7] box.
[8] date.
[9] background.
If this is scalar, it will be expanded to a 9x1 vector
pmsgctl Lx7 matrix of control information for printing the strings contained in
pmsgstr.
[L,1] horizontal location of lower left corner of string.
[L,2] vertical location of lower left corner of string.
[L,3] character height in inches.
[L,4] angle in degrees to print string. This may be -180 to 180 relative
to the positive X axis.
[L,5] location coordinate system.
1 location of string in plot coordinates.
2 location of string in inches.
[L,6] color.
[L,7] Font thickness, may be zero or greater. If 0 use normal line
width.
pmsgstr string, contains a set of messages to be printed on the plot. Each
message is separated from the next with a null byte ( \000 ). The
number of messages must correspond to the number of rows in the
pmsgctl control matrix. This can be created as follows:
201
16. PUBLICATION QUALITY GRAPHICS
_pmsgstr = "Message one.\000Message two.";
pnotify scalar, controls screen output during the creation of the graph. Default
1.
0 No activity to the screen while writing .tkf le.
1 Display progress as fonts are loaded, and .tkf le is being
generated.
2 Display graph while writing .tkf le and enter interactive draft
mode.
pnum scalar, 2x1 or 3x1 vector for independent control for axes numbering.
The rst element controls the X axis numbers, the second controls the Y
axis numbers, and the third (if set) controls the Z axis numbers. Default
is 1.
If this value is scalar, it will be expanded to a vector.
0 No axes numbers displayed.
1 Axes numbers displayed, vertically oriented on Y axis.
2 Axes numbers displayed, horizontally oriented on Y axis.
For example:
_pnum = { 0, 2 }; /* no X axis numbers, horizontal on Y axis */
pnumht scalar, size of axes numbers in inches. If 0 (default), a size of .13 will be
used.
protate scalar, if 0, no rotation, if 1, plot will be rotated 90 degrees. Default 0.
pscreen scalar, if 1, display graph on screen, if 0, do not display graph on screen.
Default 1.
psilent scalar, if 0, a beep will sound when the graph is nished drawing to the
screen. Default 1 (no beep).
pstype scalar or Kx1 vector, controls symbol used at graph points. To use a
single symbol type for all points set this to one of the following scalar
values:
1 Circle 8 Solid Circle
2 Square 9 Solid Square
3 Triangle 10 Solid Triangle
4 Plus 11 Solid Plus
5 Diamond 12 Solid Diamond
6 Inverted Triangle 13 Solid Inverted Triangle
7 Star 14 Solid Star
202
G
r
a
p
h
i
c
s
16. PUBLICATION QUALITY GRAPHICS
If this is a vector, each line will have a dierent symbol. Symbols will
repeat if there are more lines than symbol types.
psurf 2x1 vector, controls 3-D surface characteristics.
[1] if 1, show hidden lines. Default 0.
[2] Color for base (default 7). The base is an outline of the X-Y
plane with a line connecting each corner to the surface. If 0 no
base is drawn.
psym Mx7 matrix, M extra symbols will be plotted.
[M,1] x location.
[M,2] y location.
[M,3] symbol type. See pstype.
[M,4] symbol height. If this is 0, a default height of 5.0 will be used.
[M,5] symbol color.
[M,6] type of coordinates.
1 plot coordinates.
2 inch coordinates.
[M,7] line thickness. A value of zero is normal line width.
psym3d Mx7 matrix for plotting extra symbols on a 3-D (surface or xyz) graph.
[M,1] x location in plot coordinates.
[M,2] y location in plot coordinates.
[M,3] z location in plot coordinates.
[M,4] symbol type. See pstype.
[M,4] symbol height. If this is 0, a default height of 5.0 will be used.
[M,6] symbol color.
[M,7] Line thickness. A value of 0 is normal line width.
Use psym for plotting extra symbols in inch coordinates.
psymsiz scalar or Kx1 vector, symbol size for the symbols on the main curves.
This is NOT related to psym. If 0, a default size of 5.0 is used.
ptek string, name of Tektronix format graphics le. This must have a .tkf
extension. If this is set to a null string, the graphics le will be
suppressed. The default is graphic.tkf.
pticout scalar, if 1, tick marks point outward on graphs. Default 0.
203
16. PUBLICATION QUALITY GRAPHICS
ptitlht scalar, the height of the title characters in inches. If this is 0, a default
height of approx. 0.13 will be used.
pversno string, the graphics version number.
pxpmax scalar, the maximum number of places to the right of the decimal point
for the X axis numbers. Default 12.
pxsci scalar, the threshold in digits above which the data for the X axis will be
scaled and a power of 10 scaling factor displayed. Default 4.
pypmax scalar, the maximum number of places to the right of the decimal point
for the Y axis numbers. Default 12.
pysci scalar, the threshold in digits above which the data for the Y axis will be
scaled and a power of 10 scaling factor displayed. Default 4.
pzclr scalar, row vector, or Kx2 matrix, Z level color control for procedures
surface and contour. See surface.
pzoom 1x3 row vector, magnies the graphics display for zooming in on detailed
areas of the graph. If scalar 0 (default), no magnication is performed.
[1] Magnication value. 1 is normal size.
[2] Horizontal center of zoomed plot (0-100).
[3] Vertical center of zoomed plot (0-100).
To see the upper left quarter of the screen magnied 2 times use:
_pzoom = { 2 25 75 };
pzpmax scalar, the maximum number of places to the right of the decimal point
for the Z axis numbers. Default 3.
pzsci scalar, the threshold in digits above which the data for the Z axis will be
scaled and a power of 10 scaling factor displayed. Default 4.
204
G
r
a
p
h
i
c
s
Chapter 17
Graphics Reference
205
asclabel 17. GRAPHICS REFERENCE
Purpose
To set up character labels for the X and Y axes.
Library
pgraph
Format
asclabel(xl ,yl );
Input
xl string or Nx1 character vector, labels for the tick marks on the X axis. Set
to 0 if no character labels for this axis are desired.
yl string or Mx1 character vector, labels for the tick marks on the Y axis. Set
to 0 if no character labels for this axis are desired.
Example
This illustrates how to label the X axis with the months of the year:
let lab = JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC;
asclabel(lab,0);
This will also work:
lab = "JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC";
asclabel(lab,0);
If the string format is used, then escape characters may be embedded in the labels. For
example, the following produces character labels that are multiples of . The font
Simgrma must be previously loaded in a fonts command. See Section 16.6.
fonts("simplex simgrma");
lab = "\2010.25\202l \2010.5\202l \2010.75\202l l";
asclabel(lab,0);
Here, the \202l produces the symbol from Simgrma.
Source
pgraph.src
Globals
pascx, pascy
See also
xtics, ytics, scale, scale3d, fonts
206
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE axmargin
Purpose
Set absolute margins for the plot axes which control placement and size of plot.
Library
pgraph
Format
axmargin(l ,r,t ,b);
Input
l scalar, the left margin in inches.
r scalar, the right margin in inches.
t scalar, the top margin in inches.
b scalar, the bottom margin in inches.
Remarks
axmargin sets an absolute distance from the axes to the edge of the window. Note that
the user is responsible for allowing enough space in the margin if axes labels, numbers
and title are used on the graph, since axmargin does not size the plot automatically as
in the case of margin.
All input inch values for this procedure are based on a full size screen of 9 x 6.855
inches. If this procedure is used within a window, the values will be scaled to window
inches automatically.
If both margin and axmargin are used for a graph, axmargin will override any sizes
specied by margin.
Example
axmargin(1,1,.5,.855);
This will create a plot area of 7 inches horizontally by 5.5 inches vertically, and
positioned 1 inch right and .855 up from the lower left corner of the window/page.
Source
pgraph.src
Globals
paxmarx, plotshf, plotsiz
207
bar 17. GRAPHICS REFERENCE
Purpose
Bar graph.
Library
pgraph
Format
bar(val ,ht );
Input
val Nx1 numeric vector, bar labels. If scalar 0, a sequence from 1 to rows(ht )
will be created.
ht NxK numeric vector, bar heights.
K overlapping or side-by-side sets of N bars will be graphed.
For overlapping bars, the rst column should contain the set of bars with
the greatest height and the last column should contain the set of bars with
the least height. Otherwise the bars which are drawn rst may be obscured
by the bars drawn last. This is not a problem if the bars are plotted
side-by-side.
pbarwid global scalar, width and type of bars in bar graphs and histograms. The
valid range is 0-1. If this is 0, the bars will be a single pixel wide. If this is
1, the bars will touch each other.
If this value is positive, the bars will overlap. If negative, the bars will be
plotted side-by-side. The default is 0.5.
pbartyp Kx2 matrix.
The rst column controls the bar shading:
0 no shading.
1 dots.
2 vertical cross-hatch.
3 diagonal lines with positive slope.
4 diagonal lines with negative slope.
5 diagonal cross-hatch.
6 solid.
The second column controls the bar color.
208
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE bar
Remarks
Use scale or ytics to x the scaling for the bar heights.
Example
library pgraph;
graphset;
t = seqa(0,1,10);
x = (t^2/2).*(1~0.7~0.3);
_plegctl = { 1 4 };
_plegstr = "Accnt #1\000Accnt #2\000Accnt #3";
title("Theoretical Savings Balance");
xlabel("Years");
ylabel("Dollars x 1000");
_pbartyp = { 1 10 }; /* Set color of the bars to */
/* 10 (magenta) */
_pnum = 2;
bar(t,x); /* Use t vector to label X axis. */
In this example, three overlapping sets of bars will be created. The three heights for
the i
th
bar are stored in x[i,.] .
Source
pbar.src
Globals
rerun, xtics, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx,
pascy, paxes, paxht, paxnum, pbartyp, pbarwid, pbox, pcartx, pcarty,
pcrop, pcross, pcwin, pdate, perrbar, pfonts, pgrid, plegctl, plegstr,
plotshf, plotsiz, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,
pqgtype, protate, pscreen, ptek, pticout, ptitle, ptitlht, pworld,
pwrscal, pxfmt, pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel,
pypmax, pyscale, pysci, setpage, txtlt
See also
asclabel, xy, logx, logy, loglog, scale, hist
209
begwind 17. GRAPHICS REFERENCE
Purpose
Initialize global window variables.
Library
pgraph
Format
begwind;
Remarks
This procedure must be called before any other window functions are called.
Source
pwindow.src
Globals
pageshf, pagesiz, pappend, pcwin, pdate, prstw, pncwin, pscreen,
pwindmx, pwindno
See also
endwind, window, makewind, setwind, nextwind, getwind
210
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE box
Purpose
Graph data using the box graph percentile method.
Library
pgraph
Format
box(grp,y);
Input
grp 1xM vector. This contains the group numbers corresponding to each
column of y data. If scalar 0, a sequence from 1 to cols(y) will be
generated automatically for the X axis.
y NxM matrix. Each column represents the set of y values for an individual
percentiles box symbol.
Global Input
pboxctl 5x1 vector, controls box style, width, and color.
[1] box width between 0 and 1. If zero, the box plot is drawn as two
vertical lines representing the quartile ranges with a lled circle
representing the 50
th
percentile.
[2] box color. If this is set to 0, the colors may be individually
controlled using the global variable pcolor.
[3] Min/max style for the box symbol. One of the following:
1 Minimum and maximum taken from the actual limits of the
data. Elements 4 and 5 are ignored.
2 Statistical standard with the minimum and maximum
calculated according to interquartile range as follows:
intqrange = 75
th
25
th
min = 25
th
1.5intqrange
max = 75
th
+ 1.5intqrange
Elements 4 and 5 are ignored.
3 Minimum and maximum percentiles taken from elements 4 and
5.
[4] Minimum percentile value (0-100) if pboxctl[3] = 3.
[5] Maximum percentile value (0-100) if pboxctl[3] = 3.
211
box 17. GRAPHICS REFERENCE
plctrl 1xM vector or scalar as follows:
0 Plot boxes only, no symbols.
1 Plot boxes and plot symbols which lie outside the min and max
box values.
2 Plot boxes and all symbols.
-1 Plot symbols only, no boxes.
These capabilities are in addition to the usual line control capabilities of
plctrl.
pcolor 1xM vector or scalar for symbol colors. If scalar, all symbols will be one
color.
Remarks
If missing values are encountered in the y data, they will be ignored during calculations
and will not be plotted.
Source
pbox.src
Globals
rerun, xtics, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx,
pascy, paxes, paxht, paxnum, pbox, pboxctl, pcartx, pcarty, pcolor,
pcrop, pcross, pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl,
plegctl, plegstr, pline, plotshf, plotsiz, plsel, pltype, plwidth, pmargin,
pmsgctl, pncwin, pnotify, pnum, pnumht, pqgtype, protate, pscreen,
pssel, pstype, psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal,
pxfmt, pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax,
pyscale, pysci, setpage, txtlt
212
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE contour
Purpose
To graph a matrix of contour data.
Library
pgraph
Format
contour(x,y,z);
Input
x 1xK vector, the X axis data. K must be odd.
y Nx1 vector, the Y axis data. N must be odd.
z NxK matrix, the matrix of height data to be plotted.
plev Kx1 vector, user-dened contour levels for contour. Default 0.
pzclr Nx1 or Nx2 vector. This controls the Z level colors. See surface for a
complete description of how to set this global.
Remarks
A vector of evenly spaced contour levels will be generated automatically from the z
matrix data. Each contour level will be labeled. For unlabeled contours, use ztics.
To specify a vector of your own unequal contour levels, set the vector plev before
calling contour.
To specify your own evenly spaced contour levels, see ztics.
Source
pcontour.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcrop, pcross,
pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plev,
plotshf, plotsiz, plsel, pltype, pmargin, pmsgctl, pncwin, pnotify,
pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,
ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax,
pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale, pysci, pzclr, pzfmt,
pzpmax, pzscale, setpage, txtlt
See also
surface
213
draw 17. GRAPHICS REFERENCE
Purpose
Graphs lines, symbols, and text using the PQG global variables. This procedure does
not require actual X, Y, or Z data since its main purpose is to manually build graphs
using pline, pmsgctl, psym, paxes, parrow and other globals.
Library
pgraph
Format
draw;
Remarks
draw is especially useful when used in conjunction with transparent windows.
Example
library pgraph;
graphset;
begwind;
makewind(9,6.855,0,0,0); /* make full size window for plot */
makewind(3,1,3,3,0); /* make small overlapping window for text */
setwind(1);
x = seqa(.1,.1,100);
y = sin(x);
xy(x,y); /* plot data in first window */
nextwind;
_pbox = 15;
_paxes = 0;
_pnum = 0;
_ptitlht = 1;
margin(0,0,2,0);
title("This is a text window.");
draw; /* add a smaller text window */
endwind; /* create graph */
Source
pdraw.src
214
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE draw
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross,
pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plotshf, plotsiz,
plsel, pltype, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,
pqgtype, protate, pscreen, pssel, pstype, psymsiz, ptek, pticout,
ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax, pxscale, pxsci,
pyfmt, pylabel, pypmax, pyscale, pysci, setpage, txtlt
See also
window, makewind
215
endwind 17. GRAPHICS REFERENCE
Purpose
End window manipulation, display graphs with rerun.
Library
pgraph
Format
endwind;
Remarks
This function uses rerun to display the most recently created .tkf le.
Source
pwindow.src
Globals
rerun, pageshf, pagesiz, pappend, prstw, pscreen, pwindmx, pwindno
See also
begwind, window, makewind, setwind, nextwind, getwind
216
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE fonts
Purpose
Load fonts to be used in the graph.
Library
pgraph
Format
fonts(str);
Input
str string or character vector containing the names of fonts to be used in the
plot.
Simplex standard sans serif font.
Simgrma Simplex greek, math.
Microb bold and boxy.
Complex standard font with serif.
The rst font specied will be used for the axes numbers.
If str is a null string, or fonts is not called, Simplex is loaded by default.
Remarks
See Section 16.6 for instructions on how to select fonts within a text string.
Source
pgraph.src
Globals
pfonts
See also
title, xlabel, ylabel, zlabel
217
getwind 17. GRAPHICS REFERENCE
Purpose
Retrieve the current window number.
Library
pgraph
Format
n = getwind;
Output
n scalar, window number of current window.
Remarks
The current window is the window in which the next graph will be drawn.
Source
pwindow.src
Globals
pwindno
See also
endwind, begwind, window, setwind, nextwind
218
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE graphprt
Purpose
Controls automatic printer hardcopy and conversion le output.
Library
pgraph
Format
graphprt(str);
Input
str string, control string.
Remarks
graphprt is used to create hardcopy output automatically without user intervention.
The input string str can have any of the following items, separated by spaces. If str is a
null string, the interactive mode is entered. This is the default.
-P print graph.
-PF=name set output print le name.
-PO=c set print orientation.
L landscape.
P portrait.
-PS=c set print page size.
Q quarter page.
H half page.
F full page.
-PM=l,r,t,b set print margins to left,right,top,bottom in inch units.
-PR=n set print resolution.
1 low.
2 medium.
3 high.
-C=n convert to another le format.
1 Encapsulated PostScript le.
2 Lotus .PIC le.
3 HPGL Plotter le.
4 PCX bitmap format.
219
graphprt 17. GRAPHICS REFERENCE
-CF=name set converted output le name.
-CO=n set conversion le orientation.
L landscape.
P portrait.
-CS=c set conversion le page size.
Q quarter page.
H half page.
F full page.
-CM=l,r,t,b set conversion le margins to left,right,top,bottom in inch units.
-W=n display graph, wait n seconds, then continue.
If you are not using windows, you can call graphprt anytime before the call to the
graphics routine. If you are using windows, call graphprt just before the endwind
statement.
The print option default values are obtained from the graphics conguration le. Any
parameters passed through graphprt will override the default values. See Section ??.
Under DOS this uses a utility called pqgrun. pqgrun is documented in the DOS
supplement.
Example
Automatic print using a single graphics call.
library pgraph;
graphset;
load x,y;
graphprt("-p"); /* tell "xy" to print */
xy(x,y); /* create graph and print */
Automatic print using multiple graphics windows. Note graphprt is called once just
before the endwind call.
library pgraph;
graphset;
load x,y;
begwind;
window(1,2); /* create two windows */
setwind(1);
xy(x,y); /* first graphics call */
nextwind;
xy(x,y); /* second graphics call */
graphprt("-p");
endwind; /* print page containing all graphs */
220
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE graphprt
The next example shows how to build a string to be used with graphprt.
library pgraph;
graphset;
load x,y;
prtnam = "myprint.prn"; /* name of output print file */
prtres = "1"; /* low-res print */
prtmarg= ".5,.5,.5,.5" /* page margins */
/* concatenate options into one string */
cmdstr = "-p" $+ " -pf=" $+ prtnam $+ " -pr=" $+ prtres;
cmdstr = cmdstr $+ " -pm=" $+ prtmarg;
graphprt(cmdstr); /* tell "xy" to print */
xy(x,y); /* create graph and print */
The above string cmdstr will look like this:
"-p -pf=myprint.prn -pr=1 -pm=.5,.5,.5,.5"
Source
pgraph.src
Globals
pcmdlin
See also
ptek
221
graphset 17. GRAPHICS REFERENCE
Purpose
Reset graphics globals to default values.
Library
pgraph
Format
graphset;
Remarks
This procedure is used to reset the defaults between graphs.
graphset may be called between each window to be displayed.
To change the default values of the global control variables, make the appropriate
changes in the le pgraph.dec and to the procedure graphset.
Source
pgraph.src
Globals
pageshf, pagesiz, parrow, parrow3, pascx, pascy, paxes, paxht,
paxmarx, pbartyp, pbarwid, pbox, pbox3d, pboxctl, pcolor, pcrop,
pcross, pcsel, pcwin, perrbar, pfonts, pframe, pgrid, plctrl, plegctl,
plegstr, plev, pline, pline3d, plotshf, plotsiz, plsel, pltype, plwidth,
pmargin, pmcolor, pmsgctl, pmsgstr, pncwin, pnotify, pnum, pnumht,
protate, pscreen, pssel, pstype, psurf, psym, psym3d, psymsiz, ptek,
pticout, ptitle, ptitlht, pview, pvolume, pwindmx, pworld, pxfmt,
pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale,
pysci, pzclr, pzfmt, pzlabel, pzoom, pzpmax, pzscale
222
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE hist
Purpose
Computes and graphs a frequency histogram for a vector. The actual frequencies are
plotted for each category.
Library
pgraph
Format
{ b,m,freq } = hist(x,v);
Input
x Mx1 vector of data.
v Nx1 vector, the breakpoints to be used to compute the frequencies,
or
scalar, the number of categories.
Output
b Px1 vector, the breakpoints used for each category.
m Px1 vector, the midpoints of each category.
freq Px1 vector of computed frequency counts.
Remarks
If a vector of breakpoints is specied, a nal breakpoint equal to the maximum value of
x will be added if the maximum breakpoint value is smaller.
If a number of categories is specied, the data will be divided into v evenly spaced
categories.
Each time an element falls into one of the categories specied in b, the corresponding
element of freq will be incremented by one. The categories are interpreted as follows:
freq[1] = x <= b[1]
freq[2] = b[1] < x <= b[2]
freq[3] = b[2] < x <= b[3]

freq[P] = b[P 1] < x <= b[P]


Example
223
hist 17. GRAPHICS REFERENCE
library pgraph;
x = rndn(5000,1);
{ b,m,f } = hist(x,20);
Source
phist.src
Globals
bar, pascx, pcolor, pcsel, pmcolor, pmsgctl, pmsgstr, pnum, ptitle,
pworld, pxlabel, pxpmax, pylabel
See also
histp, histf, bar
224
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE histf
Purpose
To graph a histogram given a vector of frequency counts.
Library
pgraph
Format
histf(f ,c);
Input
f Nx1 vector, frequencies to be graphed.
c Nx1 vector, numeric labels for categories. If this is a scalar 0, a sequence
from 1 to rows(f ) will be created.
Remarks
The axes are not automatically labeled. Use xlabel for the category axis and ylabel for
the frequency axis.
Source
phist.src
Globals
bar, pcolor, pcsel, pworld
See also
hist, bar, xlabel, ylabel
225
histp 17. GRAPHICS REFERENCE
Purpose
Computes and graphs a percent frequency histogram of a vector. The percentages in
each category are plotted.
Library
pgraph
Format
{ b,m,freq } = histp(x,v);
Input
x Mx1 vector of data.
v Nx1 vector, the breakpoints to be used to compute the frequencies,
or
scalar, the number of categories.
Output
b Px1 vector, the breakpoints used for each category.
m Px1 vector, the midpoints of each category.
freq Px1 vector of computed frequency counts. This is the vector of counts, not
percentages.
Remarks
If a vector of breakpoints is specied, a nal breakpoint equal to the maximum value of
x will be added if the maximum breakpoint value is smaller.
If a number of categories is specied, the data will be divided into v evenly spaced
categories.
Each time an element falls into one of the categories specied in b, the corresponding
element of freq will be incremented by one. The categories are interpreted as follows:
freq[1] = x <= b[1]
freq[2] = b[1] < x <= b[2]
freq[3] = b[2] < x <= b[3]

freq[P] = b[P 1] < x <= b[P]


226
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE histp
Source
phist.src
Globals
bar, pascx, pcolor, pcsel, pmcolor, pmsgctl, pmsgstr, pnum, ptitle,
pworld, pxlabel, pxpmax, pylabel
See also
hist, histf, bar
227
loadwind 17. GRAPHICS REFERENCE
Purpose
Load a previously saved window conguration.
Library
pgraph
Format
err = loadwind(namestr);
Input
namestr string, name of le to be loaded.
Output
err scalar, 0 if successful, 1 if window matrix is invalid. Note that the current
window conguration will be overwritten in either case.
Source
pwindow.src
Globals
pwindmx
See also
savewind
228
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE loglog
Purpose
Graphs X vs. Y using log coordinates.
Library
pgraph
Format
loglog(x,y);
Input
x Nx1 or NxM matrix. Each column contains the X values for a particular
line.
y Nx1 or NxM matrix. Each column contains the Y values for a particular
line.
Source
ploglog.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, paxes, paxht,
pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel, pcwin, pdate,
perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf, plotsiz, plsel,
pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,
pqgtype, protate, pscreen, pssel, pstype, psymsiz, ptek, pticout,
ptitle, ptitlht, pworld, pxlabel, pxscale, pylabel, pyscale, setpage,
txtlt
See also
xy, logy, logx
229
logx 17. GRAPHICS REFERENCE
Purpose
Graphs X vs. Y using log coordinates for the X axis.
Library
pgraph
Format
logx(x,y);
Input
x Nx1 or NxM matrix. Each column contains the X values for a particular
line.
y Nx1 or NxM matrix. Each column contains the Y values for a particular
line.
Source
plogx.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascy, paxes,
paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel,
pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf,
plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,
pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,
ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxlabel, pxscale, pyfmt,
pylabel, pypmax, pyscale, pysci, setpage, txtlt
See also
xy, logy, loglog
230
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE logy
Purpose
Graphs X vs. Y using log coordinates for the Y axis.
Library
pgraph
Format
logy(x,y);
Input
x Nx1 or NxM matrix. Each column represents the X values for a particular
line.
y Nx1 or NxM matrix. Each column represents the Y values for a particular
line.
Source
plogy.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, paxes,
paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel,
pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, pline,
plotshf, plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin,
pnotify, pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype,
psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel,
pxpmax, pxscale, pxsci, pylabel, pyscale, setpage, txtlt
See also
xy, logx, loglog
231
makewind 17. GRAPHICS REFERENCE
Purpose
Create a window of specic size and position and add it to the list of windows.
Library
pgraph
Format
makewind(xsize,ysize,xshft,yshft ,typ);
Input
xsize scalar, horizontal size of the window in inches.
ysize scalar, vertical size of the window in inches.
xshft scalar, horizontal distance from left edge of screen in inches.
yshft scalar, vertical distance from bottom edge of screen in inches.
typ scalar, window attribute type. If this value is 1, the windows will be
transparent. If 0, the windows will be nontransparent.
Remarks
Note that if this procedure is used when rotating the page, the passed parameters are
scaled appropriately to the newly oriented page. The size and shift values will not be
true inches when printed, but the window size to page size ratio remains the same. The
result of this implementation automates the rotation and eliminates the required
window recalculations by the user.
See the window command for creating tiled windows. For more information on using
windows see Section 16.4.
Source
pwindow.src
Globals
pagedim, pwindmx
See also
window, endwind, setwind, getwind, begwind, nextwind
232
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE margin
Purpose
Sets the margins for the current graph window.
Library
pgraph
Format
margin(l ,r,t ,b);
Input
l scalar, the left margin in inches.
r scalar, the right margin in inches.
t scalar, the top margin in inches.
b scalar, the bottom margin in inches.
Remarks
By default, the dimensions of the graph are the same as the window dimensions. With
this function the graph dimensions may be decreased. The result will be a smaller plot
area surrounded by the specied margin. This procedure takes into consideration the
axes labels and numbers for correct placement.
All input inch values for this procedure are based on a full size screen of 9 x 6.855
inches. If this procedure is used with a window, the values will be scaled to window
inches automatically.
If the axes must be placed an exact distance from the edge of the page, axmargin
should be used.
Source
pgraph.src
Globals
pmargin
See also
axmargin
233
nextwind 17. GRAPHICS REFERENCE
Purpose
Set the current window to the next available window.
Library
pgraph
Format
nextwind;
Remarks
This function selects the next available window to be the current window. This is the
window in which the next graph will be drawn.
See the discussion on using graphics windows in Section 16.4.
Source
pwindow.src
Globals
getwind, setwind
See also
endwind, begwind, setwind, getwind, makewind, window
234
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE polar
Purpose
Graph data using polar coordinates.
Library
pgraph
Format
polar(radius,theta);
Input
radius Nx1 or NxM matrix. Each column contains the magnitude for a particular
line.
theta Nx1 or NxM matrix. Each column represents the angle values for a
particular line.
Source
polar.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcsel,
pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf,
plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,
pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,
ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax,
pxscale, pyfmt, pylabel, pypmax, pyscale, setpage, txtlt
See also
xy, logx, logy, loglog, scale, xtics, ytics
235
rerun 17. GRAPHICS REFERENCE
Purpose
Displays the most recently created graphics le.
Library
pgraph
Format
rerun;
Remarks
rerun is used by the endwind function.
Under DOS, rerun invokes the graphics utility pqgrun.exe. pqgrun is documented in
the DOS supplement.
Source
pcart.src
Globals
pcmdlin, pnotify, psilent, ptek, pzoom
236
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE savewind
Purpose
Save the current window conguration to a le.
Library
pgraph
Format
err = savewind(lename);
Input
lename Name of le.
Output
err scalar, 0 if successful, 1 if window matrix is invalid. Note that the le is
written in either case.
Remarks
See the discussion on using graphics windows in Section 16.4.
Source
pwindow.src
Globals
pwindmx
See also
loadwind
237
scale 17. GRAPHICS REFERENCE
Purpose
Fix the scaling for subsequent graphs. The axes endpoints and increments are
computed as a best guess based on the data passed to it.
Library
pgraph
Format
scale(x,y);
Input
x matrix, the X axis data.
y matrix, the Y axis data.
Remarks
x and y must each have at least 2 elements. Only the minimum and maximum values
are necessary.
This routine xes the scaling for all subsequent graphs until graphset is called. This
also clears xtics and ytics whenever it is called.
If either of the arguments is a scalar missing, the main graphics function will set the
scaling for that axis using the actual data.
If an argument has 2 elements, the rst will be used for the minimum and the last will
be used for the maximum.
If an argument has 2 elements, and contains a missing value, that end of the axis will
be scaled from the data by the main graphics function.
If you want direct control over the axes endpoints and tick marks, use xtics or ytics. If
xtics or ytics have been called after scale, they will override scale.
Source
pscale.src
Globals
pworld, pxscale, pyscale
See also
xtics, ytics, ztics, scale3d
238
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE scale3d
Purpose
Fix the scaling for subsequent graphs. The axes endpoints and increments are
computed as a best guess based on the data passed to it.
Library
pgraph
Format
scale3d(x,y,z);
Input
x matrix, the X axis data.
y matrix, the Y axis data.
z matrix, the Z axis data.
Remarks
x, y and z must each have at least 2 elements. Only the minimum and maximum
values are necessary.
This routine xes the scaling for all subsequent graphs until graphset is called. This
also clears xtics, ytics and ztics whenever it is called.
If any of the arguments is a scalar missing, the main graphics function will set the
scaling for that axis using the actual data.
If an argument has 2 elements, the rst will be used for the minimum and the last will
be used for the maximum.
If an argument has 2 elements, and contains a missing value, that end of the axis will
be scaled from the data by the main graphics function.
If you want direct control over the axes endpoints and tick marks, use xtics, ytics, or
ztics. If one of these functions have been called, they will override scale3d.
Source
pscale.src
Globals
pworld, pxscale, pyscale, pzscale
See also
scale, xtics, ytics, ztics
239
setwind 17. GRAPHICS REFERENCE
Purpose
Set the current window to a previously created window number.
Library
pgraph
Format
setwind(n);
Input
n scalar, window number.
Remarks
This function selects the specied window to be the current window. This is the
window in which the next graph will be drawn.
See the discussion on using graphics windows in Section 16.4.
Source
pwindow.src
Globals
pwindmx, pwindno
See also
begwind, endwind, getwind, nextwind, makewind, window
240
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE surface
Purpose
To graph a 3-D surface.
Library
pgraph
Format
surface(x,y,z);
Input
x 1xK vector, the X axis data.
y Nx1 vector, the Y axis data.
z NxK matrix, the matrix of height data to be plotted.
Global Input
psurf 2x1 vector, controls 3-D surface characteristics.
[1] if 1, show hidden lines. Default 0.
[2] Color for base (default 7). The base is an outline of the X-Y plane
with a line connecting each corner to the surface. If 0, no base is
drawn.
pticout scalar, if 0 (default), tick marks point inward, if 1, tick marks point
outward.
pzclr Z level color control.
There are 3 ways to set colors for the Z levels of a surface graph.
1. To specify a single color for the entire surface plot, set the color
control variable to a scalar value 115. Example:
_pzclr = 15;
2. To specify multiple colors distributed evenly over the entire Z
range, set the color control variable to a vector containing the
desired colors only. GAUSS will automatically calculate the
required corresponding Z values for you. The following example
will produce a three color surface plot, the Z ranges being
lowest=blue, middle=light blue, highest=white:
241
surface 17. GRAPHICS REFERENCE
_pzclr = { 1, 10, 15 };
3. To specify multiple colors distributed over selected ranges, the Z
ranges as well as the colors must be manually input by the user.
The following example assumes -0.2 to be the minimum value in
the z matrix:
_pzclr = { -0.2 1, /* z >= -0.2 blue */
0.0 10, /* z >= 0.0 light blue */
0.2 15 }; /* z >= 0.2 white */
Since a Z level is required for each selected color, the user must be
responsible to compute the minimum value of the z matrix as the
rst Z range element. This may be most easily accomplished by
setting the pzclr matrix as shown above (the rst element being
an arbitrary value), then reset the rst element to the minimum z
value as follows:
_pzclr = { 0.0 1,
0.0 10,
0.2 15 };
_pzclr[1,1] = minc(minc(z));
Source
psurface.src
Globals
rerun, cmnlt, decreas, fontsiz, linlt, pageshf, pagesiz, pappend,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcrop, pcwin,
pdate, pfonts, plegctl, plegstr, pline3d, plotshf, plotsiz, pmargin,
pmsgctl, pncwin, pnotify, pnum, pnumht, poptic, pqgtype, prngerr,
protate, pscreen, psurf, psym3d, ptek, pticout, ptitle, ptitlht, pview,
pvolume, pworld, pxlabel, pxpmax, pxscale, pylabel, pypmax, pyscale,
pzclr, pzlabel, pzpmax, pzscale, range, setpage, txtlt
See also
volume, view
242
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE title
Purpose
To set the title for the graph.
Library
pgraph
Format
title(str);
Input
str string, the title to display above the graph.
Remarks
Up to three lines of title may be produced by embedding a line feed character (\L) in
the title string. For example,
title("First title line\L Second title line\L Third title line");
Fonts may be specied in the title string. See Section 16.6 for instructions on using
fonts.
Source
pgraph.src
Globals
ptitle
See also
xlabel, ylabel, fonts
243
view 17. GRAPHICS REFERENCE
Purpose
To set the position of the observer in workbox units for 3-D plots.
Library
pgraph
Format
view(x,y,z);
Input
x scalar, the X position in workbox units.
y scalar, the Y position in workbox units.
z scalar, the Z position in workbox units.
Remarks
The size of the workbox is set with volume. The viewer MUST be outside of the
workbox. The closer the position of the observer, the more perspective distortion there
will be. If x = y = z, the projection will be isometric.
If view is not called, a default position will be calculated.
Use viewxyz to locate the observer in plot coordinates.
Source
pgraph.src
Globals
pview
See also
volume, viewxyz
244
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE viewxyz
Purpose
To set the position of the observer in plot coordinates for 3-D plots.
Library
pgraph
Format
viewxyz(x,y,z);
Input
x scalar, the X position in plot coordinates.
y scalar, the Y position in plot coordinates.
z scalar, the Z position in plot coordinates.
Remarks
The viewer MUST be outside of the workbox. The closer the observer, the more
perspective distortion there will be.
If viewxyz is not called, a default position will be calculated.
Use view to locate the observer in workbox units.
Source
pgraph.src
Globals
pview
See also
volume, view
245
volume 17. GRAPHICS REFERENCE
Purpose
To set the length, width, and height ratios of the 3-D workbox.
Library
pgraph
Format
volume(x,y,z);
Input
x scalar, the X length of the 3-D workbox.
y scalar, the Y length of the 3-D workbox.
z scalar, the Z length of the 3-D workbox.
Remarks
The ratio between these values is what is important. If volume is not called, a default
workbox will be calculated.
Source
pgraph.src
Globals
pvolume
See also
view
246
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE window
Purpose
Partition the screen into tiled windows of equal size.
Library
pgraph
Format
window(row,col ,typ);
Input
row scalar, number of rows of windows.
col scalar, number of columns of windows.
typ scalar, window attribute type. If 1, the windows will be transparent, if 0,
the windows will be nontransparent (blanked).
Remarks
The windows will be numbered from 1 to (row)(col ) starting from the left topmost
window and moving right.
See the makewind command for creating windows of a specic size and position. For
more information see Section 16.4.
Source
pwindow.src
Globals
makewind, pagedim
See also
endwind, begwind, setwind, nextwind, getwind, makewind
247
xlabel 17. GRAPHICS REFERENCE
Purpose
To set a label for the X axis.
Library
pgraph
Format
xlabel(str);
Input
str string, the label for the X axis.
Source
pgraph.src
Globals
pxlabel
See also
title, ylabel, zlabel
248
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE xtics
Purpose
To set and x scaling, axes numbering and tick marks for the X axis.
Library
pgraph
Format
xtics(min,max,step,minordiv);
Input
min scalar, the minimum value.
max scalar, the maximum value.
step scalar, the value between major tick marks.
minordiv scalar, the number of minor subdivisions.
Remarks
This routine xes the scaling for all subsequent graphs until graphset is called.
This gives you direct control over the axes endpoints and tick marks. If xtics is called
after a call to scale, it will override scale.
X and Y axes numbering may be reversed for xy, logx, logy, and loglog graphs. This
may be accomplished by using a negative step value in the xtics and ytics functions.
Source
pscale.src
Globals
pxscale
See also
scale, ytics, ztics
249
xy 17. GRAPHICS REFERENCE
Purpose
Graphs X vs. Y using Cartesian coordinates.
Library
pgraph
Format
xy(x,y);
Input
x Nx1 or NxM matrix. Each column contains the X values for a particular
line.
y Nx1 or NxM matrix. Each column contains the Y values for a particular
line.
Remarks
Missing values are ignored when plotting symbols. If missing values are encountered
while plotting a curve, the curve will end and a new curve will begin plotting at the
next non-missing value.
Source
pxy.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross,
pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr,
plotshf, plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin,
pnotify, pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype,
psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel,
pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale, pysci,
setpage, txtlt
See also
xyz, logx, logy, loglog
250
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE xyz
Purpose
Graphs X vs. Y vs. Z using Cartesian coordinates.
Library
pgraph
Format
xyz(x,y,z);
Input
x Nx1 or NxK matrix. Each column contains the X values for a particular
line.
y Nx1 or NxK matrix. Each column contains the Y values for a particular
line.
z Nx1 or NxK matrix. Each column contains the Z values for a particular
line.
Remarks
Missing values are ignored when plotting symbols. If missing values are encountered
while plotting a curve, the curve will end and a new curve will begin plotting at the
next non-missing value.
Source
pxyz.src
Globals
rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, parrow3,
paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcolor, pcrop,
pcsel, pcwin, pdate, pfonts, plctrl, plegctl, plegstr, pline3d, plotshf,
plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,
pnum, pnumht, poptic, pqgtype, prngerr, protate, pscreen, pssel,
pstype, psym3d, psymsiz, ptek, pticout, ptitle, ptitlht, pview,
pvolume, pworld, pxlabel, pxpmax, pxscale, pylabel, pypmax, pyscale,
pzlabel, pzpmax, pzscale, range, setpage, txtlt
See also
xy, surface, volume, view
251
ylabel 17. GRAPHICS REFERENCE
Purpose
To set a label for the Y axis.
Library
pgraph
Format
ylabel(str);
Input
str string, the label for the Y axis.
Source
pgraph.src
Globals
pylabel
See also
title, xlabel, zlabel
252
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE ytics
Purpose
To set and x scaling, axes numbering and tick marks for the Y axis.
Library
pgraph
Format
ytics(min,max,step,minordiv);
Input
min scalar, the minimum value.
max scalar, the maximum value.
step scalar, the value between major tick marks.
minordiv scalar, the number of minor subdivisions.
Remarks
This routine xes the scaling for all subsequent graphs until graphset is called.
This gives you direct control over the axes endpoints and tick marks. If ytics is called
after a call to scale, it will override scale.
X and Y axes numbering may be reversed for xy, logx, logy and loglog graphs. This
may be accomplished by using a negative step value in the xtics and ytics functions.
Source
pscale.src
Globals
pyscale
See also
scale, xtics, ztics
253
zlabel 17. GRAPHICS REFERENCE
Purpose
To set a label for the Z axis.
Library
pgraph
Format
zlabel(str);
Input
str string, the label for the Z axis.
Source
pgraph.src
Globals
pzlabel
See also
title, xlabel, ylabel
254
G
r
a
p
h
i
c
s
17. GRAPHICS REFERENCE ztics
Purpose
To set and x scaling, axes numbering and tick marks for the Z axis.
Library
pgraph
Format
ztics(min,max,step,minordiv);
Input
min scalar, the minimum value.
max scalar, the maximum value.
step scalar, the value between major tick marks.
minordiv scalar, the number of minor subdivisions. If this function is used with
contour, contour labels will be placed every minordiv levels. If 0, there
will be no labels.
Remarks
This routine xes the scaling for all subsequent graphs until graphset is called.
This gives you direct control over the axes endpoints and tick marks. If ztics is called
after a call to scale3d, it will override scale3d.
Source
pscale.src
Globals
pzscale
See also
scale3d, xtics, ytics, contour
255
ztics 17. GRAPHICS REFERENCE
256
T
i
m
e

a
n
d

D
a
t
e
Chapter 18
Time and Date
GAUSS oers a comprehensive set of time and date functions. These functions aord
the user the ability to return the current time and date, to carry out most related
calculations and format the results for output. GAUSS also allows the user to perform
timed iterations.
In the year 1 AD the calendar in general use was the Julian calendar. The Gregorian
calendar that we use today was not invented until the late 1500s. This new calendar
changed the method of calculating leap years on century marks. With the Julian
system simply every fourth year was a leap year. The Gregorian system made every
fourth year a leap year with the exception of century marks which are only leap years if
divisible by 400. The British adoption of this calendar, which the GAUSS date
functions are based on, did not happen until the year 1752. In that year eleven days
were removed; September 2, 1752 was followed by September 14, 1752.
dtvnormal and utctodtv are accurate back to 1 AD. The rest of the GAUSS date
functions assume a normal Gregorian system regardless of year. Thus, they will not
account for the days taken out in September of 1752, nor will they account for all
century marks being leap years before the adoption of the Gregorian system in 1752.
The time is given by your operating system, daylight savings time is not automatically
accounted for by GAUSS in calculations.
18.1 Time and Date Formats
The Time and Date formats in GAUSS fall into one of two major categories,
matrix/vector and string. The matrix/vector formats can be used for either
257
18. TIME AND DATE
calculations or if desired for output. The string formats are, however, mostly for use as
ouput. Some manipulation of strings is possible with the use of the stof function.
A 41 vector is returned by both the date and time functions.
d = date;
d;
1997.00 /* Year */
5.00000 /* Month */
29.0000 /* Day */
56.4700 /* Hundredths of a second since midnight */
t = time;
t;
10.00 /* Hours since midnight */
17.00 /* Minutes */
33.00 /* Seconds */
13.81 /* Hundredths of a second */
These vectors can be written to a string of the desired form by passing them through
the corresponding function.
d = { 1997, 5, 29, 56.47 };
datestr(d);
5/29/97
datestrymd(d);
19970529
t = { 10, 17, 33, 13.81 };
timestr(t);
10:17:33
A list and brief description of these, and other related functions is provided in the table
in section 18.2.
Another major matrix/vector format is the dtv, or date and time vector. The dtv
vector is a 18 vector used with the dtvnormal and utctodtv functions. The format for
the dtv vector is:
Y ear Month Day Hour Min Sec DoW DiY
1955 4 21 4 16 0 4 110
258
T
i
m
e

a
n
d

D
a
t
e
18. TIME AND DATE
Where:
Year Year, four digit integer.
Month 1-12, Month in year.
Day 1-31, Day of month.
Hour 0-23, Hours since midnight.
Min 0-59, Minutes.
Sec 0-59, Seconds.
DoW 0-6, Day of week, 0=Sunday.
DiY 0-365, Days since Jan 1 of current year.
dtvnormal normalizes a date. The last two elements are ignored for input, as shown in
the following example. They are set to the correct values on output. The input can be
18 or N8.
dtv = { 1954 3 17 4 16 0 0 0 };
dtv = dtvnormal(dtv);
1954 3 17 4 16 0 3 75
dtv[3] = dtv[3] + 400;
print dtv;
1954 3 417 4 16 0 3 75
dtv = dtvnormal(dtv);
print dtv;
1955 4 21 4 16 0 4 110
18.2 Time and Date Functions
Following is a partial listing of the time and date functions available in GAUSS.
datestr Formats a Date vector to a string (mo/dy/yr).
datestrymd Formats a Date vector to an eight character
string of the type yyyymmdd.
dayinyr Returns day number in the year of a given date.
daypryr Returns the number of days in the years given as input.
dtvnormal Normalizes a 1x8 dtv vector.
etdays Computes the dierence in days between two dates.
259
18. TIME AND DATE
ethsec Computes the dierence between two times in
hundredths of a second.
etstr Formats a time dierence measured in hundreths
of a second to a string.
isleap Returns a vector of ones and zeros, 1 if leap year 0 if not.
timestr Formats a Time vector to a string hr:mn:sc.
timeutc Universal time coordinate, number of seconds since
January 1, 1970 Greenwich Mean Time.
utctodtv Converts a scalar, number of seconds since, or before, Jan 1
1970 Greenwich mean time, to a dtv vector.
Below is an example of two ways to calculate a time dierence.
d1 = { 1996, 12, 19, 82 };
d2 = { 1997, 4, 28, 4248879.3 };
dif = ethsec(d1,d2);
ds = etstr(dif);
dif = 1.1274488e +09
ds = 130days 11hours 48minutes 7.97seconds
If only the number of days is needed use etdays.
d1 = { 1996, 12, 19, 82 };
d2 = { 1997, 4, 28, 4248879.3 };
dif = etdays(d1,d2);
dif = 130.00000
The last element of d1 is optional when used as an input for etdays.
isleap returns a matrix of ones and zeros, ones when the corresponding year is a leap
year.
x = seqa(1970,1,20);
y = _isleap(x);
delif(x,abs(y-1));
1972.0000 /* Vector containing all leap years
1976.0000 between 1970 - 1989 */
1980.0000
1984.0000
1988.0000
260
T
i
m
e

a
n
d

D
a
t
e
18. TIME AND DATE
To calculate the days of a number of consecutive years:
x = seqa(1983,1,3);
y = _daypryr(x);
sumc(y);
1096.0000
To add a portion of the following year:
g = { 1986, 2, 23, 0 };
dy = dayinyr(g);
sumc(y)+dy;
1150.0000
For more information on any of these functions see their respective pages in the
command reference.
18.2.1 Timed Iterations
Iterations of a program can be timed with the use of the hsec function in the following
manner.
et = hsec; /* Start timer */
/* Segment of code to be timed */
et = (hsec-et)/100; /* Stop timer, convert to seconds */
A specic example is located in the tutorial section of your supplement.
In the case of a program running from one day into the next you would need to replace
the hsec function with the date function. The ethsec function should be used to
compute the time dierence; a straight subtraction as in the previous example will not
give the desired result.
261
18. TIME AND DATE
dstart = date; /* Start timer */
/* Segment of code to be timed */
dend = date; /* Stop timer */
dif = ethsec(dstart,dend)/100; /* Convert time difference to seconds */
262
U
t
i
l
i
t
i
e
s
Chapter 19
Utility: atog
atog is a utility program to convert ASCII les into GAUSS data les. atog can
convert delimited and packed ASCII les into GAUSS data sets.
From DOS:
atog cmdle
From GAUSS:
atog cmdle;
In the examples above, cmdle is the lename of the command le. If no extension is
given, .cmd will be assumed. If no command le is specied, you will be asked for one.
Pressing Enter at that point begins the interactive mode. Interactive mode allows the
user to create a command le interactively or specify information for the data
conversion directly. The Unix version of atog does not support interactive mode.
19.1 Command Summary
The following commands are supported with atog:
append Append data to an existing le.
complex Treat data as complex variables.
help Display command summary.
263
19. UTILITY: ATOG
input The name of the ASCII input le.
invar Input le variables (column names).
msym Specify missing value character.
nocheck Dont check data type or record length.
nodata Modify the header le only.
output The name of the GAUSS data set to be created.
outtyp Output data type.
outvar List of variables to be included in output le.
quit Exit without converting. Valid only in interactive mode.
run Begin executioncease keyboard input. Valid only in interactive mode.
save Controls saving of command le while in interactive mode.
The principle commands for converting an ASCII le that is delimited with spaces or
commas are given in the following simple example. These commands are placed in a
command le or typed directly into atogs interactive mode.
input agex.asc;
output agex;
invar $ race # age pay $ sex region;
outvar region age sex pay;
outtyp d;
In this example a delimited ASCII le agex.asc is converted to a double precision
GAUSS data le agex.dat. A header is created which contains the names of the
variables and other system information. The input le has 5 variables. The le will be
interpreted as having 5 columns:
column name data type
1 race character
2 AGE numeric
3 PAY numeric
4 sex character
5 region character
The output le will have 4 columns since the rst column of the input le (race) is not
included in the output variables. The columns of the output le are:
264
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
column name data type
1 region character
2 AGE numeric
3 sex character
4 PAY numeric
When using the v89 format (see create in the COMMAND REFERENCE) the header
information is stored in a separate .dht le, thus agex.dht. The v92 and v96 formats
store header information at the top of the .dat le.
If the variable is explicitly designated as a character variable, its name will be stored in
lowercase. The $ in the invar statement species that the variables that follow are
character type. The # species numeric. If $ or # are not used in an invar statement,
the default is numeric.
Comments in command les must be enclosed between @ characters.
19.2 Commands
A detailed explanation of each command follows.
append
Instructs atog to append the converted data to an existing data le.
append;
No assumptions are made regarding the format of the existing le. You should make
certain that the number, order and type of data converted match the existing le.
complex
Instructs atog to convert the ASCII le into a complex GAUSS data set.
complex;
Complex GAUSS data sets are stored by rows, with the real and imaginary parts
interleaved, element by element. atog assumes the same structure for the ASCII input
le, and will thus read TWO numbers out for EACH variable specied. complex
cannot be used with packed ASCII les.
help
Display help screen in interactive mode.
help;
265
19. UTILITY: ATOG
input
The input command species the le name of the ASCII le which is to be converted.
The full path name can be used in the le specication. For example, the command:
input data.raw;
will expect an ASCII data le in the current working directory. The command:
input /research/data/myle.asc;
species a le to be located in the /research/data subdirectory.
invar
Soft Delimited ASCII Files
Soft delimited les may have spaces, commas, or cr/lf as delimiters between elements.
Two or more consecutive delimiters with no data between them are treated as one
delimiter.
invar age $ name sex # pay var[1:10] x[005];
The invar command above species the following variables:
column name data type
1 AGE numeric
2 name character
3 sex character
4 PAY numeric
5 VAR01 numeric
6 VAR02 numeric
7 VAR03 numeric
8 VAR04 numeric
9 VAR05 numeric
10 VAR06 numeric
11 VAR07 numeric
12 VAR08 numeric
13 VAR09 numeric
14 VAR10 numeric
15 X001 numeric
16 X002 numeric
17 X003 numeric
18 X004 numeric
19 X005 numeric
As the input le is translated, the rst 19 elements will be interpreted as the rst row
(observation), the next 19 will be interpreted as the second row, and so on. If the
number of elements in the le is not evenly divisible by 19, the nal incomplete row will
be dropped and a warning message will be given.
266
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
Hard Delimited ASCII Files
Hard delimited les have a printable character as a delimiter between elements. Two
delimiters without intervening data between them will be interpreted as a missing. If
\n is specied as a delimiter, the le should have one element per line and blank lines
will be considered missings. Otherwise, delimiters must be printable characters. The
dot . is illegal and will always be interpreted as a missing value. To specify the
backslash as a delimiter, use \\. If \r is specied as a delimiter, the le will be assumed
to contain one case or record per line with commas between elements and no comma at
the end of the line.
For hard delimited les the delimit subcommand is used with the invar command. The
delimit subcommand has two optional parameters. The rst parameter is the delimiter.
The default is a comma. The second parameter is an N. If the second parameter is
present, atog will expect N delimiters. If it is not present, atog will expect N-1
delimiters.
invar delimit(, N) $ name # var[5];
would expect a le like this:
BILL , 222.3, 123.2, 456.4, 345.2, 533.2,
STEVE, 624.3, 340.3, , 624.3, 639.5,
TOM , 244.2, 834.3, 602.3, 333.4, 822.5,
invar delimit(,) $ name # var[5];
or
invar delimit $ name # var[5];
would expect a le like this:
BILL , 222.3, 123.2, 456.4, 345.2, 533.2,
STEVE, 624.3, 340.3, , 624.3, 639.5,
TOM , 244.2, 834.3, 602.3, 333.4, 822.5
The dierence between specifying N or N-1 delimiters can be seen in the following
example:
456.4, 345.2, 533.2,
, 624.3, 639.5,
602.3, 333.4,
267
19. UTILITY: ATOG
If the invar statement specied 3 variables and N-1 delimiters were specied, this le
would be interpreted as having three rows containing a missing in the 2,1 element and
the 3,3 element like this:
456.4 345.2 533.2
missing 624.3 639.5
602.3 333.4 missing
If N delimiters were specied, this le would be interpreted as having two rows, and a
nal incomplete row which is dropped:
456.4 345.2 533.2
missing 624.3 639.5
The spaces are shown only for clarity and are not signicant in delimited les so:
BILL,222.3,123.2,456.4,345.2,533.2,
STEVE,624.3,340.3,,624.3,639.5,
TOM,244.2,834.3,602.3,333.4,822.5
would work just as well. Linefeeds are signicant only if \n is specied as the delimiter
or when using \r.
invar delimit(\r) $ name # var[5];
would expect a le with no comma after the nal element in each row:
BILL , 222.3, 123.2, 456.4, 345.2, 533.2
STEVE, 624.3, 340.3, 245.3, 624.3, 639.5
TOM , 244.2, 834.3, 602.3, 333.4, 822.5
Packed ASCII Files
Packed ASCII les must have xed length records. The record subcommand is used to
specify the record length and variables are specied by giving their type, starting
position, length, and the position of an implicit decimal point if necessary.
Note that outvar is not used with packed ASCII les. Instead, invar is used to specify
only those variables to be included in the output le.
For packed ASCII les the syntax of the invar command is as follows:
invar record=reclen (format) variables (format) variables;
268
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
where,
reclen the total record length in bytes including the nal carriage return/line feed if
applicable. Records must be xed length.
format (start,length.prec) where:
start starting position of the eld in the record, 1 is the rst position. The
default is 1.
length the length of the eld in bytes. The default is 8.
prec optional, a decimal point will be inserted automatically prec places in
from the RIGHT edge of the eld.
If several variables are listed after a format denition, each succeeding eld will be
assumed to start immediately after the preceding eld. If an asterisk is used to specify
the starting position, the current logical default will be assumed. An asterisk in the
length position will select the current default for both length and prec. This is illegal:
(3,8.*).
The type change characters $ and # are used to toggle between character and numeric
data type.
Any data in the record that is not dened in a format is ignored.
The examples below assume a 32-byte record with a carriage return/line feed occupying
the last 2 bytes of each record. The data below can be interpreted in dierent ways
using dierent invar statements:
ABCDEFGHIJ12345678901234567890<CR><LF>
| | | | | |
position 1 10 20 30 31 32
invar record=32 $(1,3) group dept #(11,4.2) x[3] (*,5) y;
variable value type
group ABC character
dept DEF character
X1 12.34 numeric
X2 56.78 numeric
X3 90.12 numeric
Y 34567 numeric
invar record=32 $ dept (*,2) id # (*,5) wage (*,2) area
269
19. UTILITY: ATOG
variable value type
dept ABCDEFGH character
id IJ character
WAGE 12345 numeric
AREA 67 numeric
msym
Species the character in the input le that is to be interpreted as a missing value.
msym &;
The statement above denes the character & as the missing value character. The
default . (dot) will always be interpreted as a missing value unless it is part of a
numeric value.
nocheck
Optional, suppresses automatic checking of packed ASCII record length and output
data type. The default is to increase the record length by 2 bytes if the second record
in a packed le starts with cr/lf, and any les that have explicitly dened character
data will be output in double precision regardless of the type specied.
nodata
If specied, the .dat le which contains the data will not be modied. nodata is used
to change the variable names or to reshape the le. Since the data is not modied, the
kind of reshaping that is possible is limited. This is usually used to change the names
of the variables or to reshape a le that has one variable to have several variables and
vice versa.
output cvx;
invar x;
outtyp d;
nodata;
output
The name of the GAUSS data set. Two les will be created with the extensions .dat
and .dht for the data and header le pair. The full DOS le path is supported. For
example:
output /gauss/dat/test;
creates the les test.dat and test.dht on the /gauss/dat directory.
outtyp
Selects the numerical accuracy of the output le. Use of this command should be
dictated by the accuracy of the input data and storage space limitations. The format is:
outtyp fmt;
270
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
where fmt is:
D or 8 double precision
F or 4 single precision (default)
I or 2 integer
The ranges of the dierent formats are:
bytes data type signicant range
digits
2 integer 4 32768 X 32767
4 single precision 67 8.43x10
37
[X[ 3.37x10
+38
8 double precision 1516 4.19x10
307
[X[ 1.67x10
+308
If the output type is integer, the input numbers will be truncated to integers. If your
data has more than 6 or 7 signicant digits, you should specify outtyp as double.
Character data require outtyp d. atog automatically selects double precision when
character data is specied in the invar statement unless you have specied nocheck.
The precision of the storage selected does not aect the accuracy of GAUSS calculations
using the data. GAUSS converts all data to double precision when the le is read.
outvar
To select the variables to be placed in the GAUSS data set. The outvar command
needs only the list of variables to be included in the output data set. outvar is not used
with packed ASCII les. They can be in any order.
invar $name #age pay $sex #var[1:10] x[005];
outvar sex age x001 x003 var[1:8];
column name data type
1 sex character
2 AGE numeric
3 X001 numeric
4 X003 numeric
5 VAR01 numeric
6 VAR02 numeric
7 VAR03 numeric
8 VAR04 numeric
9 VAR05 numeric
10 VAR06 numeric
11 VAR07 numeric
12 VAR08 numeric
271
19. UTILITY: ATOG
outvar is not used with packed ASCII les.
preservecase
Optional, preserves the case of variable names. The default is nopreservcase which will
force variable names for numeric variables to upper case and character variables to
lower case.
quit
To exit atog without executing. Used in atog interactive mode only.
quit;
run
Used in atog interactive mode only. This command starts execution of a command set
that has been specied in interactive mode.
run;
save
Controls saving of interactive commands in a le.
save qdata;
This command will open a le qdata.cmd. As subsequent commands are typed in, they
will be saved in this le.
save +qdata;
This will open the le qdata.cmd and process any commands already in the le. Any
subsequent commands that are typed in will be appended to the le.
save -;
This will close the le, and stop saving commands.
If no le name is specied, the default name is atog.cmd.
19.3 Examples
The rst example is a soft delimited ASCII le called agex1.asc. The le contains
seven columns of ASCII data.
272
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
Jan 167.3 822.4 6.34E06 yes 84.3 100.4
Feb 165.8 987.3 5.63E06 no 22.4 65.6
Mar 165.3 842.3 7.34E06 yes 65.4 78.3
The atog command le agex1.cmd:
input /gauss/agex1.asc;
output agex1;
invar $month #temp pres vol $true var[02];
outvar month true temp pres vol;
The output data set will contain the following information:
name month true TEMP PRES VOL
case 1 Jan yes 167.3 822.4 6.34e+6
case 2 Feb no 165.8 987.3 5.63e+6
case 3 Mar yes 165.3 842.3 7.34e+6
type char char numeric numeric numeric
The data set is double precision since character data is explicitly specied.
The second example is a packed ASCII le xlod.asc which contains 32-character
records.
AEGDRFCSTy02345678960631567890<CR><LF>
EDJTAJPSTn12395863998064839561<CR><LF>
GWDNADMSTy19827845659725234451<CR><LF>
| | | | | |
position 1 10 20 30 31 32
The atog command le xlod.cmd:
input /gauss/dat/xlod.asc;
output xlod2;
invar record=32 $(1,3) client[2] zone (*,1) reg #(20,5) zip;
The output data set will contain the following information:
name client1 client2 zone reg ZIP
case 1 AEG DRF CST y 60631
case 2 EDJ TAJ PST n 98064
case 3 GWD NAD MST y 59725
type char char char char numeric
273
19. UTILITY: ATOG
The data set is double precision since character data is explicitly specied.
The third example is a hard delimited ASCII le called cplx.asc. The le contains six
columns of ASCII data.
456.4, 345.2, 533.2, -345.5, 524.5, 935.3,
-257.6, 624.3, 639.5, 826.5, 331.4, 376.4,
602.3, -333.4, 342.1, 816.7, -452.6, -690.8
The atog command le cplx.cmd:
input /gauss/cplx.asc;
output cplx;
invar delimit #cvar[3];
complex;
The output data set will contain the following information:
name cvar1 cvar2 cvar3
case 1 456.4 + 345.2i 533.2 - 345.5i 524.5 + 935.3i
case 2 -257.6 + 624.3i 639.5 + 826.5i 331.4 + 376.4i
case 3 602.3 - 333.4i 342.1 + 816.7i -452.6 - 690.8i
type numeric numeric numeric
The data set defaults to single precision since no character data is present, and no
outtyp command is specied.
19.4 Error Messages
atog - Cant find input file
The ASCII input le could not be opened.
1. The le is not there.
2. You are out of le handles. Check the config.sys le on the root directory of
the disk you boot from to make sure it has a les=25 or greater statement.
atog - Cant open output file
The output le could not be opened.
274
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
1. The disk or directory is full.
2. You are out of le handles. Check the config.sys le on the root directory of
the disk you boot from to make sure it has a les=25 or greater statement.
atog - Cant open temporary file
Notify Aptech Systems of the circumstances of this error.
atog - Cant read temporary file
Notify Aptech Systems of the circumstances of this error.
atog - Character data in output file
Setting output file to double precision
The output le contains character data. The type was set to double precision
automatically.
atog - Character data longer than 8 bytes were truncated
The input le contained character elements longer than 8 bytes. The conversion
continued and the character elements were truncated to 8 bytes.
atog - Disk Full
The output disk is full. The output le is incomplete.
atog - Found character data in numeric field
This is a warning that character data was found in a variable that was specied as
numeric. The conversion will continue.
atog - Header file rename unsuccessful
The temporary header le atog.$dh could not be renamed. This could be a disk full
problem. atog.$dh has been left on the disk and can be renamed manually if you want
to recover from the error.
atog - Illegal command
An unrecognizable command was found in a command le.
atog - Internal error
Notify Aptech Systems of the circumstances of this error.
atog - Invalid delimiter
275
19. UTILITY: ATOG
The delimiter following the backslash is not supported.
atog - Invalid output type
Output type must be I, F, or D.
atog - Missing value symbol not found
No missing value was specied in an msym statement.
atog - No Input file
No ASCII input le was specied. The input command is probably missing.
atog - No input variables
No input variable names were specied. The invar statement may be missing.
atog - No output file
No output le was specied. The output command is probably missing.
atog - output type d required for character data
Character data in output file will be lost
Output le contains character data and is not double precision.
atog - Open comment
The command le has a comment that is not closed. Comments must be enclosed in
@s.
@ comment @
atog - Out of memory
Notify Aptech Systems of the circumstances of this error.
atog - read error
A read error has occurred while converting a packed ASCII le.
atog - Read error on .dht file
The temporary header le atog.$dh could not be read.
atog - Record length must be 1-16384 bytes
276
U
t
i
l
i
t
i
e
s
19. UTILITY: ATOG
The record subcommand has an out of range record length.
atog - Statement too long
Command le statements must be less than 16384 bytes.
atog - Syntax error at:
There is unrecognizable syntax in a command le.
atog - Too many input variables
More input variables were specied than available memory permitted.
atog - Too many output variables
More output variables were specied than available memory permitted.
atog - Too many variables
More variables were specied than available memory permitted.
atog - Undefined variable
A variable requested in an outvar statement was not listed in an invar statement.
ATOG WARNING: missing ) at:
The parentheses in the delimit subcommand were not closed.
ATOG WARNING: some records begin with cr/lf
A packed ASCII le has some records that begin with a carriage return/linefeed. The
record length may be wrong.
atog - complex illegal for packed ASCII file.
A complex command was encountered following an invar command with record
specied.
atog - Cannot read packed ASCII. (complex specified)
An invar command with record specied was encountered following a complex
command.
277
19. UTILITY: ATOG
278
U
t
i
l
i
t
i
e
s
Chapter 20
Utility: liblist
liblist is a library symbol listing utility.
It is a stand-alone program that lists the symbols available to the GAUSS autoloading
system. liblist will also perform .g le conversion and listing operations.
Note that .g les are specic les once used in older versions of GAUSS. Due to
compiler eciency and other reasons, .g les are no longer recommended for use. The
liblist options related to .g les are supplied to aid the user in consolidating .g les
and converting them to the standard .src les.
The format for using liblist from the operating system is:
liblist -ags lib1 lib2 ... libn
ags control ags to specify the operation of liblist.
G list all .g les in the current directory and along the src path.
D create gfile.lst using all .g les in the current directory and along the
src path.
C convert .g les to .src les and list the les in srcfile.lst.
L list the contents of the specied libraries.
N list library names.
P send listing to printer (lpt1).
F use page breaks and form feed characters.
I assume complex library extensions (.lcg).
279
20. UTILITY: LIBLIST
The search is performed in the following manner:
1. List all symbols available as .g les in the current directory and then the
src path.
2. List all symbols dened in .l32 les (.lcg les if you included the I control ag)
in the lib path subdirectory. gauss.lcg, if it exists, will be listed last.
20.1 Report Format
The listing produced will go to the standard output. The order the symbols will be
listed in is the same order that they will be found by GAUSS, except that liblist
processes the .lcg les in the order they appear in the lib path subdirectory, whereas
GAUSS processes libraries according to the order specied in your library statement.
liblist assumes that all of your libraries are active, i.e., you have listed them all in a
library statement. gauss.lcg will be listed last.
The listing looks like this:
Symbol Type File Library Path
====================================================================
1. autoreg ------ autoreg .src auto.lcg /gauss/src
2. autoprt ------ autoreg .src auto.lcg /gauss/src
3. autoset ------ autoreg .src auto.lcg /gauss/src
4. _pticout matrix pgraph .dec pgraph.lcg /gauss/src
5. _pzlabel string pgraph .dec pgraph.lcg /gauss/src
6. _pzpmax matrix pgraph .dec pgraph.lcg /gauss/src
7. asclabel proc pgraph .src pgraph.lcg /gauss/src
8. fonts proc pgraph .src pgraph.lcg /gauss/src
9. graphset proc pgraph .src pgraph.lcg /gauss/src
10. _svdtol matrix svd .dec gauss.lcg /gauss/src
12. __maxvec matrix system .dec gauss.lcg /gauss/src
13. besselj proc bessel .src gauss.lcg /gauss/src
14. bessely proc bessel .src gauss.lcg /gauss/src
15. xcopy keyword dos .src gauss.lcg /gauss/src
16. atog keyword dos .src gauss.lcg /gauss/src
Symbol is the symbol name available to the autoloader.
Type is the symbol type. If the library is not strongly typed, this will be a line of
dashes.
File is the le the symbol is supposed to be dened in.
Library is the name of the library, if any, the symbol is listed in.
Path is the path the le is located on. If the le cannot be found, the path will be
*** not found ***.
280
U
t
i
l
i
t
i
e
s
20. UTILITY: LIBLIST
20.2 Using liblist
liblist is executed from the operating system or GAUSS with:
liblist -ags lib1 lib2 ... libn
To put the listing in a le called lib.lst:
liblist -l > lib.lst
To convert all your .g les and list them in srcfile.lst:
liblist -c
The numbers are there so you can sort the listing if you want and still tell which
symbol would be found rst by the autoloader. You may have more than one symbol
by the same name in dierent les. liblist can help you keep them organized so you
dont inadvertently use the wrong one.
281
20. UTILITY: LIBLIST
282
C
a
t
e
g
o
r
i
c
a
l

R
e
f
e
r
e
n
c
e
Chapter 21
Categorical Reference
This categorical reference lists those commands that either operate dierently under
GAUSS for UNIX than other platforms, or are supported only under GAUSS for
UNIX. For a general categorical reference of commands, see chapter ??.
21.1 Window Control
WinOpenPQG Open a PQG window.
WinOpenText Open a Text window.
WinOpenTTY Open a TTY window.
WinSetActive Set the active window.
WinGetActive Get the active window.
WinMove Move a window.
WinResize Resize a window.
WinPan Pan through a window.
WinRefresh Refresh a window.
WinRefreshArea Refresh a rectangular area of a Text window.
WinClose Close a window.
WinCloseAll Close all windows except Window 1
WinSetTextWrap Set the text wrap mode for a window.
WinSetRefresh Set the refresh mode for a window.
WinGetAttributes Get attributes for a window.
283
21. CATEGORICAL REFERENCE
21.2 Console I/O
con Request input, create matrix.
cons Request input, create string.
key Return the next key in the input buer of the active
window. If none are pending, return 0.
keyw Return the next key in the input buer of the active
window. If none are pending, wait for one.
wait Wait until a key is pressed in the active window.
waitc Flush input buer of the active window, then wait until a
key is pressed in it.
key can be used to trap most keystrokes. For example, the following loop will trap the
ALT-H key combination:
kk = 0;
do until kk == 1035;
kk = key;
if not key;
sleep(0.5);
endif;
endo;
Other key combinations, function keys and cursor key movement can also be trapped.
key and keyw have the same return values.
21.3 Output
WinSetCursor Set the cursor position for a window.
WinGetCursor Get the cursor position for a window.
WinPrint Print formatted data to a window.
WinClear Clear a window.
WinClearArea Clear a rectangular area of a Text window.
WinClearTTYLog Clear the output log of a TTY window.
WinPrintPQG Print PQG graph to le or printer.
WinZoomPQG Display enlarged area of PQG graph.
WinSetColorCells Set color cell RGB values for a window.
WinGetColorCells Get color cell RGB values for a window.
WinSetForeground Set the foreground color for a window.
284
C
a
t
e
g
o
r
i
c
a
l

R
e
f
e
r
e
n
c
e
21. CATEGORICAL REFERENCE
WinSetBackground Set the background color for a window.
WinSetColormap Select a standard colormap for a window.
FontLoad Load a system font.
FontUnload Unload a system font.
FontUnloadAll Unload all system fonts.
output Open/close auxiliary output for the active window.
outwidth Set line width of auxiliary output for the active window.
print Print formatted data to the active window.
printdos Print string to the active window (calls C printf()),
emulate ANSI.SYS commands.
printfm Print matrix to the active window, use specied format.
print on[o Turn auto print on/o for the active window.
screen on[o Direct/suppress print statements to the active window.
screen out Dump snapshot of the active window to its auxiliary output.
plot Draw text style XY plot in the active window.
plotsym Set symbol used for plot in the active window.
cls Clear the active window.
font Set font to be used in the active window.
color Set foreground, background / colorcells for the active window.
csrcol Get column position of cursor in the active window.
csrlin Get line (row) position of cursor in the active window.
csrtype Sets the cursor shape.
format Dene print format for the active window.
locate Position the cursor in the active window.
tab Tab the cursor in the active window.
scroll Scroll a section of the active window.
setvmode Set the active window to emulate DOS video mode.
The results of all printing may be sent to an output le using output. This le can
then be printed or ported as an ASCII le to other software. A separate output le can
be opened for each window.
locate acts like tab in TTY windows. The row argument is ignored.
scroll is supported only for Text windows.
21.4 Error Handling and Debugging
errorlog Send error message to Window 1 and error log le.
285
21. CATEGORICAL REFERENCE
21.5 Workspace Management
new Clear current workspace, close all windows except Window 1.
21.6 Program Control
end Terminate a program, close all windows except Window 1.
stop Terminate a program, leave all windows open.
system Quit GAUSS and return to the OS.
Both stop and end terminate the execution of a program. end closes all open windows
except for Window 1; stop leaves all windows open. Neither stop or end is required to
terminate a GAUSS program; if neither is found, an implicit stop is executed.
286
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
Chapter 22
Command Reference
The command reference is broken into two sections. This rst section details commands
that operate dierently under GAUSS for UNIX and GAUSS for other operating
systems. The second section denes commands that are supported only under GAUSS
for UNIX.
cls cls clears the active window. For Text windows, this means
the window buer is cleared to the background color. For TTY
windows, the current output line is panned to the top of the
window, eectively clearing the display. The output log is
still intact. To clear the output log of a TTY window, use
WinClearTTYLog. For PQG windows, the window is
cleared to the background color, and the graphics data
are discarded.
color color aects the active window. X supports foreground and
background colors. The color command makes no distinction
between text and pixel colors; both aect the foreground color
of the active window. If both a pixel color and text color are
specied, the pixel color will be ignored, and the text color
will be used to set the foreground color.
287
22. COMMAND REFERENCE
con con gets input from the active window. If you are working
in terminal mode, GAUSS will not see any input until you
press Enter, so follow each entry with an Enter.
cons cons gets input from the active window. If you are working
in terminal mode, GAUSS will not see your input until you
press Enter.
csrcol csrcol returns the cursor column for the active window.
For Text windows, this value is the cursor column with respect
to the text buer. For TTY windows, this value is the cursor
column with respect to the current output line.
For PQG windows, this value is meaningless.
csrlin csrlin returns the cursor line for the active window.
For Text windows, this value is the cursor row with respect
to the text buer. For TTY windows, this value is the current
output line number (i.e., the number of lines logged + 1).
For PQG windows, this value is meaningless.
end end closes all windows except window 1. If you want to leave a
programs windows open, use stop.
errorlog errorlog prints to window 1 and the error log le.
format format sets the print statement format for the active window.
Each window remembers its own format, even when it is no
longer the active window.
key key gets input from the active window. If you are working
in terminal mode, key doesnt see any keystrokes until
Enter is pressed.
288
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE
keyw keyw gets the next key from the input buer of the active
window. If the input buer is empty, keyw waits for a
keystroke. If you are working in UNIX terminal mode,
GAUSS will not see any input until you press the Enter key.
locate locate locates the cursor in the active window. The row
argument is ignored for window 1 and TTY windows,
making locate act like tab in those windows.
new new closes all open windows except window 1.
output output commands aect the active window. Each window
remembers its own settings, even when it is no longer
the active window.
Each window can have its own auxiliary output le, or
several windows can write to the same output le.
outwidth outwidth aects the active window. Each window
remembers its own setting, even when it is no longer
the active window.
plot plot writes to the active window. Supported only for
Text windows.
print print writes to the active window. The refresh setting of
the window determines when output is displayed. To force
immediate display, use the /ush ag:
print /ush expr1 expr2 ...;;
289
22. COMMAND REFERENCE
print on[o print on[o aects the active window. Each window
remembers its own setting, even when it is no longer
the active window.
printdos printdos writes to the active window. The refresh setting of
the window determines when output is displayed. To force
immediate display, use the WinRefresh command.
printfm printfm writes to the active window. The refresh setting of
the window determines when output is displayed. To force
immediate display, use the WinRefresh command.
screen on[o screen on[o aects the active window. Each window
remembers its own setting, even when it is no longer
the active window.
screen out screen out aects the active window. Not supported for
PQG windows.
scroll scroll scrolls a region of the active window. Supported
only for Text windows.
setvmode setvmode aects the active window. This command forces
the active window into a DOS emulation mode, and is
supported for backwards compatibility only. Window size,
resolution, font and/or colormap may be changed to
accomodate the requested video mode. Not supported for
window 1 and TTY windows.
stop stop does not close any windows. If you want to close a
290
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE
programs windows when it is done, use end.
tab tab tabs the cursor in the active window. tab is not supported
in terminal mode.
wait wait waits for a keystroke in the active window. If you are
working in terminal mode, wait doesnt see any keystrokes
until Enter is pressed.
waitc waitc ushes the input buer of the active window, then
waits for a new keystroke in the active window. If you are
working in terminal mode, waitc doesnt see any keystrokes
until Enter is pressed.
The rest of the command reference denes the commands that are supported only
under GAUSS for UNIX.
291
font 22. COMMAND REFERENCE
Purpose
Set the font for the active window.
Format
oldfonth = font(fonthandle);
Input
fonthandle scalar, font handle or 1.
Output
oldfonth scalar, handle of previous font.
Remarks
font sets the font for the active window to fonthandle and returns the handle of the
windows previous font in oldfonth. If fonthandle = 1, font returns the current font
handle without changing it.
font is not supported for PQG windows.
292
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE FontLoad
Purpose
Load a font.
Format
fonthandle = FontLoad(fontspec);
Input
fontspec string, font specication.
Output
fonthandle scalar, font handle.
Remarks
FontLoad loads the X11 font specied in fontspec, where fontspec is a standard X11
font name, and may contain the wildcard characters and ?.
If the font is successfully loaded, FontLoad returns a GAUSS font handle which is used
in other routines (e.g., font, WinGetAttributes) to refer to the font.
If the font requested cannot be loaded, FontLoad returns a 1.
Font handles 1 through 4 are reserved by GAUSS; font handles returned by FontLoad
are 5.
293
FontUnload 22. COMMAND REFERENCE
Purpose
Unload a font.
Format
ret = FontUnload(fonthandle);
Input
fonthandle scalar, font handle.
Output
ret scalar, 0 if call is successful, 1 if it fails.
Remarks
FontUnload unloads the font specied by fonthandle, freeing the memory associated
with using it. If the font is still in use by a window, FontUnload will run successfully,
but the font will be maintained internally until the window relinquishes it. Then it will
be unloaded.
When a font is unloaded, you should set its handle to zero, to let your program know
that it no longer refers to a valid font. The best way to do this is:
fonthandle = FontUnload(fonthandle);
Font handles 1 through 4 are reserved by GAUSS, and cannot be unloaded.
294
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE FontUnloadAll
Purpose
Unload all currently loaded fonts.
Format
FontUnloadAll;
Remarks
FontUnloadAll unloads all the currently loaded fonts, freeing the memory associated
with using them. If any of the fonts are still in use by any windows, FontUnloadAll will
run successfully, but the fonts in use will be maintained internally until relinquished.
Then they will be unloaded.
When fonts are unloaded, you should set their handles to zero, to let your program
know that they no longer refer to valid fonts. The easiest way to do this is:
clear f1, f2[,f3...];
Font handles 1 through 4 are reserved by GAUSS, and cannot be unloaded.
295
WinClear 22. COMMAND REFERENCE
Purpose
Clear a window.
Format
WinClear(whandle);
Input
whandle scalar, window handle.
Remarks
WinClear clears the window to the background color. The eect of WinClear on
window data depends upon the window type, as follows:
If whandle is a PQG window, the current graphics data are discarded. The image can
only be restored by repeating the sequence of commands that originally generated it.
If whandle is a Text window, its text buer is cleared, destroying all data for the
window. The previous contents of the window can only be restored by repeating the
sequence of commands that originally generated it.
If whandle is a TTY window, the current output line is panned to the top of the
window. Window data is not aected.
See also
WinClearTTYLog
296
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinClearArea
Purpose
Clear a rectangular region of a Text window.
Format
WinClearArea(whandle,row,col ,nrows,ncols);
Input
whandle scalar, window handle.
row scalar, the topmost row to clear.
col scalar, the leftmost column to clear.
nrows scalar, the number of rows to clear.
ncols scalar, the number of columns to clear.
Remarks
WinClearArea clears a rectangular region of a Text window to the background color.
The region has its top-left corner at (row,col ), and is nrowsncols in size.
The corresponding region of the text buer is cleared, destroying all data for the
region. The previous contents of the region can only be restored by repeating the
sequence of commands that originally generated it.
WinClearArea is supported only for Text windows.
297
WinClearTTYLog 22. COMMAND REFERENCE
Purpose
Clear the output log of a TTY window.
Format
WinClearTTYLog(ttywhandle);
Input
ttywhandle scalar, window handle of a TTY window.
Remarks
WinClearTTYLog deletes the output log of a TTY window, destroying the window
data. The window is automatically cleared and refreshed.
See also
WinClear
298
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinClose
Purpose
Close a window.
Format
ret = WinClose(whandle);
Input
whandle scalar, window handle.
Output
ret scalar 0.
Remarks
WinClose closes (destroys) the window specied by whandle. When a window is closed,
GAUSS destroys all of the internal information required to maintain the window. Any
further commands which reference whandle will result in an error.
When a window is closed, the window handle should be set to to zero, to let your
program know that it no longer refers to a valid window. The easiest way to do this is:
wh = WinClose(wh);
If you close the active window, you will have no active window. To set a new one, use
WinSetActive.
Window 1 cannot be closed.
299
WinCloseAll 22. COMMAND REFERENCE
Purpose
Close all windows except window 1.
Format
WinCloseAll;
Remarks
WinCloseAll closes all open windows except window 1.
You should set the aected window handles to zero after a WinCloseAll, to let your
program know that they no longer refer to valid windows. The easiest way to do this is:
clear wh1, wh2 [,wh3...];
If window 1 is not the active window, you will have no active window. To set a new
one, use WinSetActive.
The end command also closes all open windows (except window 1). If you want to
terminate a program but leave its windows open, use stop.
300
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinGetActive
Purpose
Get the active window.
Format
whandle = WinGetActive;
Output
whandle scalar, the active window handle.
Remarks
WinGetActive returns the window handle of the active window. If there is no active
window, WinGetActive returns a 1.
301
WinGetAttributes 22. COMMAND REFERENCE
Purpose
Get window attributes.
Format
wattr = WinGetAttributes(whandle);
Input
whandle scalar, window handle.
Output
wattr 251 vector, window attributes, or scalar -1 if error.
PQG Window
[1] X window position in pixels
[2] Y window position in pixels
[3] X window size in pixels
[4] Y window size in pixels
[5] unused
[6] unused
[7] unused
[8] colormap
[9] foreground color
[10] background color
[11] aspect ratio attribute
[12] unused
[13] resizing attribute
[14] x pixel at left edge
[15] y pixel at top edge
[16] GAUSS window handle
[17] system window handle
[18] active window ag
[19] window type
[20] unused
[21] unused
[22] unused
302
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinGetAttributes
[23] bits per pixel
[24] unused
[25] unused
Text Window
[1] X window position in pixels
[2] Y window position in pixels
[3] window rows
[4] window columns
[5] buer rows
[6] buer columns
[7] font (handle)
[8] colormap
[9] foreground color
[10] background color
[11] text wrapping mode
[12] automatic refresh mode
[13] resizing attribute
[14] buer row at top of window
[15] buer column at left side of window
[16] GAUSS window handle
[17] system window handle
[18] active window ag
[19] window type
[20] cursor text row
[21] cursor text column
[22] cursor type
[23] bits per pixel
[24] character height in pixels
[25] character width in pixels
TTY Window
[1] X window position in pixels
[2] Y window position in pixels
[3] window rows
303
WinGetAttributes 22. COMMAND REFERENCE
[4] window columns
[5] number of lines to log
[6] number of lines logged
[7] font (handle)
[8] colormap
[9] foreground color
[10] background color
[11] text wrapping mode
[12] automatic refresh mode
[13] resizing attribute
[14] buer line at top of window
[15] buer column at left of window
[16] GAUSS window handle
[17] system window handle
[18] active window ag
[19] window type
[20] cursor text row (number of lines logged+1)
[21] cursor text column
[22] cursor type
[23] bits per pixel
[24] character height in pixels
[25] character width in pixels
Remarks
WinGetAttributes returns the attributes of the window specied by whandle. If
whandle is 1, the attributes of the GAUSS command window are returned. If whandle
is 2, the attributes of the GAUSS help window are returned.
wattr[1] and wattr[2] indicate the position on the display of the upper left corner of the
window border (i.e., the border the window manager supplies).
wattr[3] and wattr[4] indicate the size of the window. For PQG windows, these values
are given in pixels, for Text and TTY windows, these values are given in rows and
columns.
wattr[8] is the colormap number as specied in the WinSetColormap command.
For a PQG window, wattr[11] indicates whether the aspect ratio is xed or not. For
Text and TTY windows it indicates how text is wrapped. wattr[12] indicates how the
window is refreshed. wattr[13] indicates how the window can be resized.
304
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinGetAttributes
wattr[14] and wattr[15] indicate the buer coordinates at the upper left corner of Text
windows. For TTY windows, wattr[14] indicates the line of the output log displayed at
the top of the window.
wattr[16], the GAUSS window handle, is the handle ID assigned by GAUSS. wattr[17],
the system window handle, is the handle ID assigned by the window manager. All
GAUSS functions that take a window handle expect a GAUSS window handle.
wattr[18] indicates whether this window is the active window (1 = true, 0 = false).
wattr[22] is the cursor type number as specied in the csrtype command.
See WinOpenPQG, WinOpenText, and WinOpenTTY for details on window
attributes.
305
WinGetColorCells 22. COMMAND REFERENCE
Purpose
Get normalized RGB values from a window colormap.
Format
rgb = WinGetColorCells(whandle,cellidx);
Input
whandle scalar, window handle.
cellidx N1 vector, color cell indices.
Output
rgb N3 matrix, RGB settings of color cells.
Remarks
Each row of rgb contains the RGB values for the color cell specied in the
corresponding row of cellidx. The RGB values are normalized to range from 0.0 (black)
to 1.0 (full intensity). The columns are laid out as follows:
[.,1] red values
[.,2] green values
[.,3] blue values
If any row of cellidx contains an invalid color cell index, the corresponding row of rgb
will contain 1 in each column.
306
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinGetCursor
Purpose
Get the cursor position for a Text or TTY window.
Format
{ r,c } = WinGetCursor(whandle);
Input
whandle scalar, window handle.
Output
r scalar, cursor row position.
c scalar, cursor column position.
Remarks
If whandle is a Text window, (r,c) species the location of the cursor in the window
buer. If whandle is a TTY window, r species the current output line (i.e., the
number of lines logged + 1), c species the cursor location on that line. If whandle is a
PQG window, r and c are meaningless.
For a Text window, the upper left corner of the buer is (1,1). For a TTY window, the
rst column of the line is column 1.
307
WinMove 22. COMMAND REFERENCE
Purpose
Move a window.
Format
WinMove(whandle,x,y);
Input
whandle scalar, window handle.
x scalar, X window position in pixels.
y scalar, Y window position in pixels.
Remarks
WinMove moves the window specied by whandle to the position (x,y). (x,y) species
the position on the display of the upper left corner of the window border (i.e., the
border supplied by the window manager). The upper left corner of the display is (0,0).
(x,y) can specify an o-screen location.
To use the current value of x or y, set that argument to a missing value.
308
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinOpenPQG
Purpose
Open a PQG graphics window.
Format
whandle = WinOpenPQG(wattr,wtitle,ititle);
Input
wattr 131 vector, window attributes.
[1] X window position in pixels.
[2] Y window position in pixels.
[3] X window size in pixels.
[4] Y window size in pixels.
[5] unused.
[6] unused.
[7] unused.
[8] colormap.
[9] foreground color.
[10] background color.
[11] aspect ratio attribute.
[12] unused.
[13] resizing attribute.
wtitle string, window title.
ititle string, icon title.
Output
whandle scalar, window handle.
Remarks
wattr[1] and wattr[2] specify the position on the display of the upper left corner of the
window border (i.e., the border supplied by the window manager). The upper left
corner of the display is (0,0).
wattr[8] species the colormap for the window. See WinSetColormap for the list of
valid colormap values.
309
WinOpenPQG 22. COMMAND REFERENCE
wattr[11], the aspect ratio attribute, determines whether the aspect ratio of the window
is maintained during resize and zoom actions:
0 aspect ratio can change
1 aspect ratio is xed
The aspect ratio attribute cannot be changed.
wattr[13], the resizing attribute, controls the resizing of the window as follows:
0 the window cannot be resized
1 the window can be resized only through a WinResize call
2 the window can be resized through a WinResize call or external event
(e.g., resizing with the mouse)
The resizing attribute cannot be changed.
Default values are dened for the elements of wattr as follows:
[1] 0 window position: (0, 0)
[2] 0
[3] 640 window size: 640 480
[4] 480
[5] 0 unused
[6] 0 unused
[7] 1 unused
[8] 6 colormap: 16 color
[9] 15 foreground color: white
[10] 0 background color: black
[11] 1 xed aspect ratio
[12] 0 unused
[13] 2 resize by function or mouse
To use the default value for any attribute, set that element to a missing value.
WinOpenPQG returns a 1 if it fails to open the window.
Note that opening a window does not make it the active window.
310
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinOpenText
Purpose
Open a Text window.
Format
whandle = WinOpenText(wattr,wtitle,ititle);
Input
wattr 131 vector, window attributes.
[1] X window position in pixels.
[2] Y window position in pixels.
[3] window rows.
[4] window columns.
[5] buer rows.
[6] buer columns.
[7] font (handle).
[8] colormap.
[9] foreground color.
[10] background color.
[11] text wrapping mode.
[12] automatic refresh mode.
[13] resizing attribute.
wtitle string, window title.
ititle string, icon title.
Output
whandle scalar, window handle.
Remarks
wattr[1] and wattr[2] specify the position on the display of the upper left corner of the
window border (i.e., the border supplied by the window manager). The upper left
corner of the display is (0,0).
wattr[8] species the colormap for the window. See WinSetColormap for the list of
valid colormap values.
311
WinOpenText 22. COMMAND REFERENCE
wattr[11], the text wrapping mode, controls how text is wrapped in the window buer
as follows:
0 text is word-wrapped
1 text is character-wrapped
2 text is clipped
The text wrapping mode can be changed with WinSetTextWrap.
wattr[12], the automatic refresh mode, controls how the window display is refreshed as
follows:
0 the display is refreshed whenever a newline (\n) is output
1 the display is refreshed whenever anything is output
2 the display is never automatically refreshed; you must explicitly
refresh it
The refresh mode can be changed with WinSetRefresh.
wattr[13], the resizing attribute, controls the resizing of the window as follows:
0 the window cannot be resized
1 the window can be resized only through a WinResize call
2 the window can be resized through a WinResize call or external event
(e.g., resizing with the mouse)
The resizing attribute cannot be changed.
Default values are dened for the elements of wattr as follows:
[1] 0 window position: (0, 0)
[2] 0
[3] 25 window size: 25 80
[4] 80
[5] 25 buer size: 25 80
[6] 80
[7] 1 system default font
[8] 0 system default colormap
[9] 1 system foreground color
[10] 0 system background color
[11] 1 character wrap
[12] 0 refresh on \n
[13] 2 resize by function or mouse
To use the default value for any attribute, set that element to a missing value.
WinOpenText returns a 1 if it fails to open the window.
Note that opening a window does not make it the active window.
312
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinOpenTTY
Purpose
Open a TTY window.
Format
whandle = WinOpenTTY(wattr,wtitle,ititle);
Input
wattr 131 vector, window attributes.
[1] X window position in pixels.
[2] Y window position in pixels.
[3] window rows.
[4] window columns.
[5] number of lines to log.
[6] unused.
[7] font (handle).
[8] colormap.
[9] foreground color.
[10] background color.
[11] text wrapping mode.
[12] automatic refresh mode.
[13] resizing attribute.
wtitle string, window title.
ititle string, icon title.
Output
whandle scalar, window handle.
Remarks
wattr[1] and wattr[2] specify the position on the display of the upper left corner of the
window border. The upper left corner of the display is (0,0).
wattr[8] species the colormap for the window. See WinSetColormap for the list of
valid colormap values.
313
WinOpenTTY 22. COMMAND REFERENCE
wattr[11], the text wrapping mode, controls how text is wrapped in the window as
follows:
0 text is word-wrapped
1 text is character-wrapped
2 text is clipped
The text wrapping mode can be changed with WinSetTextWrap.
wattr[12], the automatic refresh mode, controls how the window display is refreshed as
follows:
0 the display is refreshed whenever a newline (\n) is output
1 the display is refreshed whenever anything is output
2 the display is never automatically refreshed; you must explicitly
refresh it
The refresh mode can be changed with WinSetRefresh.
wattr[13], the resizing attribute, controls the resizing of the window as follows:
0 the window cannot be resized
1 the window can be resized only through a WinResize call
2 the window can be resized through a WinResize call or external event
(e.g. resizing with the mouse)
The resizing attribute cannot be changed.
Default values are dened for the elements of wattr as follows:
[1] 0 window position: (0, 0)
[2] 0
[3] 25 window size: 25 80
[4] 80
[5] 500 log 500 lines
[6] 0 unused
[7] 1 system default font
[8] 0 system default colormap
[9] 1 system foreground color
[10] 0 system background color
[11] 1 character wrap
[12] 0 refresh on \n
[13] 2 resize by function or mouse
To use the default value for any attribute, set that element to a missing value.
WinOpenTTY returns a 1 if it fails to open the window.
Note that opening a window does not make it the active window.
314
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinPan
Purpose
Pan through a Text or TTY window.
Format
WinPan(whandle,r,c);
Input
whandle scalar, window handle.
r scalar, number of rows to pan.
c scalar, number of columns to pan.
Remarks
WinPan pans through the contents of the window specied by whandle. To pan up and
left, use negative r and c. To pan down and right, use positive r and c.
WinPan is not supported for PQG windows.
315
WinPrint 22. COMMAND REFERENCE
Purpose
Print to a specied window.
Format
WinPrint [[/ush]] [[/typ]] [[/fmted]] [[/mf ]] [[/jnt]] whandle [[expr1 expr2...]];[[;]]
Input
whandle scalar, window handle.
Remarks
WinPrint and the print statement have exactly the same syntax and behavior, except
that WinPrint prints to a specied window, and print prints to the active window.
WinPrint is not supported for PQG windows.
316
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinPrintPQG
Purpose
Prints a PQG graph to a le or the printer.
Format
WinPrintPQG(whandle,prtopts);
Input
whandle scalar, window handle.
prtopts string, print options.
WinPrintPQG prints the graphics data for whandle to the system printer, or to a le, if
one is specied in prtopts.
prtopts consists of a series of option ags and their settings. Separate items in prtopts
with spaces.
The following ags and settings are dened:
-f output le name, any valid lename. File must be writeable.
-o print orientation.
L landscape
P portrait
-t printer/le type.
PS PostScript
EPS Encapsulated PostScript
HPLJET3 HP LaserJet III, IIID
HPGL Hewlett-Packard Graphics Language
PIC Lotus PIC
The le prndev.tbl in the $GAUSSHOME directory lists additional
printer/le types that are available but not tested. You can try any of the
types listed there except the type 4 entries (i.e., those with a 4 in the
second eld), which are not supported.
-r print resolution.
1 low resolution
2 medium resolution
3 high resolution
4 maximum resolution
317
WinPrintPQG 22. COMMAND REFERENCE
-m print margins, specied in inches.
left,right,top,bottom
This is a list of four decimal values. Separate margin values with commas.
Do not put any white space between values.
Example:
-m .5,.5,.5,.75
-c print color mode.
BW black/white
GRAY gray scale
RGB 16 color
-a print aspect ratio.
F xed
V variable
-g print placement.
TL top left
T top
TR top right
L left
C center
R right
BL bottom left
B bottom
BR bottom right
Flags and settings are case-sensitive.
Print options not specied in prtopts are set to their values in .gaussrc. prtopts can
be a null string.
WinPrintPQG is supported only for PQG windows.
Example
WinPrintPQG(wh, -f /tmp/graph.out -o P -t EPS);
WinPrintPQG(wh, -m 1,1,1,1.5 -a V -r 1);
WinPrintPQG(wh, -a F -g TL -m 1,1,1,4);
318
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinRefresh
Purpose
Refresh a window.
Format
WinRefresh(whandle);
Input
whandle scalar, window handle.
Remarks
WinRefresh redraws the window specied by whandle using the current contents of the
windows graphics data, text buer or output log, depending upon the window type.
This is the only way to update windows with an automatic refresh
mode = [no refresh].
319
WinRefreshArea 22. COMMAND REFERENCE
Purpose
Refresh a rectangular region of a Text window.
Format
WinRefreshArea(whandle,row,col ,nrows,ncols);
Input
whandle scalar, window handle.
row scalar, top row of area in buer to refresh.
col scalar, left column of area in buer to refresh.
nrows scalar, number of rows to refresh.
ncols scalar, number of cols to refresh.
Remarks
WinRefreshArea redraws a rectangular region of the Text window using the current
contents of the text buer. The region has its top-left corner at (row,col ), and is
nrowsncols in size.
320
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinResize
Purpose
Resize a window.
Format
WinResize(whandle,height ,width);
Input
whandle scalar, window handle.
height scalar, window height.
width scalar, window width.
Remarks
WinResize changes the size of the window specied by whandle. The position of the
upper left corner of the window remains xed.
For PQG windows, height and width are specied in pixels. The nal size of the window
may dier from the requested size. If the window was opened with xed aspect ratio,
the width will be used to calculate the height required to maintain the correct ratio.
For Text and TTY windows, height and width are specied in characters. (Thus, the
actual requested size of the window is dependent upon the window font. ) For Text
windows, the size of the window cannot be larger than the text buer.
height and width can be nonintegral, but will be truncated to integers..
To use the current value of height or width, set that argument to a missing value.
321
WinSetActive 22. COMMAND REFERENCE
Purpose
Set the active window.
Format
whout = WinSetActive(whin);
Input
whin scalar, window handle or 1.
Output
whout scalar, window handle.
Remarks
WinSetActive sets the active window to whin and returns the handle of the previous
active window in whout . If whin is 1, the active window is deactivated.
If there was no previous active window, WinSetActive returns a 1.
322
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinSetBackground
Purpose
Set the background color for the specied window.
Format
oldback = WinSetBackground(whandle,color);
Input
whandle scalar, window handle.
color scalar, color index or 1.
Output
oldback scalar, previous background color index.
Remarks
WinSetBackground sets the background color index for whandle to color and returns
the previous background color index. If color is 1, the current background color index
is returned.
323
WinSetColorCells 22. COMMAND REFERENCE
Purpose
Set one or more cells in a windows colormap.
Format
ret = WinSetColorCells(whandle,cellidx,colorspec);
Input
whandle scalar, window handle.
cellidx N1 vector, color cell indices.
colorspec N3 matrix, color specications.
Output
ret scalar, 0 if call is successful, 1 if one or more colors cant be found.
Remarks
The columns of colorspec are interpreted as follows:
[.,1] red values
[.,2] green values
[.,3] blue values
Color values can range from 0.0 (black) to 1.0 (full intensity). Values < 0.0 will be
treated as 0.0, values > 1.0 will be treated as 1.0.
Due to the X11 color handling protocol, WinSetColorCells has to regard the contents
of colorspec as color suggestions rather than color commands, but it will always give
you colors as close to the settings of colorspec as it can. See Chapter 3 for details.
WinSetColorCells attempts to change the RGB values for the specied color cells. If it
succeeds in setting all of them, it returns a 0. If it fails to set all of them specically,
if cellidx or colorspec contain any invalid values, or the system fails to reset the color
cell WinSetColorCells returns a 1.
324
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinSetColormap
Purpose
Set the colormap for a window.
Format
mapinfo = WinSetColormap(whandle,cmap);
Input
whandle scalar, window handle.
cmap scalar, colormap number or 1.
The supported colormaps are:
0 System Color
1 System BW
2 True BW
3 4 Gray
4 4 Color
5 16 Gray
6 16 Color
7 64 Gray
8 256 Color
Output
mapinfo 31 vector, colormap information.
mapinfo[1] number of colors in colormap
mapinfo[2] number of bits per pixel
mapinfo[3] current colormap number
Remarks
WinSetColormap sets the colormap for the window whandle to cmap, and returns
information about the selected colormap. If cmap = 1, no changes are made, but the
information for the current colormap is returned.
On error, scalar 0 is returned.
325
WinSetCursor 22. COMMAND REFERENCE
Purpose
Set the cursor position for a Text or TTY window.
Format
WinSetCursor(whandle,r,c);
Input
whandle scalar, window handle.
r scalar, cursor row.
c scalar, cursor column.
Remarks
If whandle is a Text window, (r,c) species where to locate the cursor in the window
buer. If whandle is 1 or a TTY window, r is ignored, and c species where to locate
the cursor on the current line.
For a Text window, the upper left corner of the buer is (1,1). For a TTY window, the
rst column of a line is column 1.
(r,c) can specify a location that is outside the buer. You can think of the buer as
covering a small region in text coordinate space; text written within the buer
bounds is remembered, text written outside it is lost.
Note that there is no right-hand boundary in a TTY window. So, if you locate to
column 254328 and begin printing, GAUSS will attempt to allocate enough memory to
store a 254K line of output.
r and c are truncated if they are not integers.
WinSetCursor is not supported for PQG windows.
326
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinSetForeground
Purpose
Set the foreground color for the specied window.
Format
oldfore = WinSetForeground(whandle,color);
Input
whandle scalar, window handle.
color scalar, color index or 1.
Output
oldfore scalar, previous foreground color index.
Remarks
WinSetForeground sets the foreground color index for whandle to color and returns
the previous foreground color index. If color is 1, the current foreground color index
is returned.
327
WinSetRefresh 22. COMMAND REFERENCE
Purpose
Set the refresh mode for a window.
Format
oldref = WinSetRefresh(whandle,refresh);
Input
whandle scalar, window handle.
refresh scalar, refresh mode.
Output
oldref scalar, previous refresh mode.
Remarks
refresh can be one of the following:
0 refresh on newline (\n); this is the system default
1 refresh on any output
2 refresh only on WinRefresh call
To get the current refresh mode, call WinGetAttributes.
WinSetRefresh is not supported for window 1 or PQG windows.
328
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
22. COMMAND REFERENCE WinSetTextWrap
Purpose
Set the text wrapping mode for a window.
Format
oldtwrap = WinSetTextWrap(whandle,textwrap);
Input
whandle scalar, window handle.
textwrap scalar, text wrapping mode.
Output
oldtwrap scalar, previous text wrapping mode.
Remarks
textwrap can be one of the following:
0 text is word-wrapped
1 text is character-wrapped
2 text is clipped
For Text windows, the text wrapping mode species how lines are stored in the window
buer. For TTY windows, the text wrapping mode species how lines are displayed in
the window. Thus, for Text windows, clipped output is actually lost, as is output that
scrolls o the top of the buer; for TTY windows, clipped output is merely displayed
dierently than wrapped output.
To get the current text wrap mode, call WinGetAttributes.
WinSetTextWrap is not supported for PQG windows.
329
WinZoomPQG 22. COMMAND REFERENCE
Purpose
Display a zoomed image in a PQG window.
Format
WinZoomPQG(whandle,x,y,xsize,ysize);
Input
whandle scalar, window handle.
x scalar, x position of zoom rectangle in pixels.
y scalar, y position of zoom rectangle in pixels.
xsize scalar, x size of zoom rectangle in pixels.
ysize scalar, y size of zoom rectangle in pixels.
Remarks
WinZoomPQG displays a zoomed image of the area specied. If the PQG window has
the aspect ratio attribute set to xed, the y size of the rectangle will be adjusted as
needed to maintain the aspect ratio.
To zoom out (that is, to redisplay the entire graph in the PQG window), use:
WinZoomPQG(whandle,0,0,0,0);
WinZoomPQG provides the same capabilities as the Zoom pop-up menu available in
the PQG windows.
For more details, consult the PQG graphics section of the manual.
WinZoomPQG is supported only for PQG windows.
330
I
n
t
r
o
d
u
c
t
i
o
n
Chapter 23
Command Reference Introduction
The COMMAND REFERENCE describes each of the commands, procedures and
functions available in the GAUSS programming language. These functions can be
roughly divided into three categories:
Mathematical, statistical and scientic functions.
Data handling routines, including data matrix manipulation and description
routines, and le I/O.
Programming statements, including branching, looping, display features, error
checking, and shell commands.
The rst category contains those functions to be expected in a high level mathematical
language: trigonometric functions and other transcendental functions, distribution
functions, random number generators, numerical dierentiation and integration
routines, Fourier transforms, Bessel functions and polynomial evaluation routines. And,
as a matrix programming language, GAUSS includes a variety of routines which
perform standard matrix operations. Among these are routines to calculate
determinants, matrix inverses, decompositions, eigenvalues and eigenvectors, and
condition numbers.
Data handling routines include functions which return dimensions of matrices, and
information about elements of data matrices, including functions to locate values lying
in specic ranges or with certain values. Also under data handling routines fall all
those functions which create, save, open and read from and write to GAUSS data sets.
A variety of sorting routines which will operate on both numeric and character data are
also available.
Programming statements are all of the commands which make it possible to write
complex programs in GAUSS. These include conditional and unconditional branching,
looping, le I/O, error handling, and system-related commands to execute OS shells
and access directory and environment information.
331
23. COMMAND REFERENCE INTRODUCTION
23.1 Using This Manual
Users who are new to GAUSS should make sure they have familiarized themselves with
Chapter 7 in Volume I before proceeding here. That chapter contains the basics of
GAUSS programming.
In all, there are over 400 routines described in this manual. We suggest that new
GAUSS users skim through Chapter 24, and then browse through the main part of this
manual, the COMMAND REFERENCE section. Here, the user can familiarize him or
herself with the kinds of tasks that GAUSS can handle easily.
Chapter 24 gives a categorical listing of all functions in the COMMAND REFERENCE
section, and a short discussion of the functions in each category. Complete syntax,
description of input and output arguments, and general remarks regarding each
function are given in the COMMAND REFERENCE section.
If a function is an extrinsic (i.e., part of the Run-Time Library), its source code can be
found on the src subdirectory. The name of the le containing the source code is given
in the COMMAND REFERENCE under the discussion of that function.
23.2 Global Control Variables
Several GAUSS functions use global variables to control various aspects of their
performance. The les gauss.ext, gauss.dec and gauss.lcg contain the external
statements, declare statements, and library references to these globals. All globals used
by the GAUSS Run-Time library begin with an underscore .
Default values for these common globals can be found in the le gauss.dec, located on
the src subdirectory. The default values can be changed by editing this le. See
Section 23.2.1 for information on how to change default values.
23.2.1 Changing the Default Values
To permanently change the default setting of a common global, two les need to be
edited: gauss.dec and gauss.src.
To change the value of the common global output from 2 to 0, for example, edit the
le gauss.dec and change the statement
declare matrix __output = 2;
so it reads:
332
I
n
t
r
o
d
u
c
t
i
o
n
23. COMMAND REFERENCE INTRODUCTION
declare matrix __output = 0;
Also, edit the procedure gausset, located in the le gauss.src, and modify the
statement
__output = 2;
similarly.
23.2.2 The Procedure gausset
The global variables aect your program, even if you have not set them directly in a
particular command le. If you have changed them in a previous run, they will retain
their changed values until you exit GAUSS or execute the new command.
The procedure gausset will reset the Run-Time Library globals to their default values.
gausset;
If your program changes the values of these globals, you can use gausset to reset them
whenever necessary. gausset resets the globals as a whole; you can write your own
routine to reset specic ones.
333
23. COMMAND REFERENCE INTRODUCTION
334
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
Chapter 24
Commands by Category
24.1 Mathematical Functions
Scientic Functions
abs Returns absolute value of argument.
arccos Computes inverse cosine.
arcsin Computes inverse sine.
atan Computes inverse tangent.
atan2 Computes angle given a point x,y.
besselj Computes Bessel function, rst kind.
bessely Computes Bessel function, second kind.
cos Computes cosine.
cosh Computes hyperbolic cosine.
exp Computes the exponential function of x.
gamma Computes gamma function value.
ln Computes the natural log of each element.
lnfact Computes natural log of factorial function.
log Computes the log
10
of each element.
pi Returns .
sin Computes sine.
sinh Computes the hyperbolic sine.
sqrt Computes the square root of each element.
tan Computes tangent.
tanh Computes hyperbolic tangent.
All trigonometric functions take or return values in radian units.
335
24. COMMANDS BY CATEGORY
Dierentiation and Integration
gradp Computes rst derivative of a function.
hessp Computes second derivative of a function.
intgrat2 Integrate a 2-dimensional function over a user-dened region.
intgrat3 Integrate a 3-dimensional function over a user-dened region.
intquad1 Integrate a 1-dimensional function.
intquad2 Integrate a 2-dimensional function over a user-dened
rectangular region.
intquad3 Integrate a 3-dimensional function over a user-dened
rectangular region.
intsimp Integrate by Simpsons method.
gradp and hessp use a nite dierence approximation to compute the rst and second
derivatives. Use gradp to calculate a Jacobian.
intquad1, intquad2, and intquad3 use Gaussian quadrature to calculate the integral of
the user-dened function over a rectangular region.
To calculate an integral over a region dened by functions of x and y, use intgrat2 and
intgrat3.
To get a greater degree of accuracy than that provided by intquad1, use intsimp for
one-dimensional integration.
Linear Algebra
balance Balances a matrix.
cond Computes condition number of a matrix.
chol Computes Cholesky decomposition, X = Y

Y .
choldn Performs Cholesky downdate on an upper triangular matrix.
cholsol Solves a system of equations given the Cholesky factorization
of a matrix.
cholup Performs Cholesky update on an upper triangular matrix.
crout Computes Crout decomposition, X = LU (real matrices only).
croutp Computes Crout decomposition with row pivoting (real matrices
only).
det Computes determinant of square matrix.
detl Computes determinant of decomposed matrix.
hess Computes upper Hessenberg form of a matrix (real matrices
only).
inv Inverts a matrix.
336
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
invpd Inverts a positive denite matrix.
invswp Generalized sweep inverse.
lu Computes LU decomposition with row pivoting (real and complex
matrices).
null Computes orthonormal basis for right null space.
null1 Computes orthonormal basis for right null space.
orth Computes orthonormal basis for column space x.
pinv Generalized pseudo-inverse: Moore-Penrose.
qqr QR decomposition: returns Q
1
and R.
qqre QR decomposition: returns Q
1
, R and a permutation vector, E.
qqrep QR decomposition with pivot control: returns Q
1
, R and E.
qr QR decomposition: returns R.
qre QR decomposition: returns R and E.
qrep QR decomposition with pivot control: returns R and E.
qtyr QR decomposition: returns Q

Y and R.
qtyre QR decomposition: returns Q

Y ,R and E.
qtyrep QR decomposition with pivot control: returns Q

Y ,R and E.
qyr QR decomposition: returns QY and R.
qyre QR decomposition: returns QY , R and E.
qyrep QR decomposition with pivot control: returns QY , R and E.
qrsol Solves a system of equations Rx = b given an upper triangular
matrix, typically the R matrix from a QR decomposition.
qrtsol Solves a system of equations R

x = b given an upper triangular


matrix, typically the R matrix from a QR decomposition.
rank Computes rank of a matrix.
rcondl Returns reciprocal of the condition number of last
decomposed matrix.
rref Computes reduced row echelon form of a matrix.
schur Computes Schur decomposition of a matrix (real matrices
only).
solpd Solves a system of positive denite linear equations.
svd Computes the singular values of a matrix.
svd1 Computes singular value decomposition, X = USV

.
svd2 Computes svd1 with compact U.
The decomposition routines are chol for Cholesky decomposition, crout and croutp for
Crout decomposition, qqrqyrep for QR decomposition, and svd, svd1, and svd2 for
singular value decomposition.
null, null1, and orth calculate orthonormal bases.
inv, invpd, solpd, cholsol, qrsol and the / operator can all be used to solve linear
systems of equations.
rank and rref will nd the rank and reduced row echelon form of a matrix.
det, detl and cond will calculate the determinant and condition number of a matrix.
337
24. COMMANDS BY CATEGORY
Eigenvalues
eig Computes eigenvalues of general matrix.
eigh Computes eigenvalues of complex Hermitian or real symmetric
matrix.
eighv Computes eigenvalues and eigenvectors of complex Hermitian
or real symmetric matrix.
eigv Computes eigenvalues and eigenvectors of general matrix.
There are four eigenvalue-eigenvector routines. Two calculate eigenvalues only, and two
calculate eigenvalues and eigenvectors. The three types of matrices handled by these
routines are:
General: eig, eigv
Symmetric or Hermitian: eigh, eighv
Polynomial Operations
polychar Computes characteristic polynomial of a square matrix.
polyeval Evaluates polynomial with given coecients.
polyint Calculates N
th
order polynomial interpolation given known
point pairs.
polymake Computes polynomial coecients from roots.
polymat Returns sequence powers of a matrix.
polymult Multiplies two polynomials together.
polyroot Computes roots of polynomial from coecients.
See also recserrc, recsercp, and conv.
Fourier Transforms
dt Computes discrete 1-D FFT.
dti Computes inverse discrete 1-D FFT.
t Computes 1- or 2-D FFT.
tn Computes 1- or 2-D FFT using prime factor algorithm.
ti Computes inverse 1- or 2-D FFT.
tm Computes multi-dimensional FFT.
tmi Computes inverse multi-dimensional FFT.
rt Computes real 1- or 2-D FFT.
338
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
rtn Computes real 1- or 2-D FFT using prime factor algorithm.
rtp Computes real 1- or 2-D FFT, returns packed format FFT.
rtnp Computes real 1- or 2-D FFT using prime factor algorithm,
returns packed format FFT.
rti Computes inverse real 1- or 2-D FFT.
rtip Computes inverse real 1- or 2-D FFT from packed format FFT.
Random Numbers
rndbeta Computes random numbers with beta distribution.
rndgam Computes random numbers with gamma distribution.
rndn Computes random numbers with Normal distribution.
rndns Computes random numbers with Normal distribution
using specied seed.
rndnb Computes random numbers with negative binomial
distribution.
rndp Computes random numbers with Poisson distribution.
rndu Computes random numbers with uniform distribution.
rndus Computes random numbers with uniform distribution
using specied seed.
rndcon Changes constant of random number generator.
rndmod Changes modulus of random number generator.
rndmult Changes multiplier of random number generator.
rndseed Changes seed of random number generator.
The random number generator can be seeded. Set the seed using rndseed or generate
the random numbers using rndus or rndns. For example:
rndseed 44435667;
x = rndu(1,1);
seed = 44435667;
x = rndus(1,1,seed);
Fuzzy Conditional Functions
feq Fuzzy ==
fge Fuzzy >=
fgt Fuzzy >
339
24. COMMANDS BY CATEGORY
e Fuzzy <=
t Fuzzy <
fne Fuzzy / =
dotfeq Fuzzy . ==
dotfge Fuzzy . >=
dotfgt Fuzzy . >
dote Fuzzy . <=
dott Fuzzy . <
dotfne Fuzzy ./ =
The global variable fcomptol controls the tolerance used for comparison. By default,
this is 1e-15. The default can be changed by editing the le fcompare.dec.
Statistical Functions
dstat Computes descriptive statistics of a data set or matrix.
conv Computes convolution of two vectors.
corrm Computes correlation matrix of a moment matrix.
corrvc Computes correlation matrix from a variance-
covariance matrix.
corrx Computes correlation matrix.
crossprd Computes cross product.
design Creates a design matrix of 0s and 1s.
meanc Computes mean value of each column of a matrix.
median Computes medians of the columns of a matrix.
moment Computes moment matrix (x

x) with special handling


of missing values.
momentd Computes moment matrix from a data set.
ols Computes least squares regression of data set or matrix.
olsqr Computes OLS coecients using QR decomposition.
olsqr2 Computes OLS coecients, residuals, and
predicted values using QR decomposition.
stdc Computes standard deviation of the columns of a matrix.
toeplitz Computes Toeplitz matrix from column vector.
vcm Computes a variance-covariance matrix from a moment matrix.
vcx Computes a variance-covariance matrix from a data matrix.
Advanced statistics and optimization routines are available in the GAUSS Applications
programs. Contact Aptech Systems for more information.
340
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
Statistical Distributions
cdfbeta Computes integral of beta function.
cdfbvn Computes lower tail of bivariate Normal cdf.
cdfchic Computes complement of cdf of
2
.
cdfchii Computes
2
abscissae values given probability
and degrees of freedom.
cdfchinc Computes integral of noncentral
2
.
cdc Computes complement of cdf of F.
cdnc Computes integral of noncentral F.
cdfgam Computes integral of incomplete function.
cdfmvn Computes multivariate Normal cdf.
cdfn Computes integral of Normal distribution: lower tail,
or cdf.
cdfn2 Computes interval of Normal cdf.
cdfnc Computes complement of cdf of Normal distribution
(upper tail).
cdftc Computes complement of cdf of t -distribution.
cdftnc Computes integral of noncentral t -distribution.
cdftvn Computes lower tail of trivariate Normal cdf.
erf Computes Gaussian error function.
erfc Computes complement of Gaussian error function.
lncdfbvn Computes natural log of bivariate Normal cdf.
lncdfmvn Computes natural log of multivariate Normal cdf.
lncdfn Computes natural log of Normal cdf.
lncdfn2 Computes natural log of interval of Normal cdf.
lncdfnc Computes natural log of complement of Normal cdf.
lnpdfn Computes Normal log-probabilities.
lnpdfmvn Computes multivariate Normal log-probabilities.
pdfn Computes standard Normal probability density function.
Series and Sequence Functions
recserar Computes autoregressive recursive series.
recsercp Computes recursive series involving products.
recserrc Computes recursive series involving division.
seqa Creates an additive sequence.
seqm Creates a multiplicative sequence.
341
24. COMMANDS BY CATEGORY
Precision Control
base10 Convert number to x.xxx and a power of 10.
ceil Round up towards +.
oor Round down towards .
prcsn Set computational precision for matrix operations.
round Round to the nearest integer.
trunc Truncate toward 0.
All calculations in GAUSS are done in double precision, with the exception of some of
the intrinsic functions on OS/2 and DOS. These may use extended precision (18-19
digits of accuracy). Use prcsn to change the internal accuracy used in these cases.
round, trunc, ceil and oor convert oating point numbers into integers. The internal
representation for the converted integer is double precision (64 bits).
Each matrix element in memory requires 8 bytes of workspace. See the function
coreleft to determine the amount of workspace available.
24.2 Matrix Manipulation
Creating Vectors and Matrices
editm Simple matrix editor.
eye Creates identity matrix.
let Creates matrix from list of constants.
medit Full-screen spreadsheet-like matrix editor.
ones Creates a matrix of ones.
zeros Creates a matrix of zeros.
Use zeros or ones to create a constant vector or matrix.
medit is a full-screen editor which can be used to create matrices to be stored in
memory, or to edit matrices that already exist.
Matrices may also be loaded from an ASCII le, from a GAUSS matrix le, or from a
GAUSS data set. For more information see the File I/O chapter in Volume I of the
manual.
342
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
Loading and Storing Matrices
loadd Load matrix from data set.
loadm Load matrix from ASCII or matrix le.
save Save matrix to matrix le.
saved Save matrix to data set.
Size, Ranking, and Range
cols Returns number of columns in a matrix.
colsf Returns number of columns in an open data set.
counts Returns number of elements of a vector falling in specied
ranges.
countwts Returns weighted count of elements of a vector falling
in specied ranges.
indexcat Returns indices of elements falling within a specied
range.
maxc Returns largest element in each column of a matrix.
maxindc Returns row number of largest element in each column
of a matrix.
minc Returns smallest element in each column of a matrix.
minindc Returns row number of smallest element in each column
of a matrix.
rankindx Returns rank index of Nx1 vector. (Rank order of
elements in vector).
rows Returns number of rows in a matrix.
rowsf Returns number of rows in an open data set.
cumprodc Computes cumulative products of each column of a
matrix.
cumsumc Computes cumulative sums of each column of a matrix.
prodc Computes the product of each column of a matrix.
sumc Computes the sum of each column of a matrix.
These functions are used to nd the minimum, maximum and frequency counts of
elements in matrices.
Use rows and cols to nd the number of rows or columns in a matrix. Use rowsf and
colsf to nd the numbers of rows or columns in an open GAUSS data set.
343
24. COMMANDS BY CATEGORY
Sparse Matrix Functions
sparseFD Converts dense matrix to sparse matrix.
sparseFP Converts packed matrix to sparse matrix.
sparseOnes Generates sparse matrix of ones and zeros.
sparseEye Creates sparse identity matrix.
sparseTD Multiplies sparse matrix by dense matrix.
sparseTrTD Multiplies sparse matrix transposed by dense matrix.
sparseSolve Solves Ax = B for x where A is a sparse matrix.
sparseHConcat Horizontally oncatenates sparse matrices.
sparseVConcat Vertically concatenates sparse matrices.
sparseSubmat Returns sparse submatrix of sparse matrix.
denseSubmat Returns dense submatrix of sparse matrix.
sparseRows Returns number of rows in sparse matrix.
sparseCols Returns number of columns in sparse matrix.
sparseNZE Returns the number of nonzero elements in sparse matrix.
isSparse Tests whether a matrix is a sparse matrix.
sparseSet Resets sparse library globals.
Miscellaneous Matrix Manipulation
rev Reverses the order of rows of a matrix.
rotater Rotates the rows of a matrix, wrapping elements
as necessary.
shiftr Shifts rows of a matrix, lling in holes with a specied
value.
reshape Reshapes a matrix to new dimensions.
vec Stacks columns of a matrix to form a single column.
vech Reshapes the lower triangular portion of a symmetric
matrix into a column vector.
vecr Stacks rows of a matrix to form a single column.
xpnd Expands a column vector into a symmetric matrix.
delif Deletes rows from a matrix using a logical expression.
diag Extracts the diagonal of a matrix.
diagrv Puts a column vector into the diagonal of a matrix.
exctsmpl Creates a random subsample of data set, with replacement.
lowmat Returns the main diagonal and lower triangle.
lowmat1 Returns a main diagonal of 1s and the lower triangle.
upmat Returns the main diagonal and upper triangle.
upmat1 Returns a main diagonal of 1s and the upper triangle.
selif Selects rows from a matrix using a logical expression.
344
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
submat Extracts a submatrix from a matrix.
trimr Trims rows from top or bottom of a matrix.
union Returns the union of two vectors.
intrsect Returns the intersection of two vectors.
setdif Returns elements of one vector that are not in another.
complex Creates a complex matrix from two real matrices.
imag Returns the imaginary part of a complex matrix.
real Returns the real part of a complex matrix.
vech and xpnd are complementary functions. vech provides an ecient way to store a
symmetric matrix; xpnd expands the stored vector back to its original symmetric
matrix.
delif and selif are complementary functions. delif deletes rows of a matrix based on a
logical comparison, and selif selects rows based on a logical comparison.
lowmat, lowmat1, upmat, and upmat1 extract triangular portions of a matrix.
To delete rows which contain missing values from a matrix in memory, see the function
packr.
24.3 Data Handling
Data Sets
close Closes an open data set (.dat le).
closeall Closes all open data sets.
create Creates and opens a data set.
eof Tests for end of le.
loadd Loads a small data set.
open Opens an existing data set.
readr Reads rows from open data set.
saved Creates small data sets.
seekr Moves pointer to specied location in open data set.
iscplxf Returns whether a data set is real or complex.
typef Returns the element size (2, 4 or 8 bytes) of
data in open data set.
writer Writes matrix to an open data set.
These functions all operate on GAUSS data sets (.dat les). See the File I/O chapter
in Volume I for more discussion.
345
24. COMMANDS BY CATEGORY
To create a GAUSS data set from a matrix in memory, use the function saved. To
create a data set from an existing one, use create. To create a data set from a large
ASCII le, use the utility atog (see Chapter 19 in Volume I).
Data sets can be opened, read from, and written to using the functions open, readr,
seekr and writer. Test for the end of a le using eof, and close the data set using close
or closeall.
The data in data sets may be typed as character or numeric. See the File I/O chapter
in Volume I, create, and vartypef.
typef returns the element size of the data in an open data set.
Data Set Variable Names
getname Returns column vector of variable names in a data set.
getnamef Returns string array of variable names in a data set.
indcv Returns column numbers of variables within a data set.
indices Retrieves column numbers and names from a data set.
indices2 Similar to indices, but matches columns with names
for dependent and independent variables.
mergevar Concatenates column vectors to create larger matrix.
makevars Decomposes matrix to create column vectors.
setvars Creates globals using the names in a data set.
vartype Determine whether variables in data set are character
or numeric.
vartypef Returns column vector of variable types (numeric/character)
in a data set.
Use getnamef to retrieve the variable names associated with the columns of a GAUSS
data set and vartypef to retrieve the variable types. Use makevars and setvars to
create global vectors from those names. Use indices and indices2 to match names with
column numbers in a data set.
getname and vartype are supported for backwards compatibility.
Data Coding
code Code the data in a vector by applying a logical set
of rules to assign each data value to a category.
dummy Creates a dummy matrix, expanding values in vector
346
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
to rows with ones in columns corresponding to true
categories and zeros elsewhere.
dummybr Similar to dummy.
dummydn Similar to dummy.
ismiss Returns 1 if matrix has any missing values, 0 otherwise.
miss Change specied values to missing value code.
missex Change elements to missing value using logical expression.
missrv Change missing value codes to specied values.
msym Set symbol to be interpreted as missing value.
packr Delete rows with missing values.
recode Similar to code, but leaves the original data in place
if no condition is met.
scalmiss Test whether a scalar is the missing value code.
substute Similar to recode, but operates on matrices.
subscat Simpler version of recode, but uses ascending bins
instead of logical conditions.
code, recode, and subscat allow the user to code data variables and operate on vectors
in memory. substute operates on matrices, and dummy, dummybr and dummydn
create matrices.
missex, missrv and miss should be used to recode missing values.
Sorting and Merging
sortc Quick-sort rows of matrix based on numeric key.
sortcc Quick-sort rows of matrix based on character key.
sortd Sort data set on a key column.
sorthc Heap-sort rows of matrix based on numeric key.
sorthcc Heap-sort rows of matrix based on character key.
sortind Returns a sorted index of a numeric vector.
sortindc Returns a sorted index of a character vector.
sortmc Sort rows of matrix on the basis of multiple columns.
uniqindx Returns a sorted unique index of a vector.
unique Remove duplicate elements of a vector.
intrleav Produces one large sorted data le from two smaller
sorted les having the same keys.
mergeby Produces one large sorted data le from two smaller
sorted les having a single key column in common.
sortc, sorthc and sortind operate on numeric data only. sortcc, sorthcc and sortindc
operate on character data only.
347
24. COMMANDS BY CATEGORY
unique and uniqindx operate on both numeric and character data.
Use sortd to sort the rows of a data set on the basis of a key column.
Both intrleav and mergeby operate on data sets.
24.4 Compiler Control
#dene Dene a case-insensitive text-replacement or ag variable.
#denecs Dene a case-sensitive text-replacement or ag variable.
#undef Undene a text-replacement or ag variable.
#ifdef Compile code block if a variable has been #dened.
#ifndef Compile code block if a variable has not been #dened.
#iight Compile code block if running GAUSS Light.
#ifdos Compile code block if running DOS.
#ifos2win Compile code block if running OS/2 or Windows.
#ifunix Compile code block if running Unix.
#else Alternate clause for #if-#else-#endif code block.
#endif End of #if-#else-#endif code block.
#include Include code from another le in program.
#lineson Compile program with line number and le name records.
#lineso Compile program without line number and le name records.
#srcle Insert source le name record at this point
(currently used when doing data loop translation).
#srcline Insert source le line number record at this point
(currently used when doing data loop translation).
These commands are compiler directives. That is, they do not generate GAUSS
program instructions; rather, they are instructions that tell GAUSS how to process a
program during compilation. They determine what the nal compiled form of a
program will be. They are not executable statements and have no eect at run-time.
See Section 7.4 for a discussion and examples of how to use compiler directives.
24.5 Program Control
Execution Control
end Terminate a program and close all les.
348
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
pause Pause for the specied time.
run Run a program in a text le.
sleep Sleep for the specied time.
stop Stop a program and leave les open.
system Quit and return to the OS.
Both stop and end will terminate the execution of a program; end will close all open
les, and stop will leave those les open. Neither stop or end is required in a GAUSS
program.
Branching
if..endif Conditional branching.
goto Unconditional branching.
pop Retrieve goto arguments.
if iter > itlim;
goto errout("Iteration limit exceeded");
elseif iter == 1;
j = setup(x,y);
else;
j = iterate(x,y);
endif;
.
.
.
errout:
pop errmsg;
print errmsg;
end;
Looping
break Jump out the bottom of a do or for loop.
continue Jump to the top of a do or for loop.
do while.. endo Loop if TRUE.
do until.. endo Loop if FALSE.
for.. endfor Loop with integer counter.
349
24. COMMANDS BY CATEGORY
iter = 0;
do while dif > tol;
{ x,x0 } = eval(x,x0);
dif = abs(x-x0);
iter = iter + 1;
if iter > maxits;
break;
endif;
if not prtiter;
continue;
endif;
format /rdn 1,0;
print "Iteration: " iter;;
format /re 16,8;
print ", Error: " maxc(dif);
endo;
for i (1, cols(x), 1);
for j (1, rows(x), 1);
x[i,j] = x[i,j] + 1;
endfor;
endfor;
Subroutines
gosub Branch to subroutine.
pop Retrieve gosub arguments.
return Return from subroutine.
Arguments can be passed to subroutines in the branch to the subroutine label and then
popped, in rst-in-last-out order, immediately following the subroutine label denition.
See the COMMAND REFERENCE for complete details.
Arguments can then be returned in an analogous fashion through the return statement.
Procedures
350
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
local Declare variables local to a procedure.
proc Begin denition of multi-line procedure.
retp Return from a procedure.
endp Terminate a procedure denition.
Here is an example of a GAUSS procedure:
proc (3) = crosprod(x,y);
local r1, r2, r3;
r1 = x[2,.].*y[3,.]-x[3,.].*y[2,.];
r2 = x[3,.].*y[1,.]-x[1,.].*y[3,.];
r3 = x[1,.].*y[2,.]-x[2,.].*y[1,.];
retp( r1,r2,r3 );
endp;
The (3) = indicates that the procedure returns three arguments. All local variables,
except those listed in the argument list, must appear in the local statement.
Procedures may reference global variables. There may be more than one retp per
procedure denition; none is required if the procedure is dened to return 0 arguments.
The endp is always necessary and must appear at the end of the procedure denition.
Procedure denitions cannot be nested. The syntax for using this example function is:
{ a1,a2,a3 } = crosprod(u,v);
See Chapters 9 and 10 for more details.
Libraries
call Call function and discard return values.
declare Initialize variables at compile time.
external External symbol denitions.
library Set up list of active libraries.
lib Build or update a GAUSS library.
call allows functions to be called when return values are not needed. This is especially
useful if a function produces printed output (dstat, ols for example) as well as return
values.
351
24. COMMANDS BY CATEGORY
Compiling
compile Compiles and saves a program to a .gcg le.
saveall Saves the contents of the current workspace to a le.
use Loads previously compiled code.
save Saves the compiled image of a procedure to disk.
loadp Loads compiled procedure.
GAUSS procedures and programs may be compiled to disk les. By then using this
compiled code, the time necessary to compile programs from scratch is eliminated. Use
compile to compile a command le. All procedures, matrices and strings referenced by
that program will be compiled as well.
Stand-alone applications may be created by running compiled code under the
Run-Time Module. Contact Aptech Systems for more information on this product.
To save the compiled images of procedures that do not make any global references, use
the save command. This will create an .fcg le. To load the compiled procedure into
memory, use loadp. This is not recommended because of the restriction on global
references and the need to explicitly load the procedure in each program that references
it. This is here to maintain backward compatibility with previous versions.
24.6 OS Functions
cdir Returns current directory.
chdir Change directory interactively.
ChangeDir Change directory in program.
dfree Returns free space on disk.
shell Shells to OS.
envget Get an environment string.
exec Execute an executable program le.
leinfo Takes a le specication, returns names and information of
les that match.
les Takes a le specication, returns names of les that match.
lesa Takes a le specication, returns names of les that match.
24.7 Workspace Management
352
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
clear Set matrices equal to 0.
clearg Set global symbols to 0.
coreleft Returns amount of workspace memory left.
maxvec Returns maximum allowed vector size.
delete Delete specied global symbols.
new Clear current workspace.
show Display global symbol table.
iscplx Returns whether a matrix is real or complex.
hasimag Examines matrix for nonzero imaginary part.
type Returns type of argument (matrix or string).
typecv Returns type of symbol (argument contains
the name of the symbol to be checked).
When working with limited workspace, it is a good idea to clear large matrices that are
no longer needed by your program.
coreleft is most commonly used to determine how many rows of a data set may be read
into memory at one time.
24.8 Error Handling and Debugging
debug Execute a program under the source level debugger.
disable Disable invalid operation interrupt of coprocessor.
error Create user-dened error code.
errorlog Send error message to screen and log le.
enable Enable invalid operation interrupt of coprocessor.
#lineson Include line number and le name records in program.
#lineso Omit line number and le name records from program.
ndpchk Examine status word of coprocessor.
ndpclex Clear coprocessor exception ags.
ndpcntrl Set and get coprocessor control word.
scalerr Test for a scalar error code.
trace Trace program execution for debugging.
trap Control trapping of program errors.
trapchk Examine the trap ag.
To trap coprocessor overows, invalid operations, divide by zero, and other exceptions,
use ndpchk. To clear these exceptions, use ndpclex. To set exceptions to be checked,
use ndpcntrl.
To trace the execution of a program, use trace.
User-dened error codes may be generated using error.
353
24. COMMANDS BY CATEGORY
24.9 String Handling
chrs Convert ASCII values to a string.
ftocv Convert an NxK matrix to a character matrix.
ftos Convert a oating point scalar to string.
getf Load ASCII or binary le into string.
loads Loads a string le (.fst le).
lower Convert a string to lowercase.
putf Writes a string to disk le.
stof Convert a string to oating point scalar.
strindx Find starting location of one string in another string.
strlen Returns length of a string.
strrindx Find starting location of one string in another string,
searching from the end to the start of the string.
strsect Extract a substring of a string.
upper Changes a string to uppercase.
vals Convert a string to ASCII values.
varget Access the global variable named by a string.
varput Assign a global variable named by a string.
vargetl Access the local variable named by a string.
varputl Assign a local variable named by a string.
strlen, strindx, strrindx, and strsect can be used together to parse strings.
Use ftos to print to a string.
To create a list of generic variable names (X1, X2, X3, X4... for example), use ftocv.
24.10 Time and Date Functions
date Returns current system date.
datestr Formats date as mm/dd/yy.
datestring Formats date as mm/dd/yyyy.
datestrymd Formats date as yyyymmdd.
dayinyr Returns day number of a date.
etdays Dierence between two times in days.
ethsec Dierence between two times in 100ths of a second.
etstr Convert elapsed time to string.
hsec Returns elapsed time since midnight in 100ths of a second.
time Returns current system time.
timestr Format time as hh:mm:ss.
354
C
o
m
m
a
n
d
s

b
y

C
a
t
e
g
o
r
y
24. COMMANDS BY CATEGORY
Use hsec to time segments of code. For example,
et = hsec;
x = y*y;
et = hsec - et;
will time the GAUSS multiplication operator.
24.11 Console I/O
con Request console input, create matrix.
cons Request console input, create string.
key Gets the next key from the keyboard buer. If buer
is empty, returns a 0.
keyw Gets the next key from the keyboard buer. If buer
is empty, waits for a key.
wait Wait for a keystroke.
waitc Flush buer, then wait for a keystroke.
key can be used to trap most keystrokes. For example, the following loop will trap the
ALT-H key combination:
kk = 0;
do until kk == 1035;
kk = key;
endo;
Other key combinations, function keys and cursor key movement can also be trapped.
See key in the COMMAND REFERENCE.
cons and con can be used to request information from the console. keyw, wait and
waitc will wait for a keystroke.
24.12 Output Functions
Text Output
355
24. COMMANDS BY CATEGORY
comlog Control interactive command logging.
output Redirect print statements to auxiliary output.
outwidth Set line width of auxiliary output.
print Print to screen.
print [[on[o]] Turn auto screen print on and o.
printfm Print matrices using a dierent format for each column.
screen [[on[o]] Direct/suppress print statements to screen.
screen out Dump snapshot of screen to auxiliary output.
lpos Returns print head position in printer buer.
lprint Print expression to the printer.
lprint [[on[o]] Switch auto printer mode on and o.
lpwidth Species printer width.
lshow Print global symbol table on the printer.
plot Plot elements of two matrices in text mode.
plotsym Controls data symbol used by plot.
cls Clear the screen.
color Set pixel, text, background colors.
csrcol Get column position of cursor on screen.
csrlin Get row position of cursor on screen.
edit Edits a le with the GAUSS editor.
ed Access an alternate editor.
format Denes format of matrix printing.
locate Position the cursor on the screen.
printdos Print a string for special handling by the OS.
scroll Scroll a section of the screen.
tab Position the cursor on the current line.
The results of all printing may be sent to an output le using output. This le can
then be printed or ported as an ASCII le to other software.
printdos can be used to print in reverse video, or using dierent colors. It requires that
ansi.sys be installed.
To produces boxes, etc. using characters from the extended ASCII set, use chrs.
Screen Graphics
graph Set pixels.
setvmode Set video mode.
color Set color.
line Draw lines.
The function graph allows the user to plot individual pixels.
356
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e
Chapter 25
Command Reference
357
abs 25. COMMAND REFERENCE
Purpose
Returns the absolute value or complex modulus of x.
Format
y = abs(x);
Input
x NK matrix.
Output
y NK matrix containing absolute values of x.
Example
x = rndn(2,2);
y = abs(x);
x =
0.675243 1.053485
0.190746 1.229539
y =
0.675243 1.053485
0.190746 1.229539
In this example, a 22 matrix of Normal random numbers is generated and the
absolute value of the matrix is computed.
358
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

A
25. COMMAND REFERENCE arccos
Purpose
Computes the inverse cosine.
Format
y = arccos(x);
Input
x NK matrix.
Output
y NK matrix containing the angle in radians whose cosine is x.
Remarks
If x is complex or has any elements whose absolute value is greater than 1, complex
results are returned.
Example
x = { -1, -0.5, 0, 0.5, 1 };
y = arccos(x);
x =
1.000000
0.500000
0.000000
0.500000
1.000000
y =
3.141593
2.094395
1.570796
1.047198
0.000000
Source
trig.src
Globals
None
359
arcsin 25. COMMAND REFERENCE
Purpose
Computes the inverse sine.
Format
y = arcsin(x);
Input
x NK matrix.
Output
y NK matrix, the angle in radians whose sine is x.
Remarks
If x is complex or has any elements whose absolute value is greater than 1, complex
results are returned.
Example
x = { -1, -0.5, 0, 0.5, 1 };
y = arcsin(x);
x =
1.000000
0.500000
0.000000
0.500000
1.000000
y =
1.570796
0.523599
0.000000
0.523599
1.570796
Source
trig.src
Globals
None
360
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

A
25. COMMAND REFERENCE atan
Purpose
Returns the arctangent of its argument.
Format
y = atan(x);
Input
x NK matrix.
Output
y NK matrix containing the arctangent of x in radians.
Remarks
y will be a matrix the same size as x, containing the arctangents of the corresponding
elements of x.
For real x, the arctangent of x is the angle whose tangent is x. The result is a value in
radians in the range

2
to
+
2
. To convert radians to degrees, multiply by
180

.
For complex x, the arctangent is dened everywhere except i and -i . If x is complex, y
will be complex.
Example
x = { 2, 4, 6, 8 };
z = x/2;
y = atan(z);
y =
0.785398
1.107149
1.249046
1.325818
See also
atan2, sin, cos, pi, tan
361
atan2 25. COMMAND REFERENCE
Purpose
Compute an angle from an x,y coordinate.
Format
z = atan2(y,x);
Input
y NK matrix, the Y coordinate.
x LM matrix, EE conformable with y, the X coordinate.
Output
z max(N,L) by max(K,M) matrix.
Remarks
Given a point x,y in a Cartesian coordinate system, atan2 will give the correct angle
with respect to the positive X axis. The answer will be in radians from -pi to +pi.
To convert radians to degrees, multiply by
180

.
atan2 operates only on the real component of x, even if x is complex.
Example
x = 2;
y = { 2, 4, 6, 8 };
z = atan2(y,x);
z =
0.785398
1.107149
1.249046
1.325818
See also
atan, sin, cos, pi, tan, arcsin, arccos
362
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE balance
Purpose
Balances a square matrix.
Format
{ b,z } = balance(x)
Input
x KK matrix.
Output
b KK matrix, balanced matrix.
z KK matrix, diagonal scale matrix.
Remarks
balance returns a balanced matrix b and another matrix z with scale factors in powers
of two on its diagonal. b is balanced in the sense that the absolute sums of the
magnitudes of elements in corresponding rows and columns are nearly equal.
balance is most often used to scale matrices to improve the numerical stability of the
calculation of their eigenvalues. It is also useful in the solution of matrix equations.
In particular,
b = z
1
xz
balance uses the BALANC function from EISPACK.
Example
let x[3,3] = 100 200 300
40 50 60
7 8 9;
{ b,z } = balance(x);
b =
100.0 100.0 37.5
80.0 50.0 15.0
56.0 32.0 9.0
z =
4.0 0.0 0.0
0.0 2.0 0.0
0.0 0.0 0.5
363
band 25. COMMAND REFERENCE
Purpose
Extracts bands from a symmetric banded matrix.
Format
a = band(y,n);
Input
y KK symmetric banded matrix.
n scalar, number of subdiagonals.
Output
a K(N+1) matrix, 1 subdiagonal per column.
Remarks
y can actually be a rectangular PQ matrix. K is then dened as min(P,Q). It will be
assumed that a is symmetric about the principal diagonal for y[1:K,1:K].
The subdiagonals of y are stored right to left in a, with the principal diagonal in the
rightmost (N+1th) column of a. The upper left corner of a is unused; it is set to 0.
This compact form of a banded matrix is what bandchol expects.
Example
x = { 1 2 0 0,
2 8 1 0,
0 1 5 2,
0 0 2 3 };
bx = band(x,1);
bx =
0.0000000 1.0000000
2.0000000 8.0000000
1.0000000 5.0000000
2.0000000 3.0000000
364
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE bandchol
Purpose
Computes the Cholesky decomposition of a positive denite banded matrix.
Format
l = bandchol(a);
Input
a KN compact form matrix.
Output
l KN compact form matrix, lower triangle of the Cholesky decomposition
of a.
Remarks
Given a positive denite banded matrix A, there exists a matrix L, the lower triangle of
the Cholesky decomposition of A, such that A = L L

. a is the compact form of A;


see band for a description of the format of a.
l is the compact form of L. This is the form of matrix that bandcholsol expects.
Example
x = { 1 2 0 0,
2 8 1 0,
0 1 5 2,
0 0 2 3 };
bx = band(x,1);
bx =
0.0000000 1.0000000
2.0000000 8.0000000
1.0000000 5.0000000
2.0000000 3.0000000
cx = bandchol(bx);
cx =
0.0000000 1.0000000
2.0000000 2.0000000
0.50000000 2.1794495
0.91766294 1.4689774
365
bandcholsol 25. COMMAND REFERENCE
Purpose
Solves the system of equations Ax = b for x, given the lower triangle of the Cholesky
decomposition of a positive denite banded matrix A.
Format
x = bandcholsol(b,l );
Input
b KM matrix.
l KN compact form matrix.
Output
x KM matrix.
Remarks
Given a positive denite banded matrix A, there exists a matrix L, the lower triangle of
the Cholesky decomposition of A, such that A = L*L. l is the compact form of L; see
band for a description of the format of l .
b can have more than one column. If so, Ax = b is solved for each column. That is,
A*x[.,i] = b[.,i]
Example
x = { 1 2 0 0,
2 8 1 0,
0 1 5 2,
0 0 2 3 };
bx = band(x,1);
bx =
0.0000000 1.0000000
2.0000000 8.0000000
1.0000000 5.0000000
2.0000000 3.0000000
cx = bandchol(bx);
366
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE bandcholsol
cx =
0.0000000 1.0000000
2.0000000 2.0000000
0.50000000 2.1794495
0.91766294 1.4689774
xi = BandCholSol(eye(4),cx);
xi =
2.0731707 0.53658537 0.14634146 0.097560976
0.53658537 0.26829268 0.073170732 0.048780488
0.14634146 0.073170732 0.29268293 0.19512195
0.097560976 0.048780488 0.19512195 0.46341463
367
bandltsol 25. COMMAND REFERENCE
Purpose
Solves the system of equations Ax = b for x, where A is a lower triangular banded
matrix.
Format
x = bandltsol(b,A);
Input
b KM matrix.
A KN compact form matrix.
Output
x KM matrix.
Remarks
A is a lower triangular banded matrix in compact form. See band for a description of
the format of A.
b can have more than one column. If so, Ax = b is solved for each column. That is,
A*x[.,i] = b[.,i]
Example
bx =
0.0000000 1.0000000
2.0000000 8.0000000
1.0000000 5.0000000
2.0000000 3.0000000
cx = bandchol(bx);
cx =
0.0000000 1.0000000
2.0000000 2.0000000
0.50000000 2.1794495
0.91766294 1.4689774
xci = bandLTSol(eye(4),cx);
xci =
1.0000000 0.0000000 0.0000000 0.0000000
1.0000000 0.50000000 0.0000000 0.0000000
0.22941573 0.11470787 0.45883147 0.0000000
0.14331487 0.071657436 0.28662975 0.68074565
368
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE bandrv
Purpose
Creates a symmetric banded matrix, given its compact form.
Format
y = bandrv(a);
Input
a KN compact form matrix.
Output
y KK symmetrix banded matrix.
Remarks
a is the compact form of a symmetric banded matrix, as generated by band. a stores
subdiagonals right to left, with the principal diagonal in the rightmost (N
th
) column.
The upper left corner of a is unused. bandchol expects a matrix of this form.
y is the fully expanded form of a, a KK matrix with N-1 subdiagonals.
Example
bx =
0.0000000 1.0000000
2.0000000 8.0000000
1.0000000 5.0000000
2.0000000 3.0000000
x = bandrv(bx);
x =
1.0000000 2.0000000 0.0000000 0.0000000
2.0000000 8.0000000 1.0000000 0.0000000
0.0000000 1.0000000 5.0000000 2.0000000
0.0000000 0.0000000 2.0000000 3.0000000
369
bandsolpd 25. COMMAND REFERENCE
Purpose
Solves the system of equations Ax = b for x, where A is a positive denite banded
matrix.
Format
x = bandsolpd(b,A);
Input
b KM matrix.
A KN compact form matrix.
Output
x KM matrix.
Remarks
A is a positive denite banded matrix in compact form. See band for a description of
the format of A.
b can have more than one column. If so, Ax = b is solved for each column. That is,
A*x[.,i] = b[.,i]
370
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE base10
Purpose
Break number into a number of the form #.####... and a power of 10.
Format
{ M,P } = base10(x);
Input
x scalar, number to break down.
Output
M scalar, in the range 10 < M < 10.
P scalar, integer power such that:
M 10
P
= x
Example
{ b, e } = base10(4500);
b = 4.5000000
e = 3.0000000
Source
base10.src
Globals
None
371
besselj 25. COMMAND REFERENCE
Purpose
To compute a Bessel function of the rst kind, J
n
(x).
Format
y = besselj(n,x);
Input
n NK matrix, the order of the Bessel function. Nonintegers will be
truncated to an integer.
x LM matrix, EE conformable with n.
Output
y max(N,L) by max(K,M) matrix.
Example
n = { 0, 1 };
x = { 0.1 1.2, 2.3 3.4 };
y = besselj(n,x);
y =
0.99750156 0.67113274
0.53987253 0.17922585
See also
bessely, mbesseli
372
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

B
25. COMMAND REFERENCE bessely
Purpose
To compute a Bessel function of the second kind (Webers function), Y
n
(x).
Format
y = bessely(n,x);
Input
n NK matrix, the order of the Bessel function. Nonintegers will be
truncated to an integer.
x LM matrix, EE conformable with n.
Output
y max(N,L) by max(K,M) matrix.
Example
n = { 0, 1 };
x = { 0.1 1.2, 2.3 3.4 };
y = bessely(n,x);
y =
1.5342387 0.22808351
0.052277316 0.40101529
See also
besselj, mbesseli
373
break 25. COMMAND REFERENCE
Purpose
Breaks out of a do or for loop.
Format
break;
Example
x = rndn(4,4);
r = 0;
do while r < rows(x);
r = r + 1;
c = 0;
do while c < cols(x);
c = c + 1;
if c == r;
x[r,c] = 1;
elseif c > r;
break; /* terminate inner do loop */
else;
x[r,c] = 0;
endif;
endo; /* break jumps to the statement after this endo */
endo;
x =
1.000 0.326 2.682 0.594
0.000 1.000 0.879 0.056
0.000 0.000 1.000 0.688
0.000 0.000 0.000 1.000
Remarks
This command works just like in C.
See also
continue, do, for
374
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE call
Purpose
Calls a function or procedure when the returned value is not needed and can be
ignored, or when the procedure is dened to return nothing.
Format
call function name(argument list);
call function name;
Remarks
This is useful when you need to execute a function or procedure and do not need the
value that it returns. It can also be used for calling procedures that have been dened
to return nothing.
function name can be any intrinsic GAUSS function, a procedure (proc), or any valid
expression.
Example
call chol(x);
y = detl;
The above example is the fastest way to compute the determinant of a positive denite
matrix. The result of chol is discarded and detl is used to retrieve the determinant that
was computed during the call to chol.
See also
proc
375
cdfbeta 25. COMMAND REFERENCE
Purpose
Computes the incomplete beta function (i.e., the cumulative distribution function of
the beta distribution).
Format
y = cdfbeta(x,a,b);
Input
x NK matrix.
a LM matrix, EE conformable with x.
b PQ matrix, EE conformable with x and a.
Output
y max(N,L,P) by max(K,M,Q) matrix.
Remarks
y is the integral from 0 to x of the beta distribution with parameters a and b.
Allowable ranges for the arguments are:
0 x 1
a > 0
b > 0
A -1 is returned for those elements with invalid inputs.
Example
x = { .1, .2, .3, .4 };
a = 0.5;
b = 0.3;
y = cdfbeta(x,a,b);
y =
0.142285
0.206629
0.260575
0.310875
376
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfbeta
See also
cdfchic, cdc, cdfn, cdfnc, cdftc, gamma
Technical Notes
cdfbeta has the following approximate accuracy:
max(a,b) 500 the absolute error is approx. 5e13
500 < max(a,b) 10, 000 the absolute error is approx. 5e11
10, 000 < max(a,b) 200, 000 the absolute error is approx. 1e9
200, 000 < max(a,b) Normal approximations are used and
the absolute error is approx. 2e9
References:
1. ALGORITHM 179 INCOMPLETE BETA RATIO, O.G. Ludwig,
Comm. ACM, Vol. 6, No. 6, pp. 314, June 1963
2. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, M.C.
Pike and I.D. Hill, Comm. ACM, Vol. 10, No. 6, pp. 375-6, June. 1967
3. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, N. E.
Bosten and E.L. Battiste, Comm. ACM, Vol. 17, No. 3, pp. 156-7, March
1974
4. ASYMPTOTICALLY PEARSONS TRANSFORMATIONS, L.N.
Bolshev, Teor. Veroyat. Primen. (Theory of Probability and its
Applications), Vol. 8, No. 2, pp. 129-155, 1963
5. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND
OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer
and J.W. Pratt, Journal of American Statistical Association Journal, Vol.
63, pp. 1416-1456, Dec. 1968.
6. Tables of the F- and related distributions with algorithms, K.V. Mardia
and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5
377
cdfbvn 25. COMMAND REFERENCE
Purpose
Computes the cumulative distribution function of the standardized bivariate Normal
density (lower tail).
Format
c = cdfbvn(h,k,r);
Input
h NK matrix, the upper limits of integration for variable 1.
k LM matrix, EE conformable with h, the upper limits of integration for
variable 2.
r PQ matrix, EE conformable with h and k, the correlation coecients
between the two variables.
Output
c max(N,L,P) by max(K,M,Q) matrix, the result of the double integral from
to h and to k of the standardized bivariate Normal density
f(x, y, r).
Remarks
The function integrated is:
f(x, y, r) =
e
0.5w
2

1 r
2
with
w =
x
2
2rxy +y
2
1 r
2
Thus, x and y have 0 means, unit variances, and correlation = r.
Allowable ranges for the arguments are:
< h < +
< k < +
1 r 1
A -1 is returned for those elements with invalid inputs.
To nd the integral under a general bivariate density, with x and y having nonzero
means and any positive standard deviations, use the transformation equations:
378
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfbvn
h = (ht - ux) ./ sx;
k = (kt - uy) ./ sy;
where ux and uy are the (vectors of) means of x and y, sx and sy are the (vectors of)
standard deviations of x and y, and ht and kt are the (vectors of) upper integration
limits for the untransformed variables, respectively.
See also
cdfn, cdftvn
Technical Notes
The absolute error for cdfbvn is approximately 5.0e9 for the entire range of
arguments.
References:
1. A Table of Normal Integrals, D.B. Owen, Commun. Statist.-Simula.
Computa., B9(4), pp. 389-419, 1980
2. Computation of Bi- and Tri-variate Normal Integral, D.J. Daley, Appl.
Statist., Vol. 23, No. 3, pp. 435-438, 1974
379
cdfchic 25. COMMAND REFERENCE
Purpose
Computes the complement of the cdf of the chi-square distribution.
Format
y = cdfchic(x,n)
Input
x NK matrix.
n LM matrix, EE conformable with x.
Output
y max(N,L) by max(K,M) matrix.
Remarks
y is the integral from x to of the chi-square distribution with n degrees of freedom.
The elements of n must all be positive integers. The allowable ranges for the arguments
are:
x 0
n > 0
A -1 is returned for those elements with invalid inputs.
This equals 1 F(x, n), where F is the chi-square cdf with n degrees of freedom. Thus,
to get the chi-square cdf, subtract cdfchic(x,n) from 1. The complement of the cdf is
computed because this is what is most commonly needed in statistical applications, and
because it can be computed with fewer problems of roundo error.
Example
x = { .1, .2, .3, .4 };
n = 3;
y = cdfchic(x,n);
380
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfchic
y =
0.991837
0.977589
0.960028
0.940242
See also
cdfbeta, cdc, cdfn, cdfnc, cdftc, gamma
Technical Notes
For n 1000, the incomplete gamma function is used and the absolute error is approx.
6e13. For n > 1000, a Normal approximation is used and the absolute error is
2e8.
For higher accuracy when n > 1000, use:
1-cdfgam(0.5*x,0.5*n);
References:
1. ALGORITHM AS 32, THE INCOMPLETE GAMMA INTEGRAL,
G.P. Bhattacharjee, Applied Statistics, Vol. 19, pp. 285-287, 1970.
2. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND
OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer
and J.W. Pratt, Journal of American Statistical Association Journal, Vol.
63, pp. 1416-1456, Dec. 1968.
3. Tables of the F- and related distributions with algorithms, K.V. Mardia
and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5
381
cdfchii 25. COMMAND REFERENCE
Purpose
Compute chi-square abscissae values given probability and degrees of freedom.
Format
c = cdfchii(p,n);
Input
p MN matrix, probabilities.
n LK matrix, EE conformable with p, degrees of freedom.
Output
c max(M,L) by max(N,K) matrix, abscissae values for chi-square
distribution.
Example
The following generates a 33 matrix of pseudo-random numbers with a chi-squared
distribution with expected value of 4:
rndseed 464578;
x = cdfchii(rndu(3,3),4+zeros(3,3));
x =
2.1096456 1.9354989 1.7549182
4.4971008 9.2643386 4.3639694
4.5737473 1.3706243 2.5653688
Globals
gammaii
Source
cdfchii.src
382
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfchinc
Purpose
The integral under noncentral chi-square distribution, from 0 to x. It can return a
vector of values, but the degrees of freedom and noncentrality parameter must be the
same for all values of x.
Format
y = cdfchinc(x,v,d);
Input
x N1 vector, values of upper limits of integrals, must be greater than 0.
v scalar, degrees of freedom, v > 0.
d scalar, noncentrality parameter, d > 0.
This is the square root of the noncentrality parameter that sometimes goes
under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,
1959, app. IV.
Output
y N1 vector, integrals from 0 to x of noncentral chi-square.
Technical Notes
Relation to cdfchic:
cdfchic(x,v) = 1 - cdfchinc(x,v,0);
The formula used is taken from Abramowitz and Stegun, HANDBOOK
OF MATHEMATICAL FUNCTIONS, 1970, p. 942, formula 26.4.25.
Example
x = { .5, 1, 5, 25 };
p = cdfchinc(x,4,2);
0.0042086234
0.016608592
0.30954232
0.99441140
Source
cdfnonc.src
Globals
None
See also
cdnc, cdftnc
383
cdc 25. COMMAND REFERENCE
Purpose
Computes the complement of the cdf of the F distribution.
Format
y = cdc(x,n1,n2);
Input
x NK matrix.
n1 LM matrix, EE conformable with x.
n2 PQ matrix, EE conformable with x and n1.
Output
y max(N,L,P) by max(K,M,Q) matrix
Remarks
y is the integral from x to of the F distribution with n1 and n2 degrees of freedom.
Allowable ranges for the arguments are:
x 0
n1 > 0
n2 > 0
A -1 is returned for those elements with invalid inputs.
This equals 1 G(x, n1, n2), where G is the F cdf with n1 and n2 degrees of freedom.
Thus, to get the F cdf, subtract cdc(x,n1,n2) from 1. The complement of the cdf is
computed because this is what is most commonly needed in statistical applications, and
because it can be computed with fewer problems of roundo error.
Example
x = { .1, .2, .3, .4 };
n1 = 0.5;
n2 = 0.3;
y = cdffc(x,n1,n2);
384
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdc
y =
0.751772
0.708152
0.680365
0.659816
See also
cdfbeta, cdfchic, cdfn, cdfnc, cdftc, gamma
Technical Notes
For max(n1,n2) 1000, the absolute error is approx. 5e13. For max(n1,n2) > 1000,
Normal approximations are used and the absolute error is approx. 2e6.
For higher accuracy when max(n1,n2) > 1000, use:
cdfbeta(n2/(n2+n1*x), n2/2, n1/2);
References:
1. ALGORITHM 179 INCOMPLETE BETA RATIO, O.G. Ludwig,
Comm. ACM, Vol. 6, No. 6, pp. 314, June 1963
2. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, M.C.
Pike and I.D. Hill, Comm. ACM, Vol. 10, No. 6, pp. 375-6, June. 1967
3. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, N. E.
Bosten and E.L. Battiste, Comm. ACM, Vol. 17, No. 3, pp. 156-7, March
1974
4. ASYMPTOTICALLY PEARSONS TRANSFORMATIONS, L.N.
Bolshev, Teor. Veroyat. Primen. (Theory of Probability and its
Applications), Vol. 8, No. 2, pp. 129-155, 1963
5. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND
OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer
and J.W. Pratt, Journal of American Statistical Association Journal, Vol.
63, pp. 1416-1456, Dec. 1968.
6. Tables of the F- and related distributions with algorithms, K.V. Mardia
and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5
7. Statistical Computing, W.J. Kennedy, Jr. and J.E. Gentle, Marcel Dekker,
Inc., New York, 1980.
385
cdnc 25. COMMAND REFERENCE
Purpose
The integral under noncentral F distribution, from 0 to x.
Format
y = cdnc(x,v1,v2,d);
Input
x N1 vector, values of upper limits of integrals, x > 0.
v1 scalar, degrees of freedom of numerator, v1 > 0.
v2 scalar, degrees of freedom of denominator, v2 > 0.
d scalar, noncentrality parameter, d > 0.
This is the square root of the noncentrality parameter that sometimes goes
under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,
1959, app. IV.
Output
y N1 vector of integrals from 0 to x of noncentral F.
Technical Notes
Relation to cdc:
cdc(x,v1,v2) = 1 - cdnc(x,v1,v2,0);
The formula used is taken from Abramowitz and Stegun, HANDBOOK
OF MATHEMATICAL FUNCTIONS, 1970, p. 947, formula 26.6.20.
Source
cdfnonc.src
Globals
None
See also
cdftnc, cdfchinc
386
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfgam
Purpose
Incomplete gamma function.
Format
g = cdfgam(x,intlim);
Input
x NK matrix of data.
intlim LM matrix, EE compatible with x, containing the integration limit.
Output
g max(N,L) by max(K,M) matrix.
Remarks
The incomplete gamma function returns the integral

intlim
0
e
t
t
(x1)
gamma(x)
dt
The allowable ranges for the arguments are:
x > 0
intlim 0
A -1 is returned for those elements with invalid inputs.
Example
x = { 0.5 1 3 10 };
intlim = seqa(0,.2,6);
g = cdfgam(x,intlim);
x = 0.500000 1.00000 3.00000 10.0000
intlim =
0.000000
0.200000
0.400000
0.600000
0.800000
1.000000
387
cdfgam 25. COMMAND REFERENCE
g =
0.000000 0.000000 0.000000 0.000000
0.472911 0.181269 0.00114848 2.35307E 014
0.628907 0.329680 0.00792633 2.00981E 011
0.726678 0.451188 0.0231153 9.66972E 010
0.794097 0.550671 0.0474226 1.43310E 008
0.842701 0.632120 0.0803014 1.11425E 007
This computes the integrals over the range from 0 to 1, in increments of .2, at the
parameter values 0.5, 1, 3, 10.
Technical Notes
cdfgam has the following approximate accuracy:
x < 500 the absolute error is approx. 6e13
500 x 10, 000 the absolute error is approx. 3e11
10, 000 < x a Normal approximation is used and
the absolute error is approx. 3e10
References:
1. ALGORITHM AS 32, THE INCOMPLETE GAMMA INTEGRAL,
G.P. Bhattacharjee, Applied Statistics, Vol. 19, pp. 285-287, 1970.
2. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND
OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer
and J.W. Pratt, Journal of American Statistical Association Journal, Vol.
63, pp. 1416-1456, Dec. 1968.
3. Tables of the F- and related distributions with algorithms, K.V. Mardia
and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5
388
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfmvn
Purpose
Computes multivariate Normal cumulative distribution function.
Format
y = cdfmvn(x,r);
Input
x KL matrix, abscissae.
r KK matrix, correlation matrix.
Output
y L1 vector, Pr(X < x[r).
See also
cdfbvn, cdfn, cdftvn, lncdfmvn
Source
lncdfn.src
389
cdfn, cdfnc 25. COMMAND REFERENCE
Purpose
cdfn computes the cumulative distribution function (cdf) of the Normal distribution.
cdfnc computes 1 minus the cdf of the Normal distribution.
Format
n = cdfn(x);
nc = cdfnc(x);
Input
x NK matrix.
Output
n NK matrix.
nc NK matrix.
Remarks
n is the integral from to x of the Normal density function, and nc is the integral
from x to +.
Note that: cdfn(x) + cdfnc(x) = 1. However, many applications expect cdfn(x) to
approach 1, but never actually reach it. Because of this, we have capped the return
value of cdfn at 1 machine epsilon, or approximately 1 1.11e16. As the relative
error of cdfn is about 5e15 for cdfn(x) around 1, this does not invalidate the result.
What it does mean is that for abs(x) > (approx.)8.2924, the identity does not hold
true. If you have a need for the uncapped value of cdfn, the following code will return
it:
n = cdfn(x);
if n >= 1-eps;
n = 1;
endif;
where the value of machine epsilon is obtained as follows:
x = 1;
do while 1-x /= 1;
eps = x;
x = x/2;
endo;
390
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfn, cdfnc
Note that this is an alternate denition of machine epsilon. Machine epsilon is usually
dened as the smallest number such that 1 + machine epsilon > 1, which is about
2.23e16. This denes machine epsilon as the smallest number such that
1 machine epsilon < 1, or about 1.11e16.
The erf and erfc functions are also provided, and may sometimes be more useful than
cdfn and cdfnc.
Example
x = { -2 -1 0 1 2 };
n = cdfn(x);
nc = cdfnc(x);
x = 2.00000 1.00000 0.00000 1.00000 2.00000
n = 0.02275 0.15866 0.50000 0.84134 0.97725
nc = 0.97725 0.84134 0.50000 0.15866 0.02275
See also
erf, erfc, cdfbeta, cdfchic, cdftc, cdc, gamma
Technical Notes
For the integral from to x:
x 37, cdfn underows and 0.0 is returned
36 < x < 10, cdfn has a relative error of approx. 5e12
10 < x < 0, cdfn has a relative error of approx. 1e13
0 < x, cdfn has a relative error of approx. 5e15
For cdfnc, i.e., the integral from x to +, use the above accuracies but change x to x.
References:
1. ALGORITHM 304 NORMAL CURVE INTEGRAL, I.D. Hill and S.A.
Joyce, Comm. ACM, Vol. 10, No. 6, pp. 374-5, June 1967
2. REMARK ON ALGORITHM 304 NORMAL CURVE INTEGRAL,
A.G. Adams, Comm. ACM, Vol. 12, No. 10, pp. 565-6, Oct. 1969
3. REMARK ON ALGORITHM 304 NORMAL CURVE INTEGRAL, B.
Holmgren, Comm. ACM, Vol. 13, No. 10, Oct. 1970
4. Tables of the F- and related distributions with algorithms, K.V. Mardia
and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5
391
cdfn2 25. COMMAND REFERENCE
Purpose
Computes interval of Normal cumulative distribution function.
Format
y = cdfn2(x,dx);
Input
x MN matrix, abscissae.
dx KL matrix, ExE conformable to x, intervals.
Output
y max(M,K) by max(N,L) matrix, the integral from x to x+dx of the
Normal distribution, i.e., Pr(x X x +dx).
Remarks
The relative error is:
[x[ 1 and dx 1 1e 14
1 < [x[ < 37 and [dx[ < 1/[x[ 1e 13
min(x, x +dx) > 37 and y > 1e 300 1e 11 or better
A relative error of 1e 14 implies that the answer is accurate to better than 1 in
the 14th digit.
Example
print cdfn2(1,0.5);
9.1848052662599017e-02
print cdfn2(20,0.5);
2.7535164718736454e-89
print cdfn2(20,1e-2);
5.0038115018684521e-90
print cdfn2(-5,2);
1.3496113800582164e-03
print cdfn2(-5,0.15);
3.3065580013000255e-07
392
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdfn2
See also
lncdfn2
Source
lncdfn.src
393
cdftc 25. COMMAND REFERENCE
Purpose
Computes the complement of the cdf of the Students t distribution.
Format
y = cdftc(x,n);
Input
x NK matrix.
n LM matrix, EE conformable with x.
Output
y max(N,L) by max(K,M) matrix.
Remarks
y is the integral from x to of the t distribution with n degrees of freedom.
Allowable ranges for the arguments are:
< x < +
n > 0
A 1 is returned for those elements with invalid inputs.
This equals 1 F(x, n), where F is the t cdf with n degrees of freedom. Thus, to get
the t cdf, subtract cdftc(x,n) from 1. The complement of the cdf is computed because
this is what is most commonly needed in statistical applications, and because it can be
computed with fewer problems of roundo error.
Example
x = { .1, .2, .3, .4 };
n = 0.5;
y = cdftc(x,n);
y =
0.473165
0.447100
0.422428
0.399555
394
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdftc
See also
cdfbeta, cdfchic, cdc, cdfn, cdfnc, gamma
Technical Notes
For results greater than 0.5e30, the absolute error is approx. 1e14 and the relative
error is approx. 1e12. If you multiply the relative error by the result, then take the
minimum of that and the absolute error, you have the maximum actual error for any
result. Thus, the actual error is approx. 1e14 for results greater than 0.01. For
results less than 0.01, the actual error will be less. For example, for a result of 0.5e30,
the actual error is only 0.5e42.
References:
1. Reference Table: Students t-Distribution Quantiles to 20D, G.W. Hill,
Division of Mathematical Statistics Technical Paper No. 35,
Commonwealth Scientic and Industrial Research Organization, Australia,
1972
2. ALGORITHM 395 STUDENTS t -DISTRIBUTION, G.W. Hill, Comm.
ACM. Vol. 13, No. 10, Oct. 1970
3. Handbook of Mathematical Functions, Eds. M. Abramowitz and I. A.
Stegun, Dover, New York, 7th Ed, 1970, ISBN 0-486-61272-4
395
cdftnc 25. COMMAND REFERENCE
Purpose
The integral under noncentral Students t distribution, from to x. It can return a
vector of values, but the degrees of freedom and noncentrality parameter must be the
same for all values of x.
Format
y = cdftnc(x,v,d);
Input
x N1 vector, values of upper limits of integrals.
v scalar, degrees of freedom, v > 0.
d scalar, noncentrality parameter.
This is the square root of the noncentrality parameter that sometimes goes
under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,
1959, app. IV.
Output
y N1 vector, integrals from to x of noncentral t .
Technical Notes
Relation to cdftc:
cdftc(x,v) = 1 - cdftnc(x,v,0);
The formula used is based on the formula in SUGI Supplemental Library
Users Guide, 1983, SAS Institute, page 232 (which is attributed to
Johnson and Kotz, 1970).
The formula used here is a modication of that formula. It has been tested
against direct numerical integration, and against simulation experiments in
which noncentral t random variates were generated and the cdf found
directly.
We invite any feedback from those using this function.
Source
cdfnonc.src
Globals
None
See also
cdnc, cdfchinc
396
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdftvn
Purpose
Computes the cumulative distribution function of the standardized trivariate Normal
density (lower tail).
Format
c = cdftvn(x1,x2,x3,rho12,rho23,rho31);
Input
x1 N1 vector of upper limits of integration for variable 1.
x2 N1 vector of upper limits of integration for variable 2.
x3 N1 vector of upper limits of integration for variable 3.
rho12 scalar or N1 vector of correlation coecients between the two variables
x1 and x2.
rho23 scalar or N1 vector of correlation coecients between the two variables
x2 and x3.
rho31 scalar or N1 vector of correlation coecients between the two variables
x1 and x3.
Output
c N1 vector containing the result of the triple integral from to x1,
to x2, and to x3 of the standardized trivariate Normal density:
f(x1,x2,x3,rho12,rho23,rho31)
Remarks
Allowable ranges for the arguments are:
< x1 < +
< x2 < +
< x3 < +
1 < rho12 < 1
1 < rho23 < 1
1 < rho31 < 1
397
cdftvn 25. COMMAND REFERENCE
In addition, rho12, rho23 and rho31 must come from a legitimate positive denite
matrix. A -1 is returned for those rows with invalid inputs.
A separate integral is computed for each row of the inputs.
The rst 3 arguments (x1,x2,x3) must be the same length, N. The second 3 arguments
(rho12,rho23,rho31) must also be the same length, and this length must be N or 1. If
it is 1, then these values will be expanded to apply to all values of x1,x2,x3. All inputs
must be column vectors.
To nd the integral under a general trivariate density, with x1, x2, and x3 having
nonzero means and any positive standard deviations, transform by subtracting the
mean and dividing by the standard deviation. For example:
x1 = ( x1 - meanc(x1) ) / stdc(x1);
See also
cdfn, cdfbvn
Technical Notes
The absolute error for cdftvn is approximately 2.5e8 for the entire range of
arguments.
References:
1. A Table for Computing Trivariate Normal Probabilities, G.P. Steck,
Ann. Math. Statist., Vol. 29, pp. 780-800
2. Computation of Bi- and Tri-variate Normal Integral, D.J. Daley, Appl.
Statist., Vol. 23, No. 3, pp. 435-438, 1974
398
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cdir
Purpose
Returns the current directory.
Format
y = cdir(s);
Input
s string, if the rst character is A-Z and the second character is a colon :
then that drive will be used. If not, the current default drive will be used.
Output
y string containing the drive and full path name of the current directory on
the specied drive.
Remarks
If the current directory is the root directory, the returned string will end with a
backslash, otherwise it will not.
A null string or scalar zero can be passed in as an argument to obtain the current drive
and path name.
Example
x = cdir(0);
y = cdir("d:");
print x;
print y;
C:\GAUSS
D:\
See also
les
399
ceil 25. COMMAND REFERENCE
Purpose
Round up toward +.
Format
y = ceil(x);
Input
x NK matrix.
Output
y NK matrix.
Remarks
This rounds every element in the matrix x to an integer. The elements are rounded up
toward +.
Example
x = 100*rndn(2,2);
y = ceil(x);
x =
77.68 14.10
4.73 158.88
y =
78.00 14.00
5.00 158.00
See also
oor, trunc
400
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE ChangeDir
Purpose
Changes the working directory.
Format
d = ChangeDir(s);
Input
s string, directory to change to
Output
d string, new working directory, or null string if change failed
See also
chdir
401
chdir 25. COMMAND REFERENCE
Purpose
Changes working directory.
Format
chdir dirstr;
Input
dirstr literal or string, directory to change to
Remarks
This is for interactive use. Use ChangeDir in a program.
If the directory change fails, chdir prints an error message.
The working directory is listed in the status report on the Unix version.
402
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE chol
Purpose
Computes the Cholesky decomposition of a symmetric, positive denite matrix.
Format
y = chol(x);
Input
x NN matrix.
Output
y NN matrix containing the Cholesky decomposition of x.
Remarks
y is the square root matrix of x. That is, it is an upper triangular matrix such that x
= y

y.
chol does not check to see that the matrix is symmetric. chol will look only at the
upper half of the matrix including the principal diagonal.
If the matrix x is symmetric but not positive denite, either an error message or an
error code will be generated, depending on the lowest order bit of the trap ag:
trap 0 Print error message and terminate program.
trap 1 Return scalar error code 10.
See scalerr and trap for more details about error codes.
Example
x = moment(rndn(100,4),0);
y = chol(x);
ypy = yy;
x =
90.746566 6.467195 1.927489 15.696056
6.467195 87.806557 6.319043 2.435953
1.927489 6.319043 101.973276 4.355520
15.696056 2.435953 4.355520 99.042850
y =
9.526099 0.678892 0.202338 1.647690
0.000000 9.345890 0.661433 0.380334
0.000000 0.000000 10.074465 0.424211
0.000000 0.000000 0.000000 9.798130
ypy =
90.746566 6.467195 1.927489 15.696056
6.467195 87.806557 6.319043 2.435953
1.927489 6.319043 101.973276 4.355520
15.696056 2.435953 4.355520 99.042850
See also
crout, solpd
403
choldn 25. COMMAND REFERENCE
Purpose
Performs a Cholesky downdate of one or more rows on an upper triangular matrix.
Format
r = choldn(C,x);
Input
C KK upper triangular matrix.
x NK matrix, the rows to downdate C with.
Output
r KK upper triangular matrix, the downdated matrix.
Remarks
C should be a Cholesky factorization.
choldn(C,x) is equivalent to chol(C

C - x

x), but choldn is numerically much more


stable.
Warning: it is possible to render a Cholesky factorization non-positive denite with
choldn. You should keep an eye on the ratio of the largest diagonal element of r to the
smallestif it gets very large, r may no longer be positive denite. This ratio is a
rough estimate of the condition number of the matrix.
Example
let C[3,3] = 20.16210005 16.50544413 9.86676135
0 11.16601462 2.97761666
0 0 11.65496052;
let x[2,3] = 1.76644971 7.49445820 9.79114666
6.87691156 4.41961438 4.32476921;
r = choldn(C,x);
r =
18.87055964 15.32294435 8.04947012
0.00000000 9.30682813 2.12009339
0.00000000 0.00000000 7.62878355
See also
cholup
404
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cholsol
Purpose
Solves a system of linear equations given the Cholesky factorization of the system.
Format
x = cholsol(b,C);
Input
b NK matrix.
C NN matrix.
Output
x NK matrix.
Remarks
C is the Cholesky factorization of a linear system of equations A. x is the solution for
Ax = b. b can have more than one column. If so, the system is solved for each column,
i.e., A x[., i] = b[., i].
cholsol(eye(N),C) is equivalent to invpd(A). Thus, if you have the Cholesky
factorization of A, cholsol is the most ecient way to obtain the inverse of A.
Example
let b[3,1] = 0.03177513 0.41823100 1.70129375;
let C[3,3] = 1.73351215 1.53201723 1.78102499
0 1.09926365 0.63230050
0 0 0.67015361;
x = cholsol(b,C);
x =
1.94396905
1.52686768
3.21579513
A0 =
3.00506436 2.65577048 3.08742844
2.65577048 3.55545737 3.42362593
3.08742844 3.42362593 4.02095978
405
cholup 25. COMMAND REFERENCE
Purpose
Performs a Cholesky update of one or more rows on an upper triangular matrix.
Format
r = cholup(C,x);
Input
C KK upper triangular matrix.
x NK matrix, the rows to update C with.
Output
r KK upper triangular matrix, the updated matrix.
Remarks
C should be a Cholesky factorization.
cholup(C,x) is equivalent to chol(C

C + x

x), but cholup is numerically much more


stable.
Example
let C[3,3] = 18.87055964 15.32294435 8.04947012
0 9.30682813 -2.12009339
0 0 7.62878355;
let x[2,3] = 1.76644971 7.49445820 9.79114666
6.87691156 4.41961438 4.32476921;
r = cholup(C,x);
r =
20.16210005 16.50544413 9.86676135
0.00000000 11.16601462 2.97761666
0.00000000 0.00000000 11.65496052
See also
choldn
406
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE chrs
Purpose
Converts a matrix of ASCII values into a string containing the appropriate characters.
Format
y = chrs(x);
Input
x NK matrix.
Output
y string of length N*K containing the characters whose ASCII values are
equal to the values in the elements of x.
Remarks
This function is useful for imbedding control codes in strings and for creating variable
length strings when formatting printouts, reports, etc.
Example
n = 5;
print chrs(ones(n,1)*42);
*****
Since the ASCII value of the asterisk character is 42, the program above will print a
string of n asterisks.
y = chrs(67~65~84);
print y;
CAT
See also
vals, ftos, stof
407
clear 25. COMMAND REFERENCE
Purpose
Clears space in memory by setting matrices equal to scalar zero.
Format
clear x, y;
Remarks
clear x; is equivalent to x = 0;.
Matrix names are retained in the symbol table after they are cleared.
Matrices can be cleared even though they have not previously been dened. clear can
be used to initialize matrices to scalar 0.
Example
clear x;
See also
clearg, new, show, delete
408
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE clearg
Purpose
This command clears global symbols by setting them equal to scalar zero.
Format
clearg a,b,c;
Output
a,b,c scalar global matrices containing 0.
Remarks
clearg x; is equivalent to x = 0;, where x is understood to be a global symbol. clearg
can be used to initialize symbols not previously referenced. This command can be used
inside of procedures to clear global matrices. It will ignore any locals by the same name.
Example
x = 45;
clearg x;
x = 0.0000000
See also
clear, delete, new, show, local
409
close 25. COMMAND REFERENCE
Purpose
Close a GAUSS le.
Format
y = close(handle);
Input
handle scalar, the le handle given to the le when it was opened with the open,
create, or fopen command.
Output
y scalar, 0 if successful, -1 if unsuccessful.
Remarks
handle is the scalar le handle created when the le was opened. It will contain an
integer which can be used to refer to the le.
close will close the le specied by handle, and will return a 0 if successful and a -1 if
not successful. The handle itself is not aected by close unless the return value of close
is assigned to it.
If f1 is a le handle and it contains the value 7, then after:
call close(f1);
the le will be closed but f1 will still have the value 7. The best procedure is to do the
following:
f1 = close(f1);
This will set f1 to 0 upon a successful close.
It is important to set unused le handles to zero because both open and create check
the value that is in a le handle before they proceed with the process of opening a le.
During open or create, if the value that is in the le handle matches that of an already
open le, the process will be aborted and a File already open message will be given.
This gives you some protection against opening a second le with the same handle as a
currently open le. If this happened, you would no longer be able to access the rst le.
An advantage of the close function is that it returns a result which can be tested to see
if there were problems in closing a le. The most common reason for having a problem
410
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE close
in closing a le is that the disk on which the le is located is no longer in the disk
driveor the handle was invalid. In both of these cases, close will return a -1.
Files are not automatically closed when a program terminates. This allows users to run
a program that opens les, and then access the les from COMMAND mode after the
program has been run. Files are automatically closed when GAUSS exits to the
operating system or when a program is terminated with the end statement. stop will
terminate a program but not close les.
As a rule it is good practice to make end the last statement in a program, unless
further access to the open les is desired from COMMAND mode. You should close
les as soon as you are done writing to them to protect against data loss in the case of
abnormal termination of the program due to a power or equipment failure.
The danger in not closing les is that anything written to the les may be lost. The
disk directory will not reect changes in the size of a le until the le is closed and
system buers may not be ushed.
Example
open f1 = dat1 for append;
y = writer(f1,x);
f1 = close(f1);
See also
closeall
411
closeall 25. COMMAND REFERENCE
Purpose
Close all currently open GAUSS les.
Format
closeall;
closeall list of handles;
Remarks
list of handles is a comma-delimited list of le handles.
closeall with no specied list of handles will close all les. The le handles will not be
aected. The main advantage of using closeall is ease of use; the le handles do not
have to be specied, and one statement will close all les.
When a list of handles follows closeall, all les are closed and the le handles listed are
set to scalar 0. This is safer than closeall without a list of handles because the handles
are cleared.
It is important to set unused le handles to zero because both open and create check
the value that is in a le handle before they proceed with the process of opening a le.
During open or create, if the value that is in the le handle matches that of an already
open le, the process will be aborted and a File already open message will be given.
This gives you some protection against opening a second le with the same handle as a
currently open le. If this happened, you would no longer be able to access the rst le.
Files are not automatically closed when a program terminates. This allows users to run
a program that opens les, and then access the les from COMMAND mode after the
program has been run. Files are automatically closed when GAUSS exits to the
operating system or when a program is terminated with the end statement. stop will
terminate a program but not close les.
As a rule it is good practice to make end the last statement in a program, unless
further access to the open les is desired from COMMAND mode. You should close
les as soon as you are done writing to them to protect against data loss in the case of
abnormal termination of the program due to a power or equipment failure.
The danger in not closing les is that anything written to the les may be lost. The
disk directory will not reect changes in the size of a le until the le is closed and
system buers may not be ushed.
Example
open f1 = dat1 for read;
open f2 = dat1 for update;
x = readr(f1,rowsf(f1));
x = sqrt(x);
call writer(f2,x);
closeall f1,f2;
412
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE closeall
See also
close, open
413
cls 25. COMMAND REFERENCE
Purpose
Clear the screen.
Format
cls;
Portability
Unix, OS/2, Windows
cls clears the active window. For Text windows, this means the window buer is
cleared to the background color. For TTY windows, the current output line is panned
to the top of the window, eectively clearing the display. The output log is still intact.
To clear the output log of a TTY window, use WinClearTTYLog. For PQG windows,
the window is cleared to the background color, and the related graphics le is truncated
to zero length.
Remarks
This command will cause the screen to clear and will locate the cursor at the upper left
hand corner of the screen.
See also
locate
414
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE code
Purpose
Allows a new variable to be created (coded) with dierent values depending upon
which one of a set of logical expressions is true.
Format
y = code(e,v);
Input
e NK matrix of 1s and 0s. Each column of this matrix is created by a
logical expression using dot conditional and boolean operators. Each of
these expressions should return a column vector result. The columns are
horizontally concatenated to produce e. If more than one of these vectors
contains a 1 in any given row, the code function will terminate with an
error message.
v (K+1)x1 vector containing the values to be assigned to the new variable.
Output
y N1 vector containing the new values.
Remarks
If none of the K expressions is true, the new variable is assigned the default value,
which is given by the last element of v.
Example
let x1 = 0 /* column vector of original values */
5
10
15
20;
let v = 1 /* column vector of new values */
2
3; /* the last element of v is the "default" */
e1 = (0 .lt x1) .and (x1 .le 5); /* expression 1 */
e2 = (5 .lt x1) .and (x1 .le 25); /* expression 2 */
e = e1~e2; /* concatenate e1 & e2 to make a 1,0 mask
:: with one less column than the number
:: of new values in v.
*/
y = code(e,v);
415
code 25. COMMAND REFERENCE
x1[5, 1] =
0
5
10
15
20
(column vector of original values)
v[3, 1] = 1 2 3 (Note: v is a column vector)
e[5, 2] =
0 0
1 0
0 1
0 1
0 1
y[5, 1] =
3
1
2
2
2
For every row in e, if a 1 is in the rst column, the rst element of v is used. If a 1 is in
the second column, the second element of v is used, and so on. If there are only zeros in
the row, the last element of v is used. This is the default value.
If there is more than one 1 in any row of e, the function will terminate with an error
message.
Source
datatran.src
Globals
None
See also
recode, substute
416
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE color
Purpose
Set pixel, text, background color, or VGA palette color registers.
Format
y = color(cv)
Input
cv scalar, 21 or 31 vector of color values or N4 matrix of palette color
values. See Portability for platform specics.
If the input vector is smaller than 31 or the corresponding element in the
input vector is -1, the corresponding color will be left unchanged.
If the input is an N4 matrix, it will initialize the VGA palette with
user-dened RGB colors interpreted as follows:
[N,1] palette register index 0-255
[N,2] red value 0-63
[N,3] green value 0-63
[N,4] blue value 0-63
Output
y vector, or N4 matrix the same size as the input which contains the
original color values or palette values.
Portability
Dos
[1] pixel color
[2] text color
[3] ignored
Unix
color aects the active window. X supports foreground and background colors. The
color command makes no distinction between text and pixel colors; both aect the
foreground color of the active window. If both a pixel color and text color are specied,
417
color 25. COMMAND REFERENCE
the pixel color will be ignored, and the text color will be used to set the foreground
color. Thus:
[1] foreground
or
[1] ignored
[2] foreground
or
[1] ignored
[2] foreground
[3] background
OS/2, Windows
This function is not supported under OS/2 or Windows.
Remarks
This changes the screen colors for your programs output. The editor and COMMAND
mode will not be aected.
The color values 0-15 may be obtained through the help system by requesting help on
@PQG. You will have to page down several pages to the page listing the color values.
Under DOS, the VGA color palette registers may be set only if the display adapter has
been already been initialized to VGA graphics mode 19 (320200, 256 colors) with the
setvmode command. The registers will retain the new values until the adapter is reset
to text mode, which resets the palette to the default VGA colors.
This function is useful for obtaining 64 shades of a single color and/or mixing colors to
user-specication.
See also
graph, line, setvmode
418
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cols, colsf
Purpose
cols returns the number of columns in a matrix.
colsf returns the number of columns in a GAUSS data (.dat) le or GAUSS matrix
(.fmt) le.
Format
y = cols(x);
yf = colsf(fh);
Input
x any valid expression that returns a matrix.
fh le handle of an open le.
Output
y number of columns in x.
yf number of columns in the le that has the handle fh.
Remarks
If x is an empty matrix, rows(x) and cols(x) return 0.
For colsf, the le must be open.
Example
x = rndn(100,3);
y = cols(x);
y = 3.000000
create fp = myfile with x,10,4;
b = colsf(fp);
b = 10.000000
See also
rows, rowsf, show, lshow
419
comlog 25. COMMAND REFERENCE
Purpose
Controls logging of COMMAND mode commands to a disk le.
Format
comlog [[le=lename]] [[on[o[reset]] ;
Input
lename literal or ^string.
The le=lename subcommand selects the le to log COMMAND mode
statements to. This can be any legal le name.
If the name of the le is to be taken from a string variable, the name of the
string must be preceded by the ^ (caret) operator.
There is no default le name.
on, o, reset literal, mode command
on turns on command logging to the current log le. If the le already
exists, subsequent commands will be appended.
o closes the log le and turns o command logging.
reset similar to the on subcommand, except that it resets the log le by
deleting any previous commands.
Portability
This function is supported only under DOS.
Remarks
COMMAND mode statements are always logged into the le specied in the log le
conguration variable, regardless of the state of comlog.
The command comlog le=lename selects the le but does not turn on logging.
The command comlog o will turn o logging. The lename will remain the same. A
subsequent comlog on will cause logging to resume. A subsequent comlog reset will
cause the existing contents of the log le to be destroyed and a new le created.
The command comlog by itself will cause the name and status of the current log le to
be printed on the screen.
In COMMAND mode under DOS, F10 will load the current log le into the editor if
logging is on. If logging is o, the default log le listed in the log le conguration
variable will be loaded into the editor.
420
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE compile
Purpose
Compiles a source le to a compiled code le. See also Chapter 11.
Format
compile source fname;
Input
source literal or string, the name of the le to be compiled.
fname literal or string, optional, the name of the le to be created. If not given,
the le will have the same lename and path as source. It will have a .gcg
extension.
Remarks
The source le will be searched for in the src path if the full path is not specied and it
is not present in the current directory.
The source le is a regular DOS text le containing a GAUSS program. There can be
references to global symbols, Run-Time Library references, etc.
If there are library statements in source, they will be used during the compilation to
locate various procedures and symbols used in the program. Since all of these library
references are resolved at compile time, the library statements are not transferred to the
compiled le. The compiled le can be run without activating any libraries.
If you do not want extraneous stu saved in the compiled image, put a new at the top
of the source le or execute a new from COMMAND level before compiling.
The program saved in the compiled le can be run with the run command. If no
extension is given, the run command will look for a le with the correct extension for
the version of GAUSS. The src path will be used to locate the le if the full path name
is not given and it is not located on the current directory.
When the compiled le is run, all previous symbols and procedures are deleted before
the program is loaded. It is therefore unnecessary to execute a new before running a
compiled le.
If you want line number records in the compiled le you can put a #lineson statement
in the source le or turn line tracking on from the Options menu.
Dont try to include compiled les with #include.
Example
421
compile 25. COMMAND REFERENCE
compile qxy.e;
In this example, the src path would be searched for qxy.e, which would be compiled to
a le called qxy.gcg on the same subdirectory qxy.e was found.
compile qxy.e xy;
In this example, the src path would be searched for qxy.e which would be compiled to
a le called xy.gcg on the current subdirectory.
See also
run, use, saveall
422
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE complex
Purpose
Converts a pair of real matrices to a complex matrix.
Format
z = complex(xr,xi );
Input
xr NK real matrix, the real elements of z.
xi NK real matrix or scalar, the imaginary elements of z.
Output
z NK complex matrix.
Example
x = { 4 6,
9 8 };
y = { 3 5,
1 7 };
t = complex(x,y);
t =
4.0000000 + 3.0000000i 6.0000000 + 5.0000000i
9.0000000 + 1.0000000i 8.0000000 + 7.0000000i
See also
imag, real
423
con 25. COMMAND REFERENCE
Purpose
Requests input from the keyboard (console), and returns it in a matrix.
Format
x = con(r,c);
Input
r scalar, row dimension of matrix.
c scalar, column dimension of matrix.
Output
x RC matrix.
Portability
Unix, OS/2, Windows
con gets input from the active window. If you are working in terminal mode GAUSS
will not see any input until you press Enter, so follow each entry with an Enter.
Cursor keys are not supported in terminal mode.
Remarks
r and c may be any scalar-valued expressions. Nonintegers will be truncated to an
integer.
A con function in a program will cause a question mark to appear on the screen. You
can then type in numbers, and they will be placed into a matrix. GAUSS will wait
until r c numbers have been typed in (e.g., if r = 3 and c = 2, then GAUSS will wait
for 6 numbers). All GAUSS cares about is getting enough numbersit knows how to
arrange them in a matrix from the dimensions specied. The numbers can be separated
by spaces, commas or carriage returns.
When r c numbers have been entered, the program will resume with the next
command.
A matrix editor is invoked when the con function is called. This editor allows you to
move around the matrix you are entering and make changes. See editm for an
additional discussion.
424
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE con
The matrix editor allows you to use the cursor keys to move along rows or up and down
columns in the matrix. When you come to the end of a row or column, movement is
left and up, or right and down. If, for instance, you are moving left to right along a row
using the right cursor key, you will move down to the beginning of the next row when
you come to the end of the row you are in. GAUSS will beep at you if you try to move
outside the matrix.
The matrix editor will show you what is in each element, and will prompt you for a new
number. If you do not want to change anything, you can move to a dierent element by
hitting the appropriate cursor key. If you start to type a number and then hit a cursor
key, the number will not be saved. The BACKSPACE key will delete characters to the
left of the cursor.
If you type in a space, comma or carriage return before you type a number, nothing
will happen. GAUSS will wait until you type a number or use a cursor key to move to
a new element.
Numbers can be entered in scientic notation. The syntax is: dE+n or dE-n, where d
is a number and n is an integer (denoting the power of 10). Thus, 1E+10, 1.1e-4,
1100E+1 are all legal.
Complex numbers can be entered by joining the real and imaginary parts with a sign
(+ or -); there can be no spaces between the numbers and the sign. Numbers with no
real part can be entered by appending an i to the number. For example, 1.2+23,
8.56i, 3-2.1i, -4.2e+6i and 1.2e-4-4.5e+3i are all legal.
If using DOS, and e can be entered with Alt-P and Alt-E.
A con function can appear anywhere in an expression that any other function can
appear.
Example
n = con(1,1);
print rndn(n,n);
? 2
0.148030 0.861562
1.791516 0.663392
In this example, the con function is used to obtain the size of a square matrix of
Normal random variables which is to be printed out.
See also
cons, editm, let, load, medit
425
cond 25. COMMAND REFERENCE
Purpose
This procedure will compute the condition number of a matrix using the singular value
decomposition.
Format
c = cond(x);
Input
x NK matrix.
Output
c scalar, an estimate of the condition number of x. This equals the ratio of
the largest singular value to the smallest. If the smallest singular value is
zero or not all of the singular values can be computed, the return value is
10
300
.
Example
x = { 4 2 6,
8 5 7,
3 8 9 };
y = cond(x);
y = 9.8436943
Source
svd.src
Globals
None
426
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE conj
Purpose
Returns the complex conjugate of a matrix.
Format
y = conj(x);
Input
x NK matrix.
Output
y NK matrix, the complex conjugate of x.
Remarks
Compare conj with the transpose (

) operator.
Example
x = { 1+9i 2,
4+4i 5i,
7i 8-2i };
y = conj(x);
x =
1.0000000 + 9.0000000i 2.0000000
4.0000000 + 4.0000000i 0.0000000 +5.0000000i
0.0000000 + 7.0000000i 8.0000000 2.0000000i
y =
1.0000000 9.0000000i 2.0000000
4.0000000 4.0000000i 0.0000000 5.0000000i
0.0000000 7.0000000i 8.0000000 +2.0000000i
427
cons 25. COMMAND REFERENCE
Purpose
Retrieves a character string from the keyboard.
Format
x = cons;
Output
The characters entered from the keyboard. The output will be of type string.
Portability
Unix
cons gets input from the active window.
Remarks
x is assigned the value of a character string typed in at the keyboard. The program will
pause to accept keyboard input. The maximum length of the string that can be entered
is 254 characters. The program will resume execution when the Enter key is pressed.
The standard DOS editing keys will be in eect.
Example
x = cons;
At the cursor enter:
probability
x = probability
See also
con
428
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE continue
Purpose
Jumps to the top of a do or for loop.
Format
continue;
Example
x = rndn(4,4);
r = 0;
do while r < rows(x);
r = r + 1;
c = 0;
do while c < cols(x); /* continue jumps here */
c = c + 1;
if c == r;
continue;
endif;
x[r,c] = 0;
endo;
endo;
x =
1.032195 0.000000 0.000000 0.000000
0.000000 1.033763 0.000000 0.000000
0.000000 0.000000 0.061205 0.000000
0.000000 0.000000 0.000000 0.225936
Remarks
This command works just like in C.
429
conv 25. COMMAND REFERENCE
Purpose
Computes the convolution of two vectors.
Format
c = conv(b,x,f ,l );
Input
b N1 vector.
x L1 vector.
f scalar, the rst convolution to compute.
l scalar, the last convolution to compute.
Output
c Q1 result, where Q = (l f + 1) .
If f is 0, the rst to the l th convolutions are computed. If l is 0, the f th
to the last convolutions are computed. If f and l are both zero, all the
convolutions are computed.
Remarks
If x and b are vectors of polynomial coecients, this is the same as multiplying the two
polynomials.
Example
x = { 1,2,3,4 };
y = { 5,6,7,8 };
z1 = conv(x,y,0,0);
z2 = conv(x,y,2,5);
z1 =
5
16
34
60
61
52
32
z2 =
16
34
60
61
See also
polymult
430
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE coreleft
Purpose
Returns the amount, in bytes, of free workspace memory.
Format
y = coreleft;
Output
y scalar, number of bytes free.
Remarks
The amount of free memory is dynamic and can change rapidly as expressions and
procedures are being executed. coreleft returns the amount of workspace memory free
at the time it is called. Workspace memory is used for storing matrices, strings,
procedures, and for manipulating matrices and strings.
This function can be used to write programs that automatically adjust their use of
memory so they do not crash with the Insucient memory error if they are used on
machines with less free memory than the one used for development or if the size of the
data used becomes larger. A common use is to adjust the number of rows that are read
per iteration of a read loop in programs that access data from a disk.
Example
open fp = myfile;
k = colsf(fp); /* columns in file */
fac = 4;
/* check amount of memory available */
nr = coreleft/(fac*k*8);
In this example, nr, the number of rows to read, is computed by taking the number of
bytes free (coreleft) divided by fac*k*8. fac is a guesstimate of the number of copies of
the data read each iteration that the algorithm we are using will require plus a little
slop. k*8 is the number of columns times the number of bytes per element.
See also
dfree, new
431
corrm, corrvc, corrx 25. COMMAND REFERENCE
Purpose
Computes a correlation matrix.
Format
cx = corrm(m);
cx = corrvc(vc);
cx = corrx(x);
Input
m KK moment (x

x) matrix. A constant term MUST have been the rst


variable when the moment matrix was computed.
vc KK variance-covariance matrix (of data or parameters).
x NK matrix of data.
Output
cx PP correlation matrix. For corrm, P = K 1. For corrvc and corrx,
P = K.
Source
corr.src
Globals
None
See also
momentd
432
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cos
Purpose
Returns the cosine of its argument.
Format
y = cos(x);
Input
x NK matrix.
Output
y NK matrix.
Remarks
For real matrices, x should contain angles measured in radians.
To convert degrees to radians, multiply the degrees by

180
.
Example
x = { 0, .5, 1, 1.5 };
y = cos(x);
y =
1.00000000
0.87758256
0.54030231
0.07073720
See also
atan, atan2, pi
433
cosh 25. COMMAND REFERENCE
Purpose
Computes the hyperbolic cosine.
Format
y = cosh(x);
Input
x NK matrix.
Output
y NK matrix containing the hyperbolic cosines of the elements of x.
Example
x = { -0.5, -0.25, 0, 0.25, 0.5, 1 };
x = x * pi;
y = cosh(x);
x =
1.570796
0.785398
0.000000
0.785398
1.570796
3.141593
y =
2.509178
1.324609
1.000000
1.324609
2.509178
11.591953
Source
trig.src
Globals
None
434
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE counts
Purpose
Count the numbers of elements of a vector that fall into specied ranges.
Format
c = counts(x,v);
Input
x N1 vector containing the numbers to be counted.
v P1 vector containing breakpoints specifying the ranges within which
counts are to be made. The vector v MUST be sorted in ascending order.
Output
c P1 vector, the counts of the elements of x that fall into the regions:
x v[1],
v[1] < x v[2],
.
.
.
v[p 1] < x v[p].
Remarks
If the maximum value of x is greater than the last element (the maximum value) of v,
the sum of the elements of the result, c, will be less than N, the total number of
elements in x.
If
x =
1
2
3
4
5
6
7
8
9
and v =
4
5
8
then
c =
4
1
3
435
counts 25. COMMAND REFERENCE
The rst category can be a missing value if you need to count missings directly. Also
+ or are allowed as breakpoints. The missing value must be the rst breakpoint
if it is included as a breakpoint and innities must be in the proper location depending
on their sign. must be in the [2,1] element of the breakpoint vector if there is a
missing value as a category as well, otherwise it has to be in the [1,1] element. If + is
included, it must be the last element of the breakpoint vector.
Example
x = { 1, 3, 2,
4, 1, 3 };
v = { 0, 1, 2, 3, 4 };
c = counts(x,v);
c =
0.0000000
2.0000000
1.0000000
2.0000000
1.0000000
436
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE countwts
Purpose
Returns a weighted count of the numbers of elements of a vector that fall into specied
ranges.
Format
c = countwts(x,v,w);
Input
x N1 vector, the numbers to be counted.
v P1 vector, the breakpoints specifying the ranges within which counts are
to be made. This MUST be sorted in ascending order (lowest to highest).
w N1 vector, containing weights.
Output
c P1 vector containing the weighted counts of the elements of x that fall
into the regions:
x v[1]
v[1] < x v[2]
. . .
v[p 1] < x v[p]
That is, when x[i] falls into region j , the weight w[i] is added to the j
th
counter.
Remarks
If any elements of x are greater than the last element of v, they will not be counted.
Missing values are not counted unless there is a missing in v. A missing value in v
MUST be the rst element in v.
Example
x = { 1, 3, 2, 4, 1, 3 };
w = { .25, 1, .333, .1, .25, 1 };
v = { 0, 1, 2, 3, 4 };
c = countwts(x,v,w);
c =
0.000000
0.500000
0.333000
2.00000
0.100000
437
create 25. COMMAND REFERENCE
Purpose
Creates and opens a GAUSS data set for subsequent writing.
Format
create [[vag]] [[complex]] fh = lename with vnames,col ,dtyp,vtyp;
create [[vag]] [[complex]] fh = lename using comle;
Input
vag version ag.
-v89 supported on DOS, OS/2, Windows NT
-v92 supported on Unix
-v96 supported on all platforms
See the File I/O chapter in Volume I of the manual for details on the
various versions. The default format can be specied in gauss.cfg by
setting the dat fmt version conguration variable. If dat fmt version
is not set, the default is v96.
lename literal or ^string
lename is the name to be given to the le on the disk. The name can
include a path if the directory to be used is not the current directory. This
le will automatically be given the extension .dat. If an extension is
specied, the .dat will be overridden. If the name of the le is to be taken
from a string variable, the name of the string must be preceded by the ^
(caret) operator.
create... with...
vnames literal or ^string or ^character matrix.
vnames controls the names to be given to the columns of the data le. If
the names are to be taken from a string or character matrix, the ^ (caret)
operator must be placed before the name of the string or character matrix.
The number of columns parameter, col , also has an eect on the way the
names will be created. See below and see the examples for details on the
ways names are assigned to a data le.
col scalar expression.
col is a scalar expression containing the number of columns in the data le.
If col is 0, the number of columns will be controlled by the contents of
vnames. If col is positive, the le will contain col columns and the names
to be given each column will be created as necessary depending on the
vnames parameter. See the examples.
438
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE create
dtyp scalar expression.
dtyp is the precision used to store the data. This is a scalar expression
containing 2, 4, or 8, which is the number of bytes per element.
2 signed integer
4 single precision
8 double precision
data type digits range
integer 4 32768 X 32767
single 6-7 8.43x10
37
[X[ 3.37x10
+38
double 15-16 4.19x10
307
[X[ 1.67x10
+308
If the integer type is specied, numbers will be rounded to the nearest
integer as they are written to the data set. If the data to be written to the
le contains character data, the precision must be 8 or the character
information will be lost.
vtyp matrix, types of variables.
The types of the variables in the data set. If rows(vtyp)*cols(vtyp) < col
only the rst element is used. Otherwise nonzero elements indicate a
numeric variable and zero elements indicate character variables. vtyp is
ignored for v89 les.
create... using...
comle literal or ^string.
comle is the name of a command le that contains the information
needed to create the le. The default extension for the command le is
.gcf, which can be overridden.
There are three possible commands in this le:
NUMVAR n str;
OUTVAR varlist;
OUTTYP dtyp;
NUMVAR and OUTVAR are alternate ways of specifying the number and
names of the variables in the data set to be created.
When NUMVAR is used, n is a constant which species the number of
variables (columns) in the data le and str is a string literal specifying the
prex to be given to all the variables. Thus:
numvar 10 xx;
439
create 25. COMMAND REFERENCE
says that there are 10 variables and that they are to be named xx01
through xx10. The numeric part of the names will be padded on the left
with zeros as necessary so the names will sort correctly:
xx1, . . . xx9 19 names
xx01, . . . xx10 1099 names
xx001, . . . xx100 100999 names
xx0001, . . . xx1000 10008100 names
If str is omitted, the variable prex will be X.
When OUTVAR is used, varlist is a list of variable names, separated by
spaces or commas. For instance:
outvar x1, x2, zed;
species that there are to be 3 variables per row of the data set, and that
they are to be named X1, X2, ZED, in that order.
OUTTYP species the precision. It can be a constant: 2, 4, or 8, or it can
be a literal: I, F, or D. See dtyp above in the discussion of create... with...
for an explanation of the available data types.
The OUTTYP statement does not have to be included. If it is not, then
all data will be stored in 4 bytes as single precision oating point numbers.
Output
fh scalar.
fh is the le handle which will be used by most commands to refer to the
le within GAUSS. This le handle is actually a scalar containing an
integer value that uniquely identies each le. This value is assigned by
GAUSS when the create (or open) command is executed.
Remarks
If the complex ag is included, the new data set will be initialized to store complex
number data. Complex data is stored a row at a time, with the real and imaginary
halves interleaved, element by element.
Example
let vnames = age sex educat wage occ;
create f1 = simdat with ^vnames,0,8;
obs = 0; nr = 1000;
do while obs < 10000;
data = rndn(nr,colsf(f1));
if writer(f1,data) /= nr;
440
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE create
print "Disk Full"; end;
endif;
obs = obs+nr;
endo;
closeall f1;
The example above uses create... with... to create a double precision data le called
simdat.dat on the default drive with 5 columns. The writer command is used to write
10000 rows of Normal random numbers into the le. The variables (columns) will be
named: AGE, SEX, EDUCAT, WAGE, OCC.
Here are some examples of the variable names that will result when using a character
vector of names in the argument to the create function.
vnames = { AGE PAY SEX JOB };
typ = { 1, 1, 0, 0 };
create fp = mydata with ^vnames,0,2,typ;
The names in the above program will be: AGE PAY SEX JOB
AGE and PAY are numeric variables, SEX and JOB are character variables.
create fp = mydata with ^vnames,3,2;"
The names will be: AGE PAY SEX
create fp = mydata with ^vnames,8,2;
The names will now be: AGE PAY SEX JOB1 JOB2 JOB3 JOB4 JOB5
If a literal is used for the vnames parameter, then the number of columns should be
explicitly given in the col parameter and the names will be created as follows:
create fp = mydata with var,4,2;
Giving the names: VAR1 VAR2 VAR3 VAR4
For the next example we will assume a command le called comd.gcf containing the
following lines has been created using a text editor.
outvar age, pay, sex;
outtyp i;
Then the following program could be used to write 100 rows of random integers into a
le called smpl.dat in the subdirectory called /gauss/data:
441
create 25. COMMAND REFERENCE
filename = "/gauss/data/smpl";
create fh = ^filename using comd;
x = rndn(100,3)*10;
if writer(fh,x) /= rows(x);
print "Disk Full"; end;
endif;
closeall fh;
For platforms using the backslash as a path separator, remember that two backslashes
(\\) are required to enter one backslash inside of double quotes. This is because a
backslash is the escape character used to embed special characters in strings.
See also
open, readr, writer, eof, close, output, iscplxf
442
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE crossprd
Purpose
Computes the cross-products (vector products) of sets of 31 vectors.
Format
z = crossprd(x,y);
Input
x 3K matrix, each column is treated as a 31 vector.
y 3K matrix, each column is treated as a 31 vector.
Output
z 3K matrix, each column is the cross-product (sometimes called vector
product) of the corresponding columns of x and y.
Remarks
The cross-product vector z is orthogonal to both x and y. sumc(x.*z) and sumc(y.*z)
will be K1 vectors all of whose elements are 0 (except for rounding error).
Example
x = { 10 4,
11 13,
14 13 };
y = { 3 11,
5 12,
7 9 };
z = crossprd(x,y);
z =
7.0000000 39.000000
28.000000 107.00000
17.000000 95.000000
Source
crossprd.src
Globals
None
443
crout 25. COMMAND REFERENCE
Purpose
Computes the Crout decomposition of a square matrix without row pivoting, such that:
X = LU.
Format
y = crout(x);
Input
x NN square nonsingular matrix.
Output
y NN matrix containing the lower (L) and upper (U) matrices of the Crout
decomposition of x. The main diagonal of y is the main diagonal of the
lower matrix L. The upper matrix has an implicit main diagonal of ones.
Use lowmat and upmat1 to extract the L and U matrices from y.
Remarks
Since it does not do row pivoting, it is intended primarily for teaching purposes. See
croutp for a decomposition with pivoting.
Example
X = { 1 2 -1,
2 3 -2,
1 -2 1 };
y = crout(x);
L = lowmat(y);
U = upmat1(y);
y =
1 2 1
2 1 0
1 4 2
L =
1 0 0
2 1 0
1 4 2
U =
1 2 1
0 1 0
0 0 1
See also
croutp, chol, lowmat, lowmat1, lu, upmat, upmat1
444
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE croutp
Purpose
Computes the Crout decomposition of a square matrix with partial (row) pivoting.
Format
y = croutp(x);
Input
x NN square nonsingular matrix.
Output
y (N+1)xN matrix containing the lower (L) and upper (U) matrices of the
Crout decomposition of a permuted x. The N+1 row of the matrix y gives
the row order of the y matrix. The matrix must be reordered prior to
extracting the L and U matrices. Use lowmat and upmat1 to extract the
L and U matrices from the reordered y matrix.
Example
This example illustrates a procedure for extracting L and U of the permuted x matrix.
It continues by sorting the result of LU to compare with the original matrix x.
X = { 1 2 -1,
2 3 -2,
1 -2 1 };
y = croutp(x);
r = rows(y); /* the number of rows of y */
indx = y[r,.]; /* get the index vector */
z = y[indx,.]; /* z is indexed RxR matrix y */
L = lowmat(z); /* obtain L and U of permuted matrix X */
U = upmat1(z);
q = sortc(indx~(L*U),1); /* sort L*U against index */
x2 = q[.,2:cols(q)]; /* remove index column */
X =
1 2 1
2 3 2
1 2 1
y =
1 0.5 0.2857
2 1.5 1
1 3.5 0.5714
2 3 1
445
croutp 25. COMMAND REFERENCE
r = 4
indx =
2
3
1
z =
2 1.5 1
1 3.5 0.5714
1 0.5 0.2857
L =
2 0 0
1 3.5 0
1 0.5 0.2857
U =
1 1.5 1
0 1 0.5714
0 0 1
q =
1 1 2 1
2 2 3 2
3 1 2 1
x2 =
1 2 1
2 3 2
1 2 1
See also
crout, chol, lowmat, lowmat1, lu, upmat, upmat1
446
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE csrcol, csrlin
Purpose
Returns the position of the cursor.
Format
y = csrcol;
y = csrlin;
Portability
Unix
csrcol returns the cursor column for the active window. For Text windows, this value is
the cursor column with respect to the text buer. For TTY windows, this value is the
cursor column with respect to the current output line, i.e., it will be the same whether
the text is wrapped or not. For PQG windows, this value is meaningless.
csrlin returns the cursor line for the active window. For Text windows, this value is the
cursor row with respect to the text buer. For TTY windows, this value is the current
output line number (i.e., the number of lines logged + 1). For PQG windows, this value
is meaningless.
OS/2, Windows
csrcol returns the cursor column with respect to the current output line, i.e., it will
return the same value whether the text is wrapped or not. csrlin returns the cursor line
with respect to the top line in the window.
Remarks
y will contain the current column or row position of the cursor on the screen. The
upper left corner is (1,1). Under DOS, columns are usually numbered 180, rows are
usually numbered 125. setvmode will return the current screen dimensions.
csrcol returns the column position of the cursor. csrlin returns the row position.
The locate statement allows the cursor to be positioned at a specic row and column.
Example
r = csrlin;
c = csrcol;
cls;
locate r,c;
In this example the screen is cleared without aecting the cursor position.
See also
cls, locate, lpos, setvmode
447
csrtype 25. COMMAND REFERENCE
Purpose
To set the cursor shape.
Format
old = csrtype(mode);
Portability
Unix
This function is not supported in terminal mode.
OS/2, Windows
This function is not supported under OS/2 or Windows.
Input
mode scalar, cursor type to set.
DOS
0 cursor o
1 normal cursor
2 large cursor
Unix
0 cursor o
1 normal cursor
2 large cursor
3 triangular cursor
Output
old scalar, original cursor type.
Remarks
Under DOS, this function will set the same shape as GAUSS is already using for its
three modes. See the Conguration chapter in the DOS supplement for details.
Example
x = csrtype(2);
See also
csrcol, csrlin
448
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE cumprodc
Purpose
Computes the cumulative products of the columns of a matrix.
Format
y = cumprodc(x);
Input
x NK matrix.
Output
y NK matrix containing the cumulative products of the columns of x.
Remarks
This is based on the recursive series recsercp. recsercp could be called directly as
follows:
recsercp(x,zeros(1,cols(x)))
to accomplish the same thing.
Example
x = { 1 -3,
2 2,
3 -1 };
y = cumprodc(x);
y =
1.00 3.00
2.00 6.00
6.00 6.00
Source
cumprodc.src
Globals
None
See also
cumsumc, recsercp, recserar
449
cumsumc 25. COMMAND REFERENCE
Purpose
Computes the cumulative sums of the columns of a matrix.
Format
y = cumsumc(x);
Input
x NK matrix.
Output
y NK matrix containing the cumulative sums of the columns of x.
Remarks
This is based on the recursive series function recserar. recserar could be called directly
as follows:
recserar(x, x[1,.] , ones(1,cols(x)))
to accomplish the same thing.
Example
x = { 1 -3,
2 2,
3 -1 };
y = cumsumc(x);
y =
1 3
3 1
6 2
Source
cumsumc.src
Globals
None
See also
cumprodc, recsercp, recserar
450
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

C
25. COMMAND REFERENCE curve
Purpose
Computes a one-dimensional smoothing curve.
Format
{ u,v } = curve(x,y,d,s,sigma,G);
Input
x K1 vector, x-abscissae (x-axis values).
y K1 vector, y-ordinates (y-axis values).
d K1 vector or scalar, observation weights.
s scalar, smoothing parameter. If s = 0, curve performs an interpolation. If
d contains standard deviation estimates, a reasonable value for s is K.
sigma scalar, tension factor.
G scalar, grid size factor.
Output
u K*G1 vector, x-abscissae, regularly spaced.
v K*G1 vector, y-ordinates, regularly spaced.
Remarks
sigma contains the tension factor. This value indicates the curviness desired. If sigma
is nearly zero (e. g. .001), the resulting curve is approximately the tensor product of
cubic curves. If sigma is large, (e. g. 50.0) the resulting curve is approximately
bi-linear. If sigma equals zero, tensor products of cubic curves result. A standard value
for sigma is approximately 1.
G is the grid size factor. It determines the neness of the output grid. For G = 1, the
input and output vectors will be the same size. For G = 2, the output grid is twice as
ne as the input grid, i.e., u and v will have twice as many rows as x and y.
Source
spline.src
451
cvtos 25. COMMAND REFERENCE
Purpose
Converts a character vector to a string.
Format
s = cvtos(v);
Input
v N1 character vector, to be converted to a string.
Output
s string, contains the contents of v.
Remarks
cvtos in eect appends the elements of v together into a single string.
cvtos was written to operate in conjunction with stocv. If you pass it a character
vector that does not conform to the output of stocv, you may get unexpected results.
For example, cvtos DOES NOT look for 0 terminating bytes in the elements of v; it
assumes every element except the last is 8 characters long. If this is not true, there will
be 0s in the middle of s.
If the last element of v does not have a terminating 0 byte, cvtos supplies one for s.
Example
let v = { "Now is t" "he time " "for all " "good men" };
s = cvtos(v);
s = Now is the time for all good men
See also
stocv, vget, vlist, vput, vread
452
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE datalist
Purpose
List selected variables from a data set.
Format
datalist dataset [[var1 [[var2...]]]];
Input
dataset literal, name of the dataset.
var# literal, the names of the variables to list.
range global scalar, the range of rows to list. The default is all rows.
miss global scalar, controls handling of missing values.
0 display rows with missing values.
1 do not display rows with missing values.
The default is 0.
prec global scalar, the number of digits to the right of the decimal point to
display. The default is 3.
Remarks
The variables are listed in an interactive mode. As many rows and columns as will t
on the screen are displayed. You can use the cursor keys to pan and scroll around in
the listing.
Example
datalist freq age sex pay;
This command will display the variables age, sex, and pay from the data set freq.dat.
Source
datalist.src
453
date 25. COMMAND REFERENCE
Purpose
Returns the current date in a 4-element column vector, in the order: year, month, day,
and hundredths of a second since midnight.
Format
y = date;
Remarks
The hundredths of a second since midnight can be accessed using hsec.
Example
print date;
1998.0000
6.0000000
15.000000
4011252.7
See also
time, timestr, ethsec, hsec, etstr
454
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE datestr
Purpose
Returns a date in a string.
Format
str = datestr(d);
Input
d 41 vector, like the date function returns. If this is 0, the date function
will be called for the current system date.
Output
str 8 character string containing current date in the form: mo/dy/yr
Example
d = { 1998, 6, 15, 0 };
y = datestr(d);
print y;
6/15/98
Source
time.src
Globals
None
See also
date, datestring, datestrymd, time, timestr, ethsec
455
datestring 25. COMMAND REFERENCE
Purpose
Returns a date in a year-2000-compliant string.
Format
str = datestring(d);
Input
d 41 vector, like the date function returns. If this is 0, the date function
will be called for the current system date.
Output
str 10 character string containing current date in the form: mm/dd/yyyy
Example
y = datestring(0);
print y;
6/15/1996
Source
time.src
Globals
None
See also
date, datestr, datestrymd, time, timestr, ethsec
456
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE datestrymd
Purpose
Returns a date in a string.
Format
str = datestrymd(d);
Input
d 41 vector, like the date function returns. If this is 0, the date function
will be called for the current system date.
Output
str 8 character string containing current date in the form: yyyymmdd
Example
d = { 1998, 6, 15, 0 };
y = datestrymd(d);
print y;
19980615
Source
time.src
Globals
None
See also
date, datestr, datestring, time, timestr, ethsec
457
dayinyr 25. COMMAND REFERENCE
Purpose
Returns day number in the year of a given date.
Format
daynum = dayinyr(dt );
Input
dt 31 or 41 vector, date to check. The date should be in the form returned
by date.
Output
daynum scalar, the day number of that date in that year.
Example
x = { 1998, 6, 15, 0 };
y = dayinyr(x);
print y;
166.00000
Source
time.src
Globals
isleap
458
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE debug
Purpose
Runs a program under the source level debugger.
Format
debug lename;
Input
lename The name of the program to debug.
459
declare 25. COMMAND REFERENCE
Purpose
To initialize matrices and strings at compile time.
Format
declare [[type]] symbol [[aop clist]];
Input
type optional literal, specifying the type of the symbol.
matrix
string
if type is not specied, matrix is assumed.
symbol the name of the symbol being declared.
aop the type of assignment to be made.
= if not initialized, initialize.
if already initialized, reinitialize.
!= if not initialized, initialize.
if already initialized, reinitialize.
:= if not initialized, initialize.
if already initialized, redenition error.
?= if not initialized, initialize.
if already initialized, leave as is.
If aop is specied, clist must be also.
clist a list of constants to assign to symbol .
If aop clist is not specied, symbol is initialized as a scalar 0 or a null
string.
Example
declare matrix x,y,z;
x = 0
y = 0
z = 0
declare string x = "This string.";
460
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE declare
x = This string.
declare matrix x;
x = 0
declare matrix x != { 1 2 3, 4 5 6, 7 8 9 };
x =
1 2 3
4 5 6
7 8 9
declare matrix x[3,3] = 1 2 3 4 5 6 7 8 9;
x =
1 2 3
4 5 6
7 8 9
declare matrix x[3,3] = 1;
x =
1 1 1
1 1 1
1 1 1
declare matrix x[3,3];
x =
0 0 0
0 0 0
0 0 0
declare matrix x = 1 2 3 4 5 6 7 8 9;
x =
1
2
3
4
5
6
7
8
9
declare matrix x = dog cat;
x =
DOG
CAT
461
declare 25. COMMAND REFERENCE
declare matrix x = "dog" "cat";
x =
dog
cat
Remarks
The declare syntax is similar to the let statement.
declare generates no executable code. This is strictly for compile time initialization.
The data on the right-hand side of the equal sign must be constants. No expressions or
variables are allowed.
declare statements are intended for initialization of global matrices and strings that are
used by procedures in a library system.
It is best to place declare statements in a separate le from procedure denitions. This
will prevent redenition errors when rerunning the same program without clearing your
workspace.
Complex numbers can be entered by joining the real and imaginary parts with a sign
(+ or -); there can be no spaces between the numbers and the sign. Numbers with no
real part can be entered by appending an i to the number.
There should be only one declaration for any symbol in a program. Multiple
declarations of the same symbol should be considered a programming error. When
GAUSS is looking through the library to reconcile a reference to a matrix or a string, it
will quit looking as soon as a symbol with the correct name is found. If another symbol
with the same name existed in another le, it would never be found. Only the rst one
in the search path would be available to programs.
Here are some of the possible uses of the three forms of declaration:
!=, = Interactive programming or any situation where a global by the same name
will probably be sitting in the symbol table when the le containing the
declare statement is compiled. The symbol will be reset.
This allows mixing declare statements with the procedure denitions that
reference the global matrices and strings or placing them in your main le.
:= Redenition is treated as an error because you have probably just
outsmarted yourself. This will keep you out of trouble because it wont
allow you to zap one symbol with another value that you didnt know was
getting mixed up in your program. You probably need to rename one of
them.
You need to place declare statements in a separate le from the rest of
your program and procedure denitions.
462
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE declare
?= Interactive programming where some global defaults were set when you
started and you dont want them reset for each successive run even if the
le containing the declares gets recompiled. This can get you into trouble
if you are not careful.
Ctrl-W controls the declare statement warning level. If declare warnings are on, you
will be warned whenever a declare statement encounters a symbol that is already
initialized. Heres what happens when you declare a symbol that is already initialized
when declare warnings are turned on:
declare != Reinitialize and warn.
declare := Crash with fatal error.
declare ?= Leave as is and warn.
If declare warnings are o, no warnings are given for the != and ?= cases.
See also
let, external
463
delete 25. COMMAND REFERENCE
Purpose
Deletes global symbols from the symbol table.
Format
delete -ags symbol1,symbol2,symbol3;
Remarks
This completely and irrevocably deletes a symbol from GAUSSs memory and
workspace. It will no longer show up when the show command is used.
The following ags are dened:
p procedures
k keywords
f fn functions
m matrices
s strings
g only procedures with global references
l only procedures with all local references
n no pause for conrmation
Flags must be preceded by a slash (e.g. -pfk) and are dened in the same way as the
show command. If symbol names are ended with an asterisk, any names matching
those rst letters will be deleted. If the n (no pause) ag is used, you will not be asked
for conrmation for each symbol.
This command is supported only from COMMAND level. Since the interpreter
executes a compiled pseudo-code, this command would invalidate a previously compiled
code image and therefore would destroy any program it was a part of. If any symbols
are deleted, all procedures, keywords and functions with global references will be
deleted as well.
Example
print x;
96.000000
6.0000000
14.000000
3502965.9
delete -m x;
At the Delete? [Yes No Previous Quit] prompt, enter y.
464
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE delif
Purpose
Deletes rows from a matrix. The rows deleted are those for which there is a 1 in the
corresponding row of e.
Format
y = delif(x,e);
Input
x NK data matrix.
e N1 logical vector (vector of 0s and 1s).
Output
y MK data matrix consisting of the rows of y for which there is a 0 in the
corresponding row of e. If no rows remain, delif will return a scalar
missing.
Remarks
The input e will usually be generated by a logical expression using dot operators. For
instance:
y = delif(x, x[.,2] .> 100);
will delete all rows of x whose second element is greater than 100. The remaining rows
of x will be assigned to y.
Example
x = { 0 10 20,
30 40 50,
60 70 80 };
/* logical vector */
e = (x[.,1] .gt 0) .and (x[.,3] .lt 100);
y = delif(x,e);
Here is the resulting matrix y:
0 10 20
All rows for which the elements in column 1 are greater than 0 and the elements in
column 3 are less than 100 are deleted.
Source
datatran.src
Globals
None
See also
selif
465
denseSubmat 25. COMMAND REFERENCE
Purpose
Returns dense submatrix of sparse matrix.
Format
c = denseSubmat(x,r,c);
Input
x MN sparse matrix.
r K1 vector, row indices.
c L1 vector, column indices.
Output
e KL dense matrix.
Remarks
If r or c are scalar zeros, all rows or columns will be returned.
Source
sparse.src
See also
sparseFd, sparseFp
466
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE design
Purpose
Creates a design matrix of 0s and 1s from a column vector of numbers specifying the
columns in which the 1s should be placed.
Format
y = design(x);
Input
x N1 vector.
Output
y NK matrix, where K = maxc(x); each row of y will contain a single 1,
and the rest 0s. The one in the i
th
row will be in the round(x[i,1])
column.
Remarks
Note that x does not have to contain integers: it will be rounded to nearest if necessary.
Example
x = { 1, 1.2, 2, 3, 4.4 };
y = design(x);
y =
1 0 0 0
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1
Source
design.src
Globals
None
See also
cumprodc, cumsumc, recserrc
467
det 25. COMMAND REFERENCE
Purpose
Returns the determinant of a square matrix.
Format
y = det(x);
Input
x NN square matrix.
Output
y determinant of x.
Remarks
x may be any valid expression that returns a square matrix (number of rows equals
number of columns).
det computes a LU decomposition.
detl can be much faster in many applications.
Example
x = { 3 2 1,
0 1 -2,
1 3 4 };
y = det(x);
x =
3 2 1
0 1 2
1 3 4
y = 25
See also
detl
468
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE detl
Purpose
Returns the determinant of the last matrix that was passed to one of the intrinsic
matrix decomposition routines.
Format
y = detl;
Remarks
Whenever one of the following functions is executed, the determinant of the matrix is
also computed and stored in a system variable. This function will return the value of
that determinant and, because the value has been computed in a previous instruction,
this will require no computation.
The following functions will set the system variable used by detl:
chol(x)
crout(x)
croutp(x)
det(x)
inv(x)
invpd(x)
solpd(y,x) determinant of x
y/x determinant of x when neither argument is a scalar
or
determinant of x

x if x is not square
Example
If both the inverse and the determinant of the matrix are needed, the following two
commands will return both with the minimum amount of computation:
xi = inv(x);
xd = detl;
The function det(x) returns the determinant of a matrix using the Crout
decomposition. If you only want the determinant of a positive denite matrix, the
following code will be the fastest for matrices larger than 1010:
call chol(x);
xd = detl;
The Cholesky decomposition is computed and the result from that is discarded. The
determinant saved during that instruction is retrieved using detl. This can execute up
to 2.5 times faster than det(x) for large positive denite matrices.
See also
det
469
dt 25. COMMAND REFERENCE
Purpose
Computes a discrete Fourier transform.
Format
y = dt(x);
Input
x N1 vector.
Output
y N1 vector.
Remarks
The transform is divided by N.
This uses a second-order Goertzel algorithm. It is considerably slower than t, but it
may have some advantages in some circumstances. For one thing, N does not have to
be an even power of 2.
Source
dfft.src
Globals
None
See also
dti, t, ti
470
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dti
Purpose
Computes inverse discrete Fourier transform.
Format
y = dti(x);
Input
x N1 vector.
Output
y N1 vector.
Remarks
The transform is divided by N.
This uses a second-order Goertzel algorithm. It is considerably slower than ti, but it
may have some advantages in some circumstances. For one thing, N does not have to
be an even power of 2.
Source
dffti.src
Globals
None
See also
t, dti, ti
471
dfree 25. COMMAND REFERENCE
Purpose
Returns the amount of room left on a diskette or hard disk.
Format
y = dfree(drive);
Input
drive scalar, valid disk drive number.
Output
y number of bytes free.
Portability
Unix
The dfree function is not supported in Unix.
Remarks
Valid disk drive numbers are 0 = default, 1 = A, 2 = B, etc. If an error is encountered,
dfree will return -1.
See also
coreleft
472
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE diag
Purpose
Creates a column vector from the diagonal of a matrix.
Format
y = diag(x);
Input
x NK matrix.
Output
y min(N,K)x1 vector.
Remarks
The matrix need not be square.
diagrv reverses the procedure and puts a vector into the diagonal of a matrix.
Example
x = rndu(3,3);
y = diag(x);
x =
0.660818 0.367424 0.302208
0.204800 0.077357 0.145755
0.712284 0.353760 0.642567
y =
0.660818
0.077357
0.642567
See also
diagrv
473
diagrv 25. COMMAND REFERENCE
Purpose
Inserts a vector into the diagonal of a matrix.
Format
y = diagrv(x,v);
Input
x NK matrix.
v min(N,K) vector.
Output
y NK matrix equal to x with its principal diagonal elements equal to those
of v.
Remarks
diag reverses the procedure and pulls the diagonal out of a matrix.
Example
x = rndu(3,3);
v = ones(3,1);
y = diagrv(x,v);
x =
0.660818 0.367424 0.302208
0.204800 0.077357 0.145755
0.712284 0.353760 0.642567
v =
1.000000
1.000000
1.000000
y =
1.000000 0.367424 0.302208
0.204800 1.000000 0.145755
0.712284 0.353760 1.000000
See also
diag
474
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE disable
Purpose
Disables the invalid operation interrupt of the numeric processor. This aects the way
missing values are handled in most calculations.
Format
disable;
Portability
Unix, OS/2, Windows
This function is not used by these platforms. The invalid operation is always disabled
Remarks
When disable is in eect, missing values will be allowed in most calculations. A missing
value is a special oating point encoding which the numeric processor considers a NaN
(Not A Number). disable allows missing values to pass through most calculations
unchanged, i.e., a number plus a missing value is a missing value.
The default when GAUSS is started is to have the program crash when missing values
are encountered or when any operation sets the numeric processors invalid operation
exception. See the Debugger or Error Handling and Debugging chapter in your
supplement.
If disable is on, these operations will return a NaN, and the program will continue.
This can complicate debugging for programs that do not need to handle missing values,
because the program may proceed far beyond the point that NaNs are created before it
actually crashes.
The opposite of disable is enable, which is the default. If enable is on, the program
will terminate with an Invalid oating point operation error message.
The following operators are specially designed to handle missing values and are not
aected by the disable/enable commands: b/a (matrix division when a is not square
and neither a nor b is scalar), counts, ismiss, maxc, maxindc, minc, minindc, miss,
missex, missrv, moment, packr, scalmiss, sortc.
ndpcntrl can be used to get and reset the numeric processor control word, so it is more
exible than enable/disable.
See also
enable, miss, missrv, ndpchk, ndpcntrl
475
do while, do until 25. COMMAND REFERENCE
Purpose
Executes a series of statements in a loop as long as a given expression is true (or false).
Format
do while expression;
or
do until expression;
.
.
.
statements in loop
.
.
.
endo;
Remarks
expression is any expression that returns a scalar. It is TRUE if it is nonzero and
FALSE if it is zero.
In a do while loop, execution of the loop will continue as long as the expression is
TRUE.
In a do until loop, execution of the loop will continue as long as the expression is
FALSE.
The condition is checked at the top of the loop. If execution can continue, the
statements of the loop are executed until the endo is encountered. Then GAUSS
returns to the top of the loop and checks the condition again.
The do loop does not automatically increment a counter. See the rst example below.
do loops may be nested.
It is often possible to avoid using loops in GAUSS by using the appropriate matrix
operator or function. It is almost always preferable to avoid loops when possible, since
the corresponding matrix operations can be much faster.
Example
476
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE do while, do until
format /rdn 1,0;
space = " ";
comma = ",";
i = 1;
do while i <= 4;
j = 1;
do while j <= 3;
print space i comma j;;
j = j+1;
endo;
i = i+1;
print;
endo;
1, 1 1, 2 1, 3
2, 1 2, 2 2, 3
3, 1 3, 2 3, 3
4, 1 4, 2 4, 3
In the example above, two nested loops are executed and the loop counter values are
printed out. Note that the inner loop counter must be reset inside of the outer loop
before entering the inner loop. An empty print statement is used to print a carriage
return/line feed sequence after the inner loop nishes.
The following are examples of simple loops that execute a predetermined number of
times. These loops will both have the result shown.
format /rd 1,0;
i = 1;
do while i <= 10;
print i;;
i = i+1;
endo;
i = 1;
do until i > 10;
print i;;
i = i+1;
endo;
1 2 3 4 5 6 7 8 9 10
See also
continue, break
477
dos 25. COMMAND REFERENCE
Purpose
Provides access to the operating system from within GAUSS.
Format
dos [[s]];
Portability
Unix
Control and output go to the controlling terminal, if there is one.
This function may be used in terminal mode.
OS/2, Windows
The dos function opens a new terminal.
Running programs in the background is allowed in all three of the aforementioned
platforms.
Input
s literal or ^string, the OS command to be executed.
Remarks
This allows all operating system commands to be used from within GAUSS. It allows
other programs to be run even though GAUSS is still resident in memory.
If no operating system command (for instance, dir or copy) or program name is
specied, then a shell of the operating system will be entered which can be used just
like the base level OS. The exit command must be given from the shell to get back into
GAUSS. If a command or program name is included, the return to GAUSS is
automatic after the DOS command has been executed.
All matrices are retained in memory when the OS is accessed in this way. This
command allows the use of word processing, communications, and other programs from
within GAUSS.
Do not execute programs that terminate and remain resident. This is because they will
be left resident inside of GAUSSs workspace. Some examples are programs that create
ramdisks or print spoolers.
If the command is to be taken from a string variable, the ^ (caret) must precede the
string.
The shorthand > can be used in place of the word DOS.
Example
478
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dos
comstr = "basic myprog";
dos ^comstr;
This will cause the BASIC program myprog to be run. When that program is nished,
control will automatically return to GAUSS.
>dir *.prg;
This will use the DOS dir command to print a directory listing of all les with a .prg
extension. When the listing is nished, control will be returned to GAUSS.
dos;
This will cause a second level OS shell to be entered. The OS prompt will appear and
OS commands or other programs can be executed. To return to GAUSS, type exit.
See also
exit, exec
479
dotfeqdotfne 25. COMMAND REFERENCE
Purpose
Fuzzy comparison functions. These functions use fcmptol to fuzz the comparison
operations to allow for roundo error.
Format
y = dotfeq(a,b);
y = dotfge(a,b);
y = dotfgt(a,b);
y = dote(a,b);
y = dott(a,b);
y = dotfne(a,b);
Input
a NK matrix, rst matrix.
b LM matrix, second matrix, EE compatible with a.
fcmptol global scalar, comparison tolerance. The default value is 1.0e 15.
Output
y max(N,L) by max(K,M) matrix of 1s and 0s.
Remarks
The return value is 1 if true and 0 if false.
The statement:
y = dotfeq(a,b);
is equivalent to:
y = a .eq b;
The calling program can reset fcmptol before calling these procedures.
_fcmptol = 1e-12;
480
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dotfeqdotfne
Example
x = rndu(2,2);
y = rndu(2,2);
t = dotfge(x,y);
x =
0.85115559 0.98914218
0.12703276 0.43365175
y =
0.41907226 0.49648058
0.58039125 0.98200340
t =
1.0000000 1.0000000
0.0000000 0.0000000
Source
fcompare.src
Globals
fcmptol
See also
feq
481
dstat 25. COMMAND REFERENCE
Purpose
Compute descriptive statistics.
Format
{ vnam,mean,var,std,min,max,valid,mis } = dstat(dataset ,vars);
Input
dataset string, name of data set.
If dataset is null or 0, vars will be assumed to be a matrix containing the
data.
vars the variables.
If dataset contains the name of a GAUSS data set, vars will be interpreted
as:
K1 character vector names of variables.
K1 numeric vector indices of columns.
These can be any size subset of the variables in the data set and can be in
any order. If a scalar 0 is passed, all columns of the data set will be used.
If dataset is null or 0, vars will be interpreted as:
NK matrix the data on which to compute the descriptive
statistics.
Defaults are provided for the following global input variables, so they can be ignored
unless you need control over the other options provided by this procedure.
altnam global matrix, default 0.
This can be a K1 character vector of alternate variable names for the
output.
miss global scalar, default 0.
0 there are no missing values (fastest).
1 listwise deletion, drop a row if any missings occur in it.
2 pairwise deletion.
row global scalar, the number of rows to read per iteration of the read loop.
if 0, (default) the number of rows will be calculated internally.
output global scalar, controls output, default 1.
482
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dstat
1 print output table.
0 do not print output.
Output
vnam K1 character vector, the names of the variables used in the statistics.
mean K1 vector, means.
var K1 vector, variance.
std K1 vector, standard deviation.
min K1 vector, minima.
max K1 vector, maxima.
valid K1 vector, the number of valid cases.
mis K1 vector, the number of missing cases.
Remarks
If pairwise deletion is used, the minima and maxima will be the true values for the
valid data. The means and standard deviations will be computed using the correct
number of valid observations for each variable.
Source
dstat.src
Globals
output, dstatd, dstatx
483
dtvnormal 25. COMMAND REFERENCE
Purpose
Normalizes a date and time vector.
Format
d = dtvnormal(t );
Input
t 18 date and time vector that has one or more elements outside the
normal range.
Output
d Normalized 18 date and time vector.
Remarks
The date and time vector is a 18 vector whose elements consist of:
Year: Year, four digit integer.
Month: 1-12, Month in year.
Day: 1-31, Day of month.
Hour: 0-23, Hours since midnight.
Min: 0-59, Minutes.
Sec: 0-59, Seconds.
DoW: 0-6, Day of week, 0 = Sunday.
DiY: 0-365, Days since Jan 1 of year.
The last two elements are ignored on input.
Example
format /rd 10,2;
x = { 1996 14 21 6 21 37 0 0 };
d = dtvnormal(x);
d = 1997.00 2.00 21.00 6.00 21.00 37.00 2.00 51.00
Globals
None.
See also
date, ethsec, etstr, time, timestr, timeutc, utctodtv
484
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dummy
Purpose
Creates a set of dummy (0/1) variables by breaking up a variable into specied
categories. The highest (rightmost) category is unbounded on the right.
Format
y = dummy(x,v);
Input
x N1 vector of data that is to be broken up into dummy variables.
v (K1)1 vector specifying the K1 breakpoints (these must be in
ascending order) that determine the K categories to be used. These
categories should not overlap.
Output
y NK matrix containing the K dummy variables.
Remarks
Missings are deleted before the dummy variables are created.
All categories are open on the left (i.e., do not contain their left boundaries) and all but
the highest are closed on the right (i.e., do contain their right boundaries). The highest
(rightmost) category is unbounded on the right. Thus, only K1 breakpoints are
required to specify K dummy variables.
The function dummybr is similar to dummy, but in that function the highest category
is bounded on the right. The function dummydn is also similar to dummy, but in that
function a specied column of dummies is dropped.
Example
x = { 0, 2, 4, 6 };
v = { 1, 5, 7 };
y = dummy(x,v);
The result y looks like this:
1 0 0 0
0 1 0 0
0 1 0 0
0 0 1 0
485
dummy 25. COMMAND REFERENCE
The vector v will produce 4 dummies satisfying the following conditions:
x 1
1 < x 5
5 < x 7
7 < x
Source
datatran.src
Globals
None
See also
dummybr, dummydn
486
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dummybr
Purpose
Creates a set of dummy (0/1) variables. The highest (rightmost) category is bounded
on the right.
Format
y = dummybr(x,v);
Input
x N1 vector of data that is to be broken up into dummy variables.
v K1 vector specifying the K breakpoints (these must be in ascending
order) that determine the K categories to be used. These categories should
not overlap.
Output
y NK matrix containing the K dummy variables. Each row will have a
maximum of one 1.
Remarks
Missings are deleted before the dummy variables are created.
All categories are open on the left (i.e., do not contain their left boundaries) and are
closed on the right (i.e., do contain their right boundaries). Thus, K breakpoints are
required to specify K dummy variables.
The function dummy is similar to dummybr, but in that function the highest category
is unbounded on the right.
Example
x = { 0,
2,
4,
6 };
v = { 1,
5,
7 };
y = dummybr(x,v);
487
dummybr 25. COMMAND REFERENCE
The resulting matrix y looks like this:
1 0 0
0 1 0
0 1 0
0 0 1
The vector v = 1 5 7 will produce 3 dummies satisfying the following conditions:
x 1
1 < x 5
5 < x 7
Source
datatran.src
Globals
None
See also
dummydn, dummy
488
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

D
25. COMMAND REFERENCE dummydn
Purpose
Creates a set of dummy (0/1) variables by breaking up a variable into specied
categories. The highest (rightmost) category is unbounded on the right, and a specied
column of dummies is dropped.
Format
y = dummydn(x,v,p);
Input
x N1 vector of data to be broken up into dummy variables.
v K1 vector specifying the K1 breakpoints (these must be in ascending
order) that determine the K categories to be used. These categories should
not overlap.
p positive integer in the range [1,K], specifying which column should be
dropped in the matrix of dummy variables.
Output
y N(K1) matrix containing the K1 dummy variables.
Remarks
This is just like the function dummy, except that the p
th
column of the matrix of
dummies is dropped. This ensures that the columns of the matrix of dummies do not
sum to 1, and so these variables will not be collinear with a vector of ones.
Missings are deleted before the dummy variables are created.
All categories are open on the left (i.e., do not contain their left boundaries) and all but
the highest are closed on the right (i.e., do contain their right boundaries). The highest
(rightmost) category is unbounded on the right. Thus, only K1 breakpoints are
required to specify K dummy variables.
Example
x = { 0, 2, 4, 6 };
v = { 1, 5, 7 };
p = 2;
y = dummydn(x,v,p);
489
dummydn 25. COMMAND REFERENCE
The resulting matrix y looks like this:
1 0 0
0 0 0
0 0 0
0 1 0
The vector v = 1 5 7 will produce 4 dummies satisfying the following conditions:
x 1
1 < x 5
5 < x 7
7 < x
Since p = 2, the second dummy is dropped.
Source
datatran.src
Globals
None
See also
dummy, dummybr
490
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE ed
Purpose
To access an alternate editor.
Format
ed lename;
Input
lename The name of the le to be edited.
Remarks
The default name of the editor is b.exe. To change the name of the editor used type:
ed = editor name ags;
or
ed = editor name ags;
The ags are any command line ags you may want between the name of the editor
and the lename when your editor is invoked. The quoted version will prevent the ags,
if any, from being forced to uppercase.
This command can be placed in the startup le so it will be set for you automatically
when you start GAUSS.
491
edit 25. COMMAND REFERENCE
Purpose
To edit a disk le.
Format
edit lename;
Remarks
Example
edit b:test1;
See also
run, medit, editm
492
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE editm
Purpose
To edit a matrix. See medit for a full-screen matrix editor.
Format
y = editm(x);
Portability
Unix
editm is not supported.
DOS
and e can be entered with Alt-P and Alt-E.
Input
x any legal expression that returns a matrix.
Output
y edited matrix.
Remarks
A matrix editor is invoked when the editm function is called. This editor allows you to
move around the matrix you are editing and make changes. (This editor is also used by
the con function.)
When editm appears in a program, the following will appear on the screen:
[1,1] = 1.2361434675434E+002 ?
The number after the equal sign is the [1,1] element of the matrix being edited.
There are two general ways to move around the matrix. First, you can simply type
numbers separated by commas, spaces or carriage returns. The editor will
automatically move you left to right and down through the matrix. That is, you will
rst go across the rst row left to right, then across the second row, and so on. When
you reach the last element in the matrix, you will automatically cycle back to the rst
element. When this occurs, the editors prompt will again be displayed on the screen.
To get out of the editor, type a semicolon. If a semicolon is typed after you have
entered a number, that number will be saved.
493
editm 25. COMMAND REFERENCE
The second general way to move around the matrix is to use the cursor keys. The left
and right cursor keys move you back and forth along rows. The up and down cursor
keys move you up and down in a column. When you come to the end of a row or
column, movement is left and up, or right and down. If, for instance, you are moving
left to right along a row using the right cursor key, you will move down to the
beginning of the next row when you come to the end of the row you are in. GAUSS will
beep at you if you try to move outside the matrix.
The question mark you see on the screen is the matrix editors prompt. If you want to
change the number that is in the [1,1] position of the matrix, just type in the number
you want. If you do not want to change anything, you can move to a dierent element
by hitting the appropriate cursor key. If you start to type a number and then hit a
cursor key, the number will not be saved. The BACKSPACE key will delete characters
to the left of the cursor.
If you type in a space, comma or carriage return before you type a number, nothing
will happen. GAUSS will wait until you type a number or use a cursor key to move to
a new element.
Numbers can be entered in scientic notation. The syntax is: dE+n or dE-n, where d is
a number and n is an integer power of 10. Thus, 1E+10, 1.1e-4, 1100E+1 are all legal.
Complex numbers can be entered by joining the real and imaginary parts with a sign
(+ or -); there can be no spaces between the numbers and the sign. Numbers with no
real part can be entered by appending an i to the number. For example, 1.2+23, 8.56i,
3-2.1i, -4.2e+6i and 1.2e-4-4.5e+3i are all legal.
An editm function can appear anywhere in an expression that any other function can
appear. Thus, for instance, the following statements are legal:
y = x*editm(z);
y = sqrt(editm(x));
Example
y = editm(ones(2,2));
[1,1] = 1.000000000000E+000 ? 2 3 4 5[space]
[1,1] = 2.000000000000E+000 ? 6 7 8 9[;]
y =
6.000000 7.000000
8.000000 9.000000
In this example, a 22 matrix of 1s is edited. Spaces are used to separate the numbers
as they are entered. Note that after 4 numbers have been entered, the editor has cycled
494
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE editm
back to the [1,1] position in the matrix again. When this occurs, the prompt appears
on the screen again. This time, after 4 more numbers have been entered, a semicolon is
entered (as indicated in the brackets). This causes the editor to stop and the edited
matrix to be returned.
See also
con, medit
495
eig 25. COMMAND REFERENCE
Purpose
Computes the eigenvalues of a general matrix.
Format
va = eig(x);
Input
x NN matrix.
Output
va N1 vector, the eigenvalues of x.
Remarks
If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]
to the scalerr function will return the index of the eigenvalue that failed. The
eigenvalues for indices scalerr(va[1])+1 to N should be correct.
Error handling is controlled with the low bit of the trap ag.
trap 0 set va[1] and terminate with message
trap 1 set va[1] and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst.
Example
x = { 4 8 1,
9 4 2,
5 5 7 };
va = eig(x);
va =
4.4979246
14.475702
5.0222223
See also
eigh, eighv, eigv
496
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigcg
Purpose
Computes the eigenvalues of a complex, general matrix. (Included for backwards
compatibilityplease use eig instead.)
Format
{ var,vai } = eigcg(xr,xi );
Input
xr NN matrix, real part.
xi NN matrix, imaginary part.
Output
var N1 vector, real part of eigenvalues.
vai N1 vector, imaginary part of eigenvalues.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices eigerr+1 to N should be correct.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst.
Source
eigcg.src
Globals
eigerr
See also
eigcg2, eigch, eigrg, eigrs
497
eigcg2 25. COMMAND REFERENCE
Purpose
Computes eigenvalues and eigenvectors of a complex, general matrix. (Included for
backwards compatibilityplease use eigv instead.)
Format
{ var,vai ,ver,vei } = eigcg2(xr,xi );
Input
xr NN matrix, real part.
xi NN matrix, imaginary part.
Output
var N1 vector, real part of eigenvalues.
vai N1 vector, imaginary part of eigenvalues.
ver NN matrix, real part of eigenvectors.
vei NN matrix, imaginary part of eigenvectors.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices eigerr+1 to N should be correct. The eigenvectors
are not computed.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst. The
columns of ver and vei contain the real and imaginary eigenvectors of x in the same
order as the eigenvalues. The eigenvectors are not normalized.
Source
eigcg.src
Globals
eigerr
See also
eigcg, eigch, eigrg, eigrs
498
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigch
Purpose
Computes the eigenvalues of a complex, hermitian matrix. (Included for backwards
compatibilityplease use eigh instead.)
Format
va = eigch(xr,xi );
Input
xr NN matrix, real part.
xi NN matrix, imaginary part.
Output
va N1 vector, real part of eigenvalues.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices 1 to eigerr1 should be correct.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are in ascending order. The eigenvalues for a complex hermitian
matrix are always real so this procedure returns only one vector.
Source
eigch.src
Globals
eigerr
See also
eigch2, eigcg, eigrg, eigrs
499
eigch2 25. COMMAND REFERENCE
Purpose
Computes eigenvalues and eigenvectors of a complex, hermitian matrix. (Included for
backwards compatibilityplease use eighv instead.)
Format
{ var,vai ,ver,vei } = eigch2(xr,xi );
Input
xr NN matrix, real part.
xi NN matrix, imaginary part.
Output
var N1 vector, real part of eigenvalues.
vai N1 vector, imaginary part of eigenvalues.
ver NN matrix, real part of eigenvectors.
vei NN matrix, imaginary part of eigenvectors.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices 1 to eigerr1 should be correct. The eigenvectors
are not computed.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are in ascending order. The eigenvalues of a complex hermitian matrix
are always real. This procedure returns a vector of zeros for the imaginary part of the
eigenvalues so the syntax is consistent with other eigxx procedure calls. The columns of
ver and vei contain the real and imaginary eigenvectors of x in the same order as the
eigenvalues. The eigenvectors are orthonormal.
Source
eigch.src
Globals
eigerr
See also
eigch, eigcg, eigrg, eigrs
500
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigh
Purpose
Computes the eigenvalues of a complex hermitian or real symmetric matrix.
Format
va = eigh(x);
Input
x NN matrix.
Output
va N1 vector, the eigenvalues of x.
Remarks
If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]
to the scalerr function will return the index of the eigenvalue that failed. The
eigenvalues for indices 1 to scalerr(va[1])-1 should be correct.
Error handling is controlled with the low bit of the trap ag.
trap 0 set va[1] and terminate with message
trap 1 set va[1] and continue execution
The eigenvalues are in ascending order.
The eigenvalues of a complex hermitian or real symmetric matrix are always real.
See also
eig, eighv, eigv
501
eighv 25. COMMAND REFERENCE
Purpose
Computes eigenvalues and eigenvectors of a complex hermitian or a real symmetric
matrix.
Format
{ va,ve } = eighv(x);
Input
x NN matrix.
Output
va N1 vector, the eigenvalues of x.
ve NN matrix, the eigenvectors of x.
Remarks
If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]
to the scalerr function will return the index of the eigenvalue that failed. The
eigenvalues for indices 1 to scalerr(va[1])-1 should be correct. The eigenvectors are not
computed.
Error handling is controlled with the low bit of the trap ag.
trap 0 set va[1] and terminate with message
trap 1 set va[1] and continue execution
The eigenvalues are in ascending order. The columns of ve contain the eigenvectors of x
in the same order as the eigenvalues. The eigenvectors are orthonormal.
The eigenvalues of a complex hermitian or real symmetric matrix are always real.
See also
eig, eigh, eigv
502
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigrg
Purpose
Computes the eigenvalues of a real, general matrix. (Included for backwards
compatibilityplease use eig instead.)
Format
{ var,vai } = eigrg(x);
Input
x NN matrix.
Output
var N1 vector, real part of eigenvalues.
vai N1 vector, imaginary part of eigenvalues.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices eigerr+1 to N should be correct.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst.
Example
x = { 1 2i 3,
4i 5+3i 6,
7 8 9i };
{y,n} = eigrg(x);
y =
6.3836054
2.0816489
10.301956
n =
7.2292503
1.4598755
6.2306252
503
eigrg 25. COMMAND REFERENCE
Source
eigrg.src
Globals
eigerr
See also
eigrg2, eigcg, eigch, eigrs
504
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigrg2
Purpose
Computes eigenvalues and eigenvectors of a real, general matrix. (Included for
backwards compatibilityplease use eigv instead.)
Format
{ var,vai ,ver,vei } = eigrg2(x);
Input
x NN matrix.
Output
var N1 vector, real part of eigenvalues.
vai N1 vector, imaginary part of eigenvalues.
ver NN matrix, real part of eigenvectors.
vei NN matrix, imaginary part of eigenvectors.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices eigerr+1 to N should be correct. The eigenvectors
are not computed.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst. The
columns of ver and vei contain the real and imaginary eigenvectors of x in the same
order as the eigenvalues. The eigenvectors are not normalized.
Source
eigrg.src
Globals
eigerr
See also
eigrg, eigcg, eigch, eigrs
505
eigrs 25. COMMAND REFERENCE
Purpose
Computes the eigenvalues of a real, symmetric matrix. (Included for backwards
compatibilityplease use eigh instead.)
Format
va = eigrs(x);
Input
x NN matrix.
Output
va N1 vector, eigenvalues of x.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues for indices 1 to eigerr1 should be correct.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are in ascending order. The eigenvalues for a real symmetric matrix are
always real so this procedure returns only one vector.
Source
eigrs.src
Globals
eigerr
See also
eigrs2, eigcg, eigch, eigrg
506
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eigrs2
Purpose
Computes eigenvalues and eigenvectors of a real, symmetric matrix. (Included for
backwards compatibilityplease use eighv instead.)
Format
{ va,ve } = eigrs2(x);
Input
x NN matrix.
Output
va N1 vector, eigenvalues of x.
ve NN matrix, eigenvectors of x.
eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,
otherwise eigerr is set to the index of the eigenvalue that failed. The
eigenvalues and eigenvectors for indices 1 to eigerr1 should be correct.
Remarks
Error handling is controlled with the low bit of the trap ag.
trap 0 set eigerr and terminate with message
trap 1 set eigerr and continue execution
The eigenvalues are in ascending order. The columns of ve contain the eigenvectors of x
in the same order as the eigenvalues. The eigenvectors are orthonormal.
The eigenvalues and eigenvectors for a real symmetric matrix are always real so this
procedure returns only the real parts.
Source
eigrs.src
Globals
eigerr
See also
eigrs, eigcg, eigch, eigrg
507
eigv 25. COMMAND REFERENCE
Purpose
Computes the eigenvalues and eigenvectors of a general matrix.
Format
{ va,ve } = eigv(x);
Input
x NN matrix.
Output
va N1 vector, the eigenvalues of x.
ve NN matrix, the eigenvectors of x.
Remarks
If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]
to the scalerr function will return the index of the eigenvalue that failed. The
eigenvalues for indices scalerr(va[1])+1 to N should be correct. The eigenvectors are
not computed.
Error handling is controlled with the low bit of the trap ag.
trap 0 set va[1] and terminate with message
trap 1 set va[1] and continue execution
The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will
appear consecutively with the eigenvalue having the positive imaginary part rst. The
columns of ve contain the eigenvectors of x in the same order as the eigenvalues. The
eigenvectors are not normalized.
Example
x = { 4 8 1,
9 4 2,
5 5 7 };
{y,n} = eigv(x);
y =
4.4979246
14.475702
5.0222223
n =
0.66930459 0.64076622 0.40145623
0.71335708 0.72488533 0.26047487
0.019156716 0.91339349 1.6734214
See also
eig, eigh, eighv
508
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE enable
Purpose
Enables the invalid operation interrupt of the numeric processor. This aects the way
missing values are handled in most calculations.
Format
enable;
Portability
Unix, OS/2, Windows
Invalid operation is always disabled. enable is not supported by these platforms.
Remarks
When enable is in eect, missing values will not be allowed in most calculations. A
missing value is a special oating point encoding which the numeric processor considers
a NaN (Not A Number).
The default, when GAUSS is started, is to have the program crash when missing values
are encountered or when any operation sets the numeric processors invalid operation
exception. See the Debugger or Error Handling and Debugging chapter in your
supplement.
If enable is on, these operations will cause the program to terminate with an Invalid
oating point operation error message.
The opposite of enable is disable. If disable is on these operations will return a NaN,
and the program will continue. This can complicate debugging for programs that do
not need to handle missing values, because the program may proceed far beyond the
point that NaNs are created before it actually crashes.
The following operators are specially designed to handle missing values and are not
aected by the disable/enable commands: b/a (matrix division when a is not square),
counts, ismiss, maxc, maxindc, minc, minindc, miss, missex, missrv, moment, packr,
scalmiss, sortc.
ndpcntrl can be used to get and reset the numeric processor control word, and is more
exible than enable/disable.
See also
ndpcntrl, disable, miss, missrv, ndpchk
509
end 25. COMMAND REFERENCE
Purpose
Terminate a program.
Format
end;
Portability
Unix
end closes all windows except window 1. If you want to leave a programs windows
open, use stop.
OS/2, Windows
end closes all user-created windows.
DOS
COMMAND mode requires the screen to be in text mode, so it will be reset if it is in
graphics mode. The screen will revert to text mode whenever it drops to COMMAND
mode.
Remarks
end causes GAUSS to revert to COMMAND mode, and closes all open les. end also
closes the auxiliary output le and turns the screen on. It is not necessary to put an
end statement at the end of a program.
An end command can be placed above a label which begins a subroutine to make sure
that a program does not enter a subroutine without a gosub.
stop also terminates a program but closes no les and leaves the screen setting as it is.
Example
output on;
screen off;
print x;
end;
In this example a matrix x is printed to the auxiliary output. The screen is turned o
to speed up the printing. The end statement is used to terminate the program so the
output le will be closed and the screen will be turned back on.
See also
new, stop, system
510
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE endp
Purpose
Close a procedure or keyword denition.
Format
endp;
Remarks
endp marks the end of a procedure denition that began with a proc or keyword
statement. See Chapter 9 for details on writing and using procedures.
Example
proc regress(y,x);
retp(inv(xx)*xy);
endp;
x = { 1 3 2, 7 4 9, 1 1 6, 3 3 2 };
y = { 3, 5, 2, 7 };
b = regress(y,x);
x =
1.00000000 3.00000000 2.00000000
7.00000000 4.00000000 9.00000000
1.00000000 1.00000000 6.00000000
3.00000000 3.00000000 2.00000000
y =
3.00000000
5.00000000
2.00000000
7.00000000
b =
0.15456890
1.50276345
0.12840825
See also
proc, keyword, retp
511
envget 25. COMMAND REFERENCE
Purpose
Searches the environment for a dened name.
Format
y = envget(s);
Input
s string, the name to be searched for.
Output
y string, the string that corresponds to that name in the environment or a
null string if it is not found.
Example
proc dopen(file);
local fname,fp;
fname = envget("DPATH");
if fname $== "";
fname = file;
else;
if strsect(fname,strlen(fname),1) $== "\\";
fname = fname $+ file;
else;
fname = fname $+ "\\" $+ file;
endif;
endif;
open fp = ^fname;
retp(fp);
endp;
This is an example of a procedure which will open a data le using a path stored in an
environment string called DPATH. The procedure returns the le handle and is called
as follows:
fp = dopen(myle);
See also
cdir
512
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eof
Purpose
Tests if the end of a le has been reached.
Format
y = eof(fh);
Input
fh scalar, le handle.
Output
y scalar, 1 if end of le has been reached, else 0.
Remarks
This function is used with the readr and fgetsxxx commands to test for the end of a le.
The seekr function can be used to set the pointer to a specic row position in a data
set; the fseek function can be used to set the pointer to a specic byte oset in a le
opened with fopen.
Example
open f1 = dat1;
xx = 0;
do until eof(f1);
xx = xx+moment(readr(f1,100),0);
endo;
In this example, the data le dat1.dat is opened and given the handle f1. Then the
data are read from this data set and are used to create the moment (x

x) matrix of the
data. On each iteration of the loop, 100 additional rows of data are read in and the
moment matrix for this set of rows is computed, and added to the matrix xx. When all
the data have been read, xx will contain the entire moment matrix for the data set.
GAUSS will keep reading until eof(f1) returns the value 1, which it will when the end
of the data set has been reached. On the last iteration of the loop, all remaining
observations are read in if there are 100 or fewer left.
See also
open, readr, seekr
513
eqSolve 25. COMMAND REFERENCE
Purpose
Solves a system of nonlinear equations
Format
{ x, retcode } = eqSolve(&F,start );
Input
start K1 vector, starting values
&F scalar, a pointer to a procedure which computes the value at x of the
equations to be solved.
Output
x K1 vector, solution
retcode scalar, the return code:
1 Norm of the scaled function value is less than Tol. x given is an
approximate root of F(x) (unless Tol is too large).
2 The scaled distance between the last two steps is less than the
step-tolerance ( eqs StepTol). x may be an approximate root of
F(x), but it is also possible that the algorithm is making very slow
progress and is not near a root, or the step-tolerance is too large.
3 The last global step failed to decrease norm2(F(x)) suciently;
either x is close to a root of F(x) and no more accuracy is possible,
or an incorrectly coded analytic Jacobian is being used, or the
secant approximation to the Jacobian is inaccurate, or the
step-tolerance is too large.
4 Iteration limit exceeded.
5 Five consecutive steps of maximum step length have been taken;
either norm2(F(x)) asymptotes from above to a nite value in
some direction or the maximum step length is too small.
6 x seems to be an approximate local minimizer of norm2(F(x)) that
is not a root of F(x). To nd a root of F(x), restart eqSolve from a
dierent region.
Globals
eqs JacobianProc pointer to a procedure which computes the analytical Jacobian.
By default, eqSolve will compute the Jacobian numerically.
514
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eqSolve
eqs MaxIters scalar, the maximum number of iterations. Default = 100.
eqs StepTol scalar, the step tolerance. Default = macheps^(2/3).
eqs TypicalF K1 vector of the typical F(x) values at a point not near a root, used
for scaling. This becomes important when the magnitudes of the
components of F(x) are expected to be very dierent. By default, function
values are not scaled.
eqs TypicalX K1 vector of the typical magnitude of x, used for scaling. This
becomes important when the magnitudes of the components of x are
expected to be very dierent. By default, variable values are not scaled.
eqs IterInfo scalar, if nonzero, iteration information is printed. Default = 0;
Tol scalar, the tolerance of the scalar function f = 0.5 [[F(x)[[
2
required to
terminate the algorithm. Default = 1e-5
altnam K1 character vector of alternate names to be used by the printed output.
By default, the names X1, X2, X3... or X01, X02, X03 (depending on how
vpad is set) will be used.
output scalar. If non-zero, nal results are printed.
title string, a custom title to be printed at the top of the iterations report. By
default, only a generic title will be printed.
Remarks
The equation procedure should return a column vector containing the result for each
equation. For example:
Equation 1: x1^2 + x2^2 - 2 = 0
Equation 2: exp(x1-1) + x2^3 - 2 = 0
proc f(var);
local x1,x2,eqns;
x1 = var[1];
x2 = var[2];
eqns[1] = x1^2 + x2^2 - 2; /* Equation 1 */
eqns[2] = exp(x1-1) + x2^3 - 2; /* Equation 2 */
retp( eqns );
endp;
Example
515
eqSolve 25. COMMAND REFERENCE
eqsolveset;
proc f(x);
local f1,f2,f3;
f1 = 3*x[1]^3 + 2*x[2]^2 + 5*x[3] - 10;
f2 = -x[1]^3 - 3*x[2]^2 + x[3] + 5;
f3 = 3*x[1]^3 + 2*x[2]^2 - 4*x[3];
retp(f1|f2|f3);
endp;
proc fjc(x);
local fjc1,fjc2, fjc3;
fjc1 = 9*x[1]^2 ~ 4*x[2] ~ 5;
fjc2 = -3*x[1]^2 ~ -6*x[2] ~ 1;
fjc3 = 9*x[1]^2 ~ 4*x[2] ~ -4;
retp(fjc1|fjc2|fjc3);
endp;
start = { -1, 12, -1 };
_eqs_JacobianProc = &fjc;
{ x,tcode } = eqSolve(&f,start);
==========================================================================
EqSolve Version 3.2.22 2/24/97 9:54 am
==========================================================================
||F(X)|| at final solution: 0.93699762
--------------------------------------------------------------------------
Termination Code = 1:
Norm of the scaled function value is less than __Tol;
--------------------------------------------------------------------------
--------------------------------------------------------------------------
VARIABLE START ROOTS F(ROOTS)
--------------------------------------------------------------------------
X1 -1.00000 0.54144351 4.4175402e-06
X2 12.00000 1.4085912 -6.6263102e-06
X3 -1.00000 1.1111111 4.4175402e-06
--------------------------------------------------------------------------
516
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eqSolve
Source
eqsolve.src
517
erf, erfc 25. COMMAND REFERENCE
Purpose
Computes the Gaussian error function (erf) and its complement (erfc).
Format
y = erf(x);
y = erfc(x);
Input
x NK matrix.
Output
y NK matrix.
Remarks
The allowable range for x is:
x 0
The erf and erfc functions are closely related to the Normal distribution:
cdfn(x) =

1
2
(1 + erf(
x

2
)) x 0
1
2
erfc(
x

2
) x < 0
Example
x = { .5 .4 .3,
.6 .8 .3 };
y = erf(x);
y =
0.52049988 0.42839236 0.32862676
0.60385609 0.74210096 0.32862676
x = { .5 .4 .3,
.6 .8 .3 };
y = erfc(x);
y =
0.47950012 0.57160764 0.67137324
0.39614391 0.25789904 0.67137324
See also
cdfn, cdfnc
Technical Notes
erf and erfc are computed by summing the appropriate series and continued fractions.
They are accurate to about 10 digits.
518
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE error
Purpose
Allows the user to generate a user-dened error code which can be tested quickly with
the scalerr function.
Format
y = error(x);
Input
x scalar, in the range 065535.
Output
y scalar error code which can be interpreted as an integer with the scalerr
function.
Remarks
The user may assign any number in the range 065535 to denote particular error
conditions. This number may be tested for as an error code by scalerr.
The scalerr function will return the value of the error code and so is the reverse of
error. These user-generated error codes work in the same way as the intrinsic GAUSS
error codes which are generated automatically when trap 1 is on and certain GAUSS
functions detect a numerical error such as a singular matrix.
error(0) is equal to the missing value code.
Example
proc syminv(x);
local oldtrap,y;
if not x == x;
retp(error(99));
endif;
oldtrap = trapchk(0xffff);
trap 1;
y = invpd(x);
if scalerr(y);
y = inv(x);
endif;
trap oldtrap,0xffff;
retp(y);
endp;
The procedure syminv returns error code 99 if the matrix is not symmetric. If invpd
fails, it returns error code 20. If inv fails, it returns error code 50. The original trap
state is restored before the procedure returns.
See also
scalerr, trap, trapchk
519
errorlog 25. COMMAND REFERENCE
Purpose
Prints an error message to the screen and error log le.
Format
errorlog str;
Input
str string, the error message to print.
Portability
Unix
errorlog prints to window 1 and the error log le.
OS/2, Windows
errorlog prints to the main GAUSS window and the error log le.
520
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE etdays
Purpose
Computes the dierence between two times, as generated by the date command, in
days.
Format
days = etdays(tstart,tend);
Input
tstart 31 or 41 vector, starting date, in the order: yr, mo, day. (Only the rst
3 elements are used.)
tend 31 or 41 vector, ending date, in the order: yr, mo, day. (Only the rst
3 elements are used.) MUST be later than tstart.
Output
days scalar, elapsed time measured in days.
Remarks
This will work correctly across leap years and centuries. The assumptions are a
Gregorian calendar with leap years on the years evenly divisible by 4 and not evenly
divisible by 400.
Example
let date1 = 1986 1 2;
let date2 = 1987 10 25;
d = etdays(date1,date2);
d = 661
Source
time.src
Globals
daypryr, dayinyr
521
ethsec 25. COMMAND REFERENCE
Purpose
Computes the dierence between two times, as generated by the date command, in
hundredths of a second.
Format
hs = ethsec(tstart,tend);
Input
tstart 41 vector, starting date, in the order: yr, mo, day, hundredths of a
second.
tend 41 vector, ending date, in the order: yr, mo, day, hundredths of a second.
MUST be later date than tstart.
Output
hs scalar, elapsed time measured in hundredths of a second.
Remarks
This will work correctly across leap years and centuries. The assumptions are a
Gregorian calendar with leap years on the years evenly divisible by 4 and not evenly
divisible by 400.
Example
let date1 = 1986 1 2 0;
let date2 = 1987 10 25 0;
t = ethsec(date1,date2);
t = 5711040000
Source
time.src
Globals
daypryr, dayinyr
522
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE etstr
Purpose
Formats an elapsed time measured in hundredths of a second to a string.
Format
str = etstr(tothsecs);
Input
tothsecs scalar, an elapsed time measured in hundredths of a second, as given, for
instance, by the ethsec function.
Output
str string containing the elapsed time in the form:
# days # hours # minutes #.## seconds
Example
d1 = { 86, 1, 2, 0 };
d2 = { 86, 2, 5, 815642 };
t = ethsec(d1,d2);
str = etstr(t);
t = 2.9457564e +08
str = 34 days 2 hours 15 minutes 56.42 seconds
Source
time.src
Globals
None
523
exctsmpl 25. COMMAND REFERENCE
Purpose
Computes a random subsample of a data set.
Format
n = exctsmpl(inle,outle,percent );
Input
inle string, the name of the original data set.
outle string, the name of the data set to be created.
percent scalar, the percentage random sample to take. This must be in the range
0100.
Output
n scalar, number of rows in output data set.
Error returns are controlled by the low bit of the trap ag:
trap 0 terminate with error message
trap 1 return scalar negative integer
1 cant open input le
2 cant open output le
3 disk full
Remarks
Random sampling is done with replacement. Thus, an observation may be in the
resulting sample more than once. If percent is 100, the resulting sample will not be
identical to the original sample, though it will be the same size.
Example
n = exctsmpl("freq.dat","rout",30);
n = 30
freq.dat is an example data set provided with GAUSS. Switching to the GAUSS
examples directory will make it possible to do the above example as shown. Otherwise
substitute data set names will need to be used.
Source
exctsmpl.src
Globals
None
524
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE exec
Purpose
Executes an executable program and returns the exit code to GAUSS.
Format
y = exec(program,comline);
Portability
Unix
All I/O goes to GAUSSs controlling terminal.
Windows
The le can be given an extension or a . meaning no extension. Otherwise the le
will be searched for with the following extensions in their given order: .com, .exe,
.bat, .cmd.
OS/2
exec works the same as in Windows, except that the only default extension is .exe.
DOS
You must use the full name of the executable, including the extension.
This uses MS-DOS functions 4B and 4D. The child process can return an exit code
when it returns if it terminates with the MS-DOS function 4C. See the DOS Technical
Reference manual for detailed information on these functions.
Input
program string, the name of the program to be executed.
comline string, the arguments to be placed on the command line of the program
being executed.
Output
y the exit code returned by program.
If exec cant execute program, the error returns will be negative.
1 le not found
2 the le is not an executable le
525
exec 25. COMMAND REFERENCE
3 not enough memory
4 command line too long
Remarks
On some platforms the exit code is truncated to a 2-byte signed integer and only the
lower 8 bits will be returned. Therefore a 1 will be returned as 255. The operating
system may also set the lower 2 bits of the high byte of the returned word.
Example
y = exec("atog","comd1.cmd");
if y;
errorlog "atog failed";
end;
endif;
In this example the atog ASCII conversion utility is executed under the exec function.
The name of the command le to be used, comd1.cmd, is passed to atog on its
command line. The exit code y returned by exec is tested to see if atog was successful;
if not, the program will be terminated after printing an error message.
526
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE exp
Purpose
Calculates the exponential function.
Format
y = exp(x);
Input
x NK matrix.
Output
y NK matrix containing e, the base of natural logs, raised to the powers
given by the elements of x.
Example
x = eye(3);
y = exp(x);
x =
1.000000 0.000000 0.000000
0.000000 1.000000 0.000000
0.000000 0.000000 1.000000
y =
2.718282 1.000000 1.000000
1.000000 2.718282 1.000000
1.000000 1.000000 2.718282
This example creates a 33 identity matrix and computes the exponential function for
each one of its elements. Note that exp(1) returns e, the base of natural logs.
See also
ln
527
external 25. COMMAND REFERENCE
Purpose
To let the compiler know about symbols that are referenced above or in a separate le
from their denitions.
Format
external proc dog,cat ;
external keyword dog;
external fn dog;
external matrix x,y,z;
external string mstr,cstr;
Remarks
See Chapter 9.
You may have several procedures in dierent les that reference the same global
variable. By placing an external statement at the top of each le, you can let the
compiler know if the symbol is a matrix, string or procedure. If the symbol is listed and
strongly typed in an active library, no external statement is needed.
If a matrix or string appears in an external statement it needs to appear once in a
declare statement. If no declaration is found, an Undened symbol error will result.
Example
The real general eigenvalue procedure, eigrg, sets a global variable eigerr if it cannot
compute all of the eigenvalues.
external matrix _eigerr;
x = rndn(4,4);
xi = inv(x);
xev = eigrg(x);
if _eigerr;
print "Eigenvalues not computed";
end;
endif;
Without the external statement, the compiler would assume that eigerr was a
procedure and incorrectly compile this program. The le containing the eigrg
procedure also contains an external statement that denes eigerr as a matrix, but
this would not be encountered until the if statement containing the reference to eigerr
in the main program le had already been incorrectly compiled.
See also
declare
528
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

E
25. COMMAND REFERENCE eye
Purpose
Creates an identity matrix.
Format
y = eye(n);
Input
n scalar, size of identity matrix to be created.
Output
y NN identity matrix.
Remarks
If n is not an integer, it will be truncated to an integer.
The matrix created will contain 1s down the diagonal and 0s everywhere else.
Example
x = eye(3);
x =
1.000000 0.000000 0.000000
0.000000 1.000000 0.000000
0.000000 0.000000 1.000000
See also
zeros, ones
529
fcheckerr 25. COMMAND REFERENCE
Purpose
Gets the error status of a le.
Format
err = fcheckerr(f );
Input
f scalar, le handle of a le opened with fopen.
Output
err scalar, error status.
Remarks
If there has been a read or write error on a le, fcheckerr returns 1, otherwise 0.
If you pass fcheckerr the handle of a le opened with open (i.e., a data set or matrix
le), your program will terminate with a fatal error.
530
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fclearerr
Purpose
Gets the error status of a le, then clears it.
Format
err = fclearerr(f );
Input
f scalar, le handle of a le opened with fopen.
Output
err scalar, error status.
Remarks
Each le has an error ag that gets set when there is an I/O error on the le.
Typically, once this ag is set, you can no longer do I/O on the le, even if the error is
a recoverable one. fclearerr clears the les error ag, so you can attempt to continue
using it.
If there has been a read or write error on a le, fclearerr returns 1, otherwise 0.
If you pass fclearerr the handle of a le opened with open (i.e., a data set or matrix
le), your program will terminate with a fatal error.
The ag accessed by fclearerr is not the same as that accessed by fstrerror.
531
feqfne 25. COMMAND REFERENCE
Purpose
Fuzzy comparison functions. These functions use fcmptol to fuzz the comparison
operations to allow for roundo error.
Format
y = feq(a,b);
y = fge(a,b);
y = fgt(a,b);
y = e(a,b);
y = t(a,b);
y = fne(a,b);
Input
a NK matrix, rst matrix.
b LM matrix, second matrix, EE compatible with a.
fcmptol global scalar, comparison tolerance. The default value is 1.0e 15.
Output
y scalar, 1 (true) or 0 (false).
Remarks
The return value is true if every comparison is true.
The statement:
y = feq(a,b);
is equivalent to:
y = a eq b;
The calling program can reset fcmptol before calling these procedures.
_fcmptol = 1e-12;
532
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE feqfne
Example
x = rndu(2,2);
y = rndu(2,2);
t = fge(x,y);
x =
0.038289504 0.072535275
0.014713947 0.96863611
y =
0.25622293 0.70636474
0.0036191244 0.35913385
t = 0.0000000
Source
fcompare.src
Globals
fcmptol
See also
dotfeq
533
ush 25. COMMAND REFERENCE
Purpose
Flushes a les output buer.
Format
ret = ush(f );
Input
f scalar, le handle of a le opened with fopen.
Output
ret scalar, 0 if successful, -1 if not.
Remarks
If ush fails, you can call fstrerror to nd out why.
If you pass ush the handle of a le opened with open (i.e., a data set or matrix le),
your program will terminate with a fatal error.
534
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE t
Purpose
Computes a 1- or 2-D Fast Fourier transform.
Format
y = t(x);
Input
x NK matrix.
Output
y LM matrix, where L and M are the smallest powers of 2 greater than or
equal to N and K, respectively.
Remarks
This computes the FFT of x, scaled by 1/N.
This uses a Temperton Fast Fourier algorithm.
If N or K is not a power of 2, x will be padded out with zeros before computing the
transform.
Example
x = { 22 24,
23 25 };
y = fft(x);
y =
23.500000 1.0000000
0.5000000 0.00000000
See also
ti, rt, rti
535
ti 25. COMMAND REFERENCE
Purpose
Computes an inverse 1- or 2-D Fast Fourier transform.
Format
y = ti(x);
Input
x NK matrix.
Output
y LM matrix, where L and M are the smallest prime factor products
greater than or equal to N and K, respectively.
Remarks
Computes the inverse FFT of x, scaled by 1/N.
This uses a Temperton prime factor Fast Fourier algorithm.
Example
x = { 22 24,
23 25 };
y = fft(x);
y =
23.500000 1.0000000
0.5000000 0.00000000
fi = ffti(y);
fi =
22.000000 24.000000
23.000000 25.000000
See also
t, rt, rti
536
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE tm
Purpose
Computes a multi-dimensional FFT.
Format
y = tm(x,dim);
Input
x M1 vector, data.
dim K1 vector, size of each dimension.
Output
y L1 vector, FFT of x.
Remarks
The multi-dimensional data are laid out in a recursive or heirarchical fashion in the
vector x. That is to say, the elements of any given dimension are stored in sequence left
to right within the vector, with each element containing a sequence of elements of the
next smaller dimension. In abstract terms, a 4-dimensional 2x2x2x2 hypercubic x
would consist of two cubes in sequence, each cube containing two matrices in sequence,
each matrix containing two rows in sequence, and each row containing two columns in
sequence. Visually, x would look something like this:
X
hyper
= X
cube1
[ X
cube2
X
cube1
= X
mat1
[ X
mat2
X
mat1
= X
row1
[ X
row2
X
row1
= X
col1
[ X
col2
Or, in an extended GAUSS notation, x would be:
Xhyper = x[1,.,.,.] | x[2,.,.,.];
Xcube1 = x[1,1,.,.] | x[1,2,.,.];
Xmat1 = x[1,1,1,.] | x[1,1,2,.];
Xrow1 = x[1,1,1,1] | x[1,1,1,2];
To be explicit, x would be laid out like this:
x[1,1,1,1] x[1,1,1,2] x[1,1,2,1] x[1,1,2,2]
x[1,2,1,1] x[1,2,1,2] x[1,2,2,1] x[1,2,2,2]
x[2,1,1,1] x[2,1,1,2] x[2,1,2,1] x[2,1,2,2]
x[2,2,1,1] x[2,2,1,2] x[2,2,2,1] x[2,2,2,2]
537
tm 25. COMMAND REFERENCE
Constructing multi-dimensional matrices in vector format is actually quite simple. If
you look at the last diagram for the layout of x youll notice that each line actually
constitutes the elements of an ordinary matrix in normal row-major order. This is easy
to achieve with vecr. Further, each pair of lines or matrices constitutes one of the
desired cubes, again with all the elements in the correct order. And nally, the two
cubes combine to form the hypercube. So, the process of construction is simply a
sequence of concatenations of column vectors, with a vecr step if necessary to get
started.
Heres an example, this time working with a 2x3x2x3 hypercube.
let dim = 2 3 2 3;
let x1[2,3] = 1 2 3 4 5 6;
let x2[2,3] = 6 5 4 3 2 1;
let x3[2,3] = 1 2 3 5 7 11;
xc1 = vecr(x1)|vecr(x2)|vecr(x3); /* cube 1 */
let x1 = 1 1 2 3 5 8;
let x2 = 1 2 6 24 120 720;
let x3 = 13 17 19 23 29 31;
xc2 = x1|x2|x3; /* cube 2 */
xh = xc1|xc2; /* hypercube */
xhfft = fftm(xh,dim);
let dimi = 2 4 2 4;
xhffti = fftmi(xhfft,dimi);
I left out the vecr step for the 2
nd
cube. Its not really necessary when youre
constructing the matrices with let statements.
dim contains the dimensions of x, beginning with the highest dimension. The last
element of dim is the number of columns, the next to the last element of dim is the
number of rows, and so on. Thus
dim = { 2, 3, 3 };
indicates that the data in x is a 2x3x3 three-dimensional array, i.e., two 3x3 matrices of
data. Suppose that x1 is the rst 3x3 matrix and x2 the second 3x3 matrix, then x =
vecr(x1) | vecr(x2).
The size of dim tells you how many dimensions x has.
The arrays have to be padded in each dimension to the nearest power of two. Thus the
output array can be larger than the input array. In the 2x3x2x3 hypercube example, x
would be padded from 2x3x2x3 out to 2x4x2x4. The input vector would contain 36
elements, while the output vector would contain 64 elements. You may have noticed
that we used a dimi with padded values at the end of the example to check our answer.
538
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE tmi
Purpose
Computes a multi-dimensional inverse FFT.
Format
y = tmi(x,dim);
Input
x M1 vector, data.
dim K1 vector, size of each dimension.
Output
y L1 vector, inverse FFT of x.
Remarks
The multi-dimensional data are laid out in a recursive or heirarchical fashion in the
vector x. That is to say, the elements of any given dimension are stored in sequence left
to right within the vector, with each element containing a sequence of elements of the
next smaller dimension. In abstract terms, a 4-dimensional 2x2x2x2 hypercubic x
would consist of two cubes in sequence, each cube containing two matrices in sequence,
each matrix containing two rows in sequence, and each row containing two columns in
sequence. Visually, x would look something like this:
X
hyper
= X
cube1
[ X
cube2
X
cube1
= X
mat1
[ X
mat2
X
mat1
= X
row1
[ X
row2
X
row1
= X
col1
[ X
col2
Or, in an extended GAUSS notation, x would be:
Xhyper = x[1,.,.,.] | x[2,.,.,.];
Xcube1 = x[1,1,.,.] | x[1,2,.,.];
Xmat1 = x[1,1,1,.] | x[1,1,2,.];
Xrow1 = x[1,1,1,1] | x[1,1,1,2];
To be explicit, x would be laid out like this:
x[1,1,1,1] x[1,1,1,2] x[1,1,2,1] x[1,1,2,2]
x[1,2,1,1] x[1,2,1,2] x[1,2,2,1] x[1,2,2,2]
x[2,1,1,1] x[2,1,1,2] x[2,1,2,1] x[2,1,2,2]
x[2,2,1,1] x[2,2,1,2] x[2,2,2,1] x[2,2,2,2]
539
tmi 25. COMMAND REFERENCE
Constructing multi-dimensional matrices in vector format is actually quite simple. If
you look at the last diagram for the layout of x youll notice that each line actually
constitutes the elements of an ordinary matrix in normal row-major order. This is easy
to achieve with vecr. Further, each pair of lines or matrices constitutes one of the
desired cubes, again with all the elements in the correct order. And nally, the two
cubes combine to form the hypercube. So, the process of construction is simply a
sequence of concatenations of column vectors, with a vecr step if necessary to get
started.
Heres an example, this time working with a 2x3x2x3 hypercube.
let dim = 2 3 2 3;
let x1[2,3] = 1 2 3 4 5 6;
let x2[2,3] = 6 5 4 3 2 1;
let x3[2,3] = 1 2 3 5 7 11;
xc1 = vecr(x1)|vecr(x2)|vecr(x3); /* cube 1 */
let x1 = 1 1 2 3 5 8;
let x2 = 1 2 6 24 120 720;
let x3 = 13 17 19 23 29 31;
xc2 = x1|x2|x3; /* cube 2 */
xh = xc1|xc2; /* hypercube */
xhffti = fftmi(xh,dim);
I left out the vecr step for the 2
nd
cube. Its not really necessary when youre
constructing the matrices with let statements.
dim contains the dimensions of x, beginning with the highest dimension. The last
element of dim is the number of columns, the next to the last element of dim is the
number of rows, and so on. Thus
dim = { 2, 3, 3 };
indicates that the data in x is a 2x3x3 three-dimensional array, i.e., two 3x3 matrices of
data. Suppose that x1 is the rst 3x3 matrix and x2 the second 3x3 matrix, then x =
vecr(x1) | vecr(x2).
The size of dim tells you how many dimensions x has.
The arrays have to be padded in each dimension to the nearest power of two. Thus the
output array can be larger than the input array. In the 2x3x2x3 hypercube example, x
would be padded from 2x3x2x3 out to 2x4x2x4. The input vector would contain 36
elements, while the output vector would contain 64 elements.
540
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE tn
Purpose
Computes a complex 1- or 2-D FFT.
Format
y = tn(x);
Input
x NK matrix.
Output
y LM matrix, where L and M are the smallest prime factor products
greater than or equal to N and K, respectively.
Remarks
tn uses the Temperton prime factor FFT algorithm. This algorithm can compute the
FFT of any vector or matrix whose dimensions can be expressed as the product of
selected prime number factors. GAUSS implements the Temperton algorithm for any
power of 2, 3, and 5, and one factor of 7. Thus, tn can handle any matrix whose
dimensions can be expressed as
2
p
3
q
5
r
7
s
, p, q, r nonnegative integers
s = 0 or 1
If a dimension of x does not meet this requirement, it will be padded with zeros to the
next allowable size before the FFT is computed.
tn pads matrices to the next allowable dimensions; however, it generally runs faster
for matrices whose dimensions are highly composite numbers, i.e., products of several
factors (to various powers), rather than powers of a single factor. For example, even
though it is bigger, a 33600x1 vector can compute as much as 20% faster than a
32768x1 vector, because 33600 is a highly composite number, 2
6
3 5
2
7, whereas
32768 is a simple power of 2, 2
15
. For this reason, you may want to hand-pad matrices
to optimum dimensions before passing them to tn. The Run-Time Library includes a
routine, optn, for determining optimum dimensions.
The Run-Time Library also includes the nextn routine, for determining allowable
dimensions for a matrix. (You can use this to see the dimensions to which tn would
pad a matrix.)
tn scales the computed FFT by 1/(L*M).
See also
t, ti, tm, tmi, rt, rti, rtip, rtn, rtnp, rtp
541
fgets 25. COMMAND REFERENCE
Purpose
Reads a line of text from a le.
Format
str = fgets(f ,maxsize);
Input
f scalar, le handle of a le opened with fopen.
maxsize scalar, maximum size of string to read in, including the terminating null
byte.
Output
str string.
Remarks
fgets reads text from a le into a string. It reads up to a newline, the end of the le, or
maxsize-1 characters. The result is placed in str, which is then terminated with a null
byte. The newline, if present, is retained.
If the le is already at end-of-le when you call fgets, your program will terminate with
an error. Use eof in conjunction with fgets to avoid this.
If the le was opened for update (see fopen) and you are switching from writing to
reading, dont forget to call fseek or ush rst, to ush the les buer.
If you pass fgets the handle of a le opened with open (i.e., a data set or matrix le),
your program will terminate with a fatal error.
542
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fgetsa
Purpose
Reads lines of text from a le into a string array.
Format
sa = fgetsa(f ,numl );
Input
f scalar, le handle of a le opened with fopen.
numl scalar, number of lines to read.
Output
sa N1 string array, N <= numl .
Remarks
fgetsa reads up to numl lines of text. If fgetsa reaches the end of the le before reading
numl lines, sa will be shortened. Lines are read in the same manner as fgets, except
that no limit is placed on the size of a line. Thus, fgetsa always returns complete lines
of text. Newlines are retained. If numl is 1, fgetsa returns a string. (This is one way to
read a line from a le without placing a limit on the length of the line.)
If the le is already at end-of-le when you call fgetsa, your program will terminate
with an error. Use eof in conjunction with fgetsa to avoid this. If the le was opened
for update (see fopen) and you are switching from writing to reading, dont forget to
call fseek or ush rst, to ush the les buer.
If you pass fgetsa the handle of a le opened with open (i.e., a data set or matrix le),
your program will terminate with a fatal error.
543
fgetsat 25. COMMAND REFERENCE
Purpose
Reads lines of text from a le into a string array.
Format
sa = fgetsat(f ,numl );
Input
f scalar, le handle of a le opened with fopen.
numl scalar, number of lines to read.
Output
sa N1 string array, N <= numl .
Remarks
fgetsat operates identically to fgetsa, except that newlines are not retained as text is
read into sa.
In general, you dont want to use fgetsat on les opened in binary mode (see fopen).
fgetsat drops the newlines, but it does NOT drop the carriage returns that precede
them on some platforms. Printing out such a string array can produce unexpected
results.
544
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fgetst
Purpose
Reads a line of text from a le.
Format
str = fgetst(f ,maxsize);
Input
f scalar, le handle of a le opened with fopen.
maxsize scalar, maximum size of string to read in, including the null terminating
byte.
Output
str string.
Remarks
fgetst operates identically to fgets, except that the newline is not retained in the string.
In general, you dont want to use fgetst on les opened in binary mode (see fopen).
fgetst drops the newline, but it does NOT drop the preceding carriage return used on
some platforms. Printing out such a string can produce unexpected results.
545
leinfo 25. COMMAND REFERENCE
Purpose
Returns names and information for les that match a specication.
Format
{ fnames,nfo } = leinfo(fspec);
Input
fspec string, le specication. Can include path. Wildcards are allowed in the
lename.
Output
fnames N1 string array of all lenames that match, null string if none are found.
nfo N13 matrix, information about matching les.
Unix
[N, 1] lesystem ID
[N, 2] inode number
[N, 3] mode bit mask
[N, 4] number of links
[N, 5] user ID
[N, 6] group ID
[N, 7] device ID (char/block special les only)
[N, 8] size in bytes
[N, 9] last access time
[N,10] last data modication time
[N,11] last le status change time
[N,12] preferred I/O block size
[N,13] number of 512-byte blocks allocated
546
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE leinfo
OS/2, Windows
[N, 1] drive number (A = 0, B = 1, etc.)
[N, 2] n/a, 0
[N, 3] mode bit mask
[N, 4] number of links, always 1
[N, 5] n/a, 0
[N, 6] n/a, 0
[N, 7] n/a, 0
[N, 8] size in bytes
[N, 9] last access time
[N,10] last data modication time
[N,11] creation time
[N,12] n/a, 0
[N,13] n/a, 0
DOS
[N, 1] drive number (A = 0, B = 1, etc.)
[N, 2] n/a, 0
[N, 3] mode bit mask
[N, 4] number of links, always 1
[N, 5] n/a, 0
[N, 6] n/a, 0
[N, 7] n/a, 0
[N, 8] size in bytes
[N, 9] n/a, 0
[N,10] last data modication time
[N,11] n/a, 0
[N,12] n/a, 0
[N,13] n/a, 0
nfo will be a scalar zero if no matches are found.
Remarks
fnames will contain le names only; any path information that was passed is dropped.
The time stamp elds (finfo[N, 9][N, 11]) are expressed as the number of seconds
since midnight, Jan. 1, 1970, Coordinated Universal Time (UTC).
See also
les, lesa
547
les 25. COMMAND REFERENCE
Purpose
Returns a matrix of matching le names.
Format
y = les(n,a);
Input
n string containing any combination of drive, path, and lename to search
for. Wildcards are allowed in the lename.
a scalar, the attribute to use in the search.
Output
y N2 matrix of all lenames that match, or scalar 0 if none are found.
Portability
Unix, OS/2, Windows
les was written to work under DOS, with its 8x3 lenames; use leinfo or lesa
instead.
Remarks
The le names will be in the rst column of the returned matrix. The drive and path
that was passed is dropped, and the extensions, including the period ., will be in the
second column. For les with no extension the second column entry will be null.
Volume labels look like lenames and have a period before the 9
th
character.
The attribute corresponds to the le attribute for each entry in the disk directory. For
normal les an attribute of 0 is used. This will return the names of all matching
normal les. The bits in the attribute byte have the following meaning:
2 Hidden les
4 System les
8 Volume Label (DOS only)
16 Subdirectory
The values above are added together to specify dierent types of les to be searched
for. Therefore 6 would specify hidden+system.
If the attribute is set for hidden, system, or subdirectory entries then it will be an
inclusive search. All normal entries plus all entries matching the specied attributes
will be returned.
If the attribute is set for the volume label, it will be an exclusive search and only the
volume label will be returned.
Example
548
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE les
y = files("ch*.*",0);
In this example all normal les listed in the current directory that begin with ch will
be returned.
y = files("ch*.",0);
In this example all normal les listed in the current directory that begin with ch but
do not have an extension will be returned.
y = files("ch*.*",2+4+16);
In this example all normal, hidden, and system les and all subdirectories listed in the
current directory that begin with ch will be returned.
proc exist(filename);
retp(not files(filename,0) $== 0);
endp;
This procedure will return 1 if the le exists or 0 if not.
See also
dos, leinfo, lesa
549
lesa 25. COMMAND REFERENCE
Purpose
Returns a string array of le names.
Format
y = lesa(n);
Input
n string, le specication to search for. Can include path. Wildcards are
allowed in the lename.
Output
y N1 string array of all lenames that match, or null string if none are
found.
Remarks
y will contain le names only; any path information that was passed is dropped.
Example
y = filesa("ch*");
In this example all les listed in the current directory that begin with ch will be
returned.
proc exist(filename);
retp(not filesa(filename) $== "");
endp;
This procedure will return 1 if the le exists or 0 if not.
See also
dos, leinfo, les
550
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE oor
Purpose
Round down toward .
Format
y = oor(x);
Input
x NK matrix.
Output
y NK matrix containing the elements of x rounded down.
Remarks
This rounds every element in the matrix x down to the nearest integer.
Example
x = 100*rndn(2,2);
x =
77.68 14.10
4.73 158.88
f = floor(x);
f =
77.00 15.00
4.00 159.00
See also
ceil, round, trunc
551
fmod 25. COMMAND REFERENCE
Purpose
Computes the oating-point remainder of x/y.
Format
r = fmod(x,y);
Input
x NK matrix.
y LM matrix, EE conformable with x.
Output
r max(N,L) by max(K,M) matrix.
Remarks
Returns the oating-point remainder r of x/y such that x = iy +r, where i is an
integer, r has the same sign as x and [r[ < [y[.
Compare this with %, the modulo division operator, in Chapter 8.
Example
x = seqa(1.7,2.3,5);
y = 2;
r = fmod(x,y);
x = 1.7 4 6.3 8.6 10.9
r = 1.7 0 0.3 0.6 0.9
552
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fn
Purpose
Allows user to create one-line functions.
Format
fn fn name(args) = code for function;
Example
fn area(r) = pi*r*r;
a = area(4);
Remarks
Functions can be called in the same way as other procedures.
553
fopen 25. COMMAND REFERENCE
Purpose
Opens a le.
Format
f = fopen(lename,omode);
Input
lename string, name of le to open.
omode string, le I/O mode.
Output
f scalar, le handle.
Portability
Unix
Carriage return-linefeed conversion for les opened in text mode is unnecessary,
because in Unix a newline is simply a linefeed.
Remarks
lename can contain a path specication.
omode is a sequence of characters that specify the mode in which to open the le. The
rst character must be one of:
r Open an existing le for reading. If the le does not exist, fopen fails.
w Open or create a le for writing. If the le already exists, its current
contents will be destroyed.
a Open or create a le for appending. All output is appended to the end of
the le.
To this can be appended a + and/or a b. The + indicates the le is to opened for
reading and writing, or update, as follows:
r+ Open an existing le for update. You can read from or write to any
location in the le. If the le does not exist, fopen fails.
554
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fopen
w+ Open or create a le for update. You can read from or write to any location
in the le. If the le already exists, its current contents will be destroyed.
a+ Open or create a le for update. You can read from any location in the
le, but all output will be appended to the end of the le.
Finally, the b indicates whether the le is to be opened in text or binary mode. If the
le is opened in binary mode, the contents of the le are read verbatim; likewise,
anything output to the le is written verbatim. In text mode (the default), carriage
return-linefeed sequences are converted on input to linefeeds, or newlines. Likewise on
output, newlines are converted to carriage return-linefeeds. Also in text mode, if a
Ctrl-Z (char 26) is encountered during a read, it is interpreted as an end-of-le
character, and reading ceases. In binary mode, Ctrl-Z is read in uninterpreted.
The order of + and b is not signicant; rb+ and r+b mean the same thing.
You can both read from and write to a le opened for update. However, before
switching from one to the other, you must make an fseek or ush call, to ush the
les buer.
If fopen fails, it returns a 0.
Use close and closeall to close les opened with fopen.
555
for 25. COMMAND REFERENCE
Purpose
Begins a for loop.
Format
for i (start , stop, step);
.
.
.
endfor;
Input
i literal, the name of the counter variable.
start scalar expression, the initial value of the counter.
stop scalar expression, the nal value of the counter.
step scalar expression, the increment value.
Remarks
The counter is strictly local to the loop. It is created with an implicit #dene. The
expressions, start , stop and step are evaluated only once when the loop initializes.
They are converted to integers and stored local to the loop.
The for loop is optimized for speed and much faster than a do loop.
The commands break and continue are supported. The continue command steps the
counter and jumps to the top of the loop. The break command terminates the current
loop.
When the loop terminates, the value of the counter is stop if the loop terminated
naturally. If break is used to terminate the loop and you want the nal value of the
counter you need to assign it to a variable before the break statement. See the third
example below.
Example
x = zeros(10, 5);
for i (1, rows(x), 1);
for j (1, cols(x), 1);
x[i,j] = i*j;
endfor;
556
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE for
endfor;
x = rndn(3,3);
y = rndn(3,3);
for i (1, rows(x), 1);
for j (1, cols(x), 1);
if x[i,j] >= y[i,j];
continue;
endif;
temp = x[i,j];
x[i,j] = y[i,j];
y[i,j] = temp;
endfor;
endfor;
li = 0;
x = rndn(100,1);
y = rndn(100,1);
for i (1, rows(x), 1);
if x[i] /= y[i];
li = i;
break;
endif;
endfor;
if li;
print "Compare failed on row " li;
endif;
557
format 25. COMMAND REFERENCE
Purpose
Controls the format of matrices and numbers printed out with print or lprint
statements.
Format
format [[/typ]] [[/fmted]] [[/mf ]] [[/jnt]] [[f,p]]; ;
Input
/typ literal, symbol type ag(s). Indicate which symbol types you are setting
the output format for.
/mat, /sa, /str Formatting parameters are maintained separately for
matrices (/mat), string arrays (/sa), and strings (/str). You can
specify more than one /typ ag; the format will be set for all types
indicated. If no /typ ag is listed, format assumes /mat.
/fmted literal, enable formatting ag.
/on, /o Enable/disable formatting. When formatting is disabled, the
contents of a variable are dumped to the screen in a raw format.
/o is currently supported only for strings. Raw format for
strings means that the entire string is printed, starting at the
current cursor position. When formatting is enabled for strings,
they are handled the same as string arrays. This shouldnt be too
surprising, since a string is actually a 1x1 string array.
/mf literal, matrix row format ag.
/m0 no delimiters before or after rows when printing out matrices.
/m1 or /mb1 print 1 carriage return/line feed pair before each row of a
matrix with more than 1 row.
/m2 or /mb2 print 2 carriage return/line feed pairs before each row of a
matrix with more than 1 row.
/m3 or /mb3 print Row 1, Row 2... before each row of a matrix
with more than one row.
/ma1 print 1 carriage return/line feed pair after each row of a matrix
with more than 1 row.
/ma2 print 2 carriage return/line feed pairs after each row of a matrix
with more than 1 row.
/a1 print 1 carriage return/line feed pair after each row of a matrix.
/a2 print 2 carriage return/line feed pairs after each row of a matrix.
558
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE format
/b1 print 1 carriage return/line feed pair before each row of a matrix.
/b2 print 2 carriage return/line feed pairs before each row of a matrix.
/b3 print Row 1, Row 2... before each row of a matrix.
/jnt literal, matrix element format ag controls justication, notation and
trailing character.
Right-Justied
/rd Signed decimal number in the form [[-]]####.####, where #### is
one or more decimal digits. The number of digits before the
decimal point depends on the magnitude of the number, and the
number of digits after the decimal point depends on the precision.
If the precision is 0, no decimal point will be printed.
/re Signed number in the form [[-]]#.##E###, where # is one decimal
digit, ## is one or more decimal digits depending on the precision,
and ### is three decimal digits. If precision is 0, the form will be
[[-]]#E### with no decimal point printed.
/ro This will give a format like /rd or /re depending on which is most
compact for the number being printed. A format like /re will be
used only if the exponent value is less than -4 or greater than the
precision. If a /re format is used, a decimal point will always
appear. The precision signies the number of signicant digits
displayed.
/rz This will give a format like /rd or /re depending on which is most
compact for the number being printed. A format like /re will be
used only if the exponent value is less than -4 or greater than the
precision. If a /re format is used, trailing zeros will be supressed
and a decimal point will appear only if one or more digits follow it.
The precision signies the number of signicant digits displayed.
Left-Justied
/ld Signed decimal number in the form [[-]]####.####, where #### is
one or more decimal digits. The number of digits before the
decimal point depends on the magnitude of the number, and the
number of digits after the decimal point depends on the precision.
If the precision is 0, no decimal point will be printed. If the number
is positive, a space character will replace the leading minus sign.
/le Signed number in the form [[-]]#.##E###, where # is one decimal
digit, ## is one or more decimal digits depending on the precision,
and ### is three decimal digits. If precision is 0, the form will be
[[-]]#E### with no decimal point printed. If the number is
positive, a space character will replace the leading minus sign.
/lo This will give a format like /ld or /le depending on which is most
compact for the number being printed. A format like /le will be
559
format 25. COMMAND REFERENCE
used only if the exponent value is less than -4 or greater than the
precision. If a /le format is used, a decimal point will always
appear. If the number is positive, a space character will replace the
leading minus sign. The precision species the number of
signicant digits displayed.
/lz This will give a format like /ld or /le depending on which is most
compact for the number being printed. A format like /le will be
used only if the exponent value is less than -4 or greater than the
precision. If a /le format is used, trailing zeros will be supressed
and a decimal point will appear only if one or more digits follow it.
If the number is positive, a space character will replace the leading
minus sign. The precision species the number of signicant digits
displayed.
Trailing Character
The following characters can be added to the /jnt parameters
above to control the trailing character if any:
format /rdn 1,3;
s The number will be followed immediately by a space character.
This is the default.
c The number will be followed immediately with a comma.
t The number will be followed immediately with a tab character.
n No trailing character.
f scalar expression, controls the eld width.
p scalar expression, controls the precision.
Portability
Unix, OS/2, Windows
format sets the print statement format for the active window. Each window
remembers its own format, even when it is no longer the active window.
Remarks
For numeric values in matrices, p sets the number of signicant digits to be printed.
For string arrays, strings, and character elements in matrices, p sets the number of
characters to be printed. If a string is shorter than the specied precision, the entire
string is printed. For string arrays and strings, p = -1 means print the entire string,
regardless of its length. p = -1 is illegal for matrices; setting p >= 8 means the same
thing for character elements.
The /xxx slash parameters are optional. Field and precision are optional also but if one
is included, then both have to be included.
560
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE format
Slash parameters, if present, must precede the eld and precision parameters.
A format statement stays in eect until it is overridden by a new format statement.
The slash parameters may be used in a print statement to override the current default.
f and p may be any legal expressions that return scalars. Nonintegers will be truncated
to integers.
The total width of eld will be overridden if the number is too big to t into the space
allotted. For instance, format /rds 1,0 can be used to print integers with a single space
between them, regardless of the magnitudes of the integers.
Complex numbers are printed with the sign of the imaginary half separating them and
an i appended to the imaginary half. Also, the eld parameter refers to the width of
eld for each half of the number, so a complex number printed with a eld of 8 will
actually take (at least) 20 spaces to print. The character printed after the imaginary
part can be changed (for example, to a j) with the sysstate function, case 9.
The default when GAUSS is rst started is:
format /mb1 /ros 16,8;
Example
x = rndn(3,3);
format /m1 /rd 16,8;
print x;
-1.63533465 1.61350700 -1.06295179
0.26171282 0.27972294 -1.38937242
0.58891114 0.46812202 1.08805960
format /m1 /rzs 1,10;
print x;
-1.635334648 1.613507002 -1.062951787
0.2617128159 0.2797229414 -1.389372421
0.5889111366 0.4681220206 1.088059602
format /m3 /rdn 16,4;
print x;
Row 1
-1.6353 1.6135 -1.0630
Row 2
561
format 25. COMMAND REFERENCE
0.2617 0.2797 -1.3894
Row 3
0.5889 0.4681 1.0881
format /m1 /ldn 16,4;
print x;
-1.6353 1.6135 -1.0630
0.2617 0.2797 -1.3894
0.5889 0.4681 1.0881
format /m1 /res 12,4;
print x;
-1.6353E+000 1.6135E+000 -1.0630E+000
2.6171E-001 2.7972E-001 -1.3894E+000
5.8891E-001 4.6812E-001 1.0881E+000
See also
formatcv, formatnv, print, lprint, output
562
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE formatcv
Purpose
Sets the character data format used by printfmt.
Format
oldfmt = formatcv(newfmt );
Input
newfmt 13 vector, the new format specication.
Output
oldfmt 13 vector, the old format specication.
Remarks
See printfm for details on the format vector.
Example
x = { A 1, B 2, C 3 };
oldfmt = formatcv("*.*s" ~ 3 ~ 3);
call printfmt(x,0~1);
call formatcv(oldfmt);
Source
gauss.src
Globals
fmtcv
See also
formatnv, printfm, printfmt
563
formatnv 25. COMMAND REFERENCE
Purpose
Sets the numeric data format used by printfmt.
Format
oldfmt = formatnv(newfmt );
Input
newfmt 13 vector, the new format specication.
Output
oldfmt 13 vector, the old format specication.
Remarks
See printfm for details on the format vector.
Example
x = { A 1, B 2, C 3 };
oldfmt = formatnv("*.*lf" ~ 8 ~ 4);
call printfmt(x,0~1);
call formatnv(oldfmt);
Source
gauss.src
Globals
fmtnv
See also
formatcv, printfm, printfmt
564
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fputs
Purpose
Writes strings to a le.
Format
numl = fputs(f ,sa);
Input
f scalar, le handle of a le opened with fopen.
sa string or string array.
Output
numl scalar, the number of lines written to the le.
Portability
Unix
Carriage return-linefeed conversion for les opened in text mode is unnecessary,
because in Unix a newline is simply a linefeed.
Remarks
fputs writes the contents of each string in sa, minus the null terminating byte, to the
le specied. If the le was opened in text mode (see fopen), any newlines present in
the strings are converted to carriage return-linefeed sequences on output. If numl is not
equal to the number of elements in sa, there may have been an I/O error while writing
the le. You can use fcheckerr or fclearerr to check this. If there was an error, you can
call fstrerror to nd out what it was. If the le was opened for update (see fopen) and
you are switching from reading to writing, dont forget to call fseek or ush rst, to
ush the les buer. If you pass fputs the handle of a le opened with open (i.e., a
data set or matrix le), your program will terminate with a fatal error.
565
fputst 25. COMMAND REFERENCE
Purpose
Writes strings to a le.
Format
numl = fputst (f ,sa);
Input
f scalar, le handle of a le opened with fopen.
sa string or string array.
Output
numl scalar, the number of lines written to the le.
Portability
Unix
Carriage return-linefeed conversion for les opened in text mode is unnecessary,
because in Unix a newline is simply a linefeed.
Remarks
fputst works identically to fputs, except that a newline is appended to each string that
is written to the le. If the le was opened in text mode (see fopen), these newlines are
also converted to carriage return-linefeed sequences on output.
566
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fseek
Purpose
Positions the le pointer in a le.
Format
ret = fseek(f ,os,base);
Input
f scalar, le handle of a le opened with fopen.
os scalar, oset (in bytes).
base scalar, base position.
0 beginning of le.
1 current position of le pointer.
2 end of le.
Output
ret scalar, 0 is successful, 1 if not.
Portability
Unix
Carriage return-linefeed conversion for les opened in text mode is unnecessary,
because in Unix a newline is simply a linefeed.
Remarks
fseek moves the le pointer os bytes from the specied base position. os can be
positive or negative. The call may fail if the le buer needs to be ushed (see ush).
If fseek fails, you can call fstrerror to nd out why.
For les opened for update (see fopen), the next operation can be a read or a write.
fseek is not reliable when used on les opened in text mode (see fopen). This has to do
with the conversion of carriage return-linefeed sequences to newlines. In particular, an
fseek that follows one of the fgetxxx or fputxxx commands may not produce the
expected result. For example:
567
fseek 25. COMMAND REFERENCE
p = ftell(f);
s = fgetsa(f,7);
call fseek(f,p,0);
is not reliable. We have found that the best results are obtained by fseeking to the
beginning of the le and then fseeking to the desired location, as in:
p = ftell(f);
s = fgetsa(f,7);
call fseek(f,0,0);
call fseek(f,p,0);
If you pass fseek the handle of a le opened with open (i.e., a data set or matrix le),
your program will terminate with a fatal error.
568
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE fstrerror
Purpose
Returns an error message explaining the cause of the most recent le I/O error.
Format
s = fstrerror;
Output
s string, error message.
Remarks
Any time an I/O error occurs on a le opened with fopen, an internal error ag is
updated. (This ag, unlike those accessed by fcheckerr and fclearerr, is not specic to
a given le; rather, it is system-wide.) fstrerror returns an error message based on the
value of this ag, clearing it in the process. If no error has occurred, a null string is
returned.
Since fstrerror clears the error ag, if you call it twice in a row, it will always return a
null string the second time.
569
ftell 25. COMMAND REFERENCE
Purpose
Gets the position of the le pointer in a le.
Format
pos = ftell(f );
Input
f scalar, le handle of a le opened with fopen.
Output
pos scalar, current position of the le pointer in a le.
Remarks
ftell returns the position of the le pointer in terms of bytes from the beginning of the
le. The call may fail if the le buer needs to be ushed (see ush).
If an error occurs, ftell returns -1. You can call fstrerror to nd out what the error was.
If you pass ftell the handle of a le opened with open (i.e., a data set or matrix le),
your program will terminate with a fatal error.
570
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE ftocv
Purpose
Converts a matrix containing oating point numbers into a matrix containing the
decimal character representation of each element.
Format
y = ftocv(x,eld,prec);
Input
x NK matrix containing numeric data to be converted.
eld scalar, minimum eld width.
prec scalar, the numbers created will have prec places after the decimal point.
Output
y NK matrix containing the decimal character equivalent of the
corresponding elements in x in the format dened by eld and prec.
Remarks
If a number is narrower than eld, it will be padded on the left with zeros.
If prec = 0, the decimal point will be suppressed.
Example
y = seqa(6,1,5);
x = 0 $+ "cat" $+ ftocv(y,2,0);
x =
cat06
cat07
cat08
cat09
cat10
Notice that the ( 0 $+ ) above was necessary to force the type of the result to
MATRIX because the string constant cat would be of type STRING. The left
operand in an expression containing a $+ operator controls the type of the result.
See also
ftos
571
ftos 25. COMMAND REFERENCE
Purpose
Converts a scalar into a string containing the decimal character representation of that
number.
Format
y = ftos(x,fmat,eld,prec);
Input
x scalar, the number to be converted.
fmat string, the format string to control the conversion.
eld scalar or 21 vector, the minimum eld width. If eld is 21, it species
separate eld widths for the real and imaginary parts of x.
prec scalar or 21 vector, the number of places following the decimal point. If
prec is 21, it species separate precisions for the real and imaginary parts
of x.
Output
y string containing the decimal character equivalent of x in the format
specied.
Remarks
The format string corresponds to the format /jnt (justication, notation, trailing
character) slash parameter as follows:
/rdn %*.*lf
/ren %*.*lE
/ron %#*.*lG
/rzn %*.*lG
/ldn %- *.*lf
/len %- *.*lE
/lon %-# *.*lG
/lzn %- *.*lG
If x is complex, you can specify separate formats for the real and imaginary parts by
putting two format specications in the format string. You can also specify separate
elds and precisions. You can position the sign of the imaginary part by placing a +
between the two format specications. If you use two formats, no i is appended to
the imaginary part. This is so you can use an alternate format if you prefer, for
example, prefacing the imaginary part with a j.
The format string can be a maximum of 80 characters.
If you want special characters to be printed after x, include them as the last characters
of the format string. For example:
572
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

F
25. COMMAND REFERENCE ftos
%*.*lf, right-justied decimal followed by a comma.
%-*.*s left-justied string followed by a space.
%*.*lf right-justied decimal followed by nothing.
You can embed the format specication in the middle of other text.
Time: %*.*lf seconds.
If you want the beginning of the eld padded with zeros, then put a 0 before the rst
* in the format string:
%0*.*lf right-justied decimal.
If prec = 0, the decimal point will be suppressed.
Example
You can create custom formats for complex numbers with ftos. For example,
let c = 24.56124+6.3224e-2i;
field = 1;
prec = 3|5;
fmat = "%lf + j%le is a complex number.";
cc = ftos(c,fmat,field,prec);
results in
cc = "24.561 + j6.32240e-02 is a complex number."
Some other things you can do with ftos:
let x = 929.857435324123;
let y = 5.46;
let z = 5;
field = 1;
prec = 0;
fmat = "%*.*lf";
zz = ftos(z,fmat,field,prec);
field = 1;
prec = 10;
fmat = "%*.*lE";
573
ftos 25. COMMAND REFERENCE
xx = ftos(x,fmat,field,prec);
field = 7;
prec = 2;
fmat = "%*.*lf seconds";
s1 = ftos(x,fmat,field,prec);
s2 = ftos(y,fmat,field,prec);
field = 1;
prec = 2;
fmat = "The maximum resistance is %*.*lf ohms.";
om = ftos(x,fmat,field,prec);
The results:
zz = "5"
xx = "9.2985743532E+02"
s1 = " 929.86 seconds"
s2 = " 5.46 seconds"
om = "The maximum resistance is 929.86 ohms."
See also
ftocv, stof, format
574
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE gamma
Purpose
Returns the value of the gamma function.
Format
y = gamma(x);
Input
x NK matrix.
Output
y NK matrix.
Remarks
For each element of x this function returns the integral


0
t
(x1)
e
t
dt
All elements of x must be positive and less than or equal to 169. Values of x greater
than 169 will cause an overow.
The natural log of gamma is often what is required and it can be computed without
the overow problems of gamma. lnfact can be used to compute log gamma.
Example
y = gamma(2.5);
y = 1.32934
See also
cdfchic, cdfbeta, cdc, cdfn, cdfnc, cdftc, erf, erfc
575
gammaii 25. COMMAND REFERENCE
Purpose
Compute the inverse incomplete gamma function.
Format
x = gammaii(a,p);
Input
a MN matrix, exponents.
p KL matrix, EE conformable with a, incomplete gamma values.
Output
x max(M,K) by max(N,L) matrix, abscissae.
Source
cdfchii.src
Globals
ginvinc, macheps
576
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE gausset
Purpose
Resets the global control variables declared in gauss.dec.
Format
gausset;
Source
gauss.src
Globals
altnam, con, , fmtcv, fmtnv, header, miss, output,
row, rowfac, sort, title, tol, vpad, vtype, weight
577
getf 25. COMMAND REFERENCE
Purpose
Loads an ASCII or binary le into a string.
Format
y = getf(lename,mode);
Input
lename string, any valid le name.
mode scalar 1 or 0 which determines if the le is to be loaded in ASCII mode (0)
or binary mode (1).
Output
y string containing the le, up to 65519 bytes long.
Remarks
If the le is loaded in ASCII mode, it will be tested to see if it contains any end of le
characters. These are Z (ASCII 26). The le will be truncated before the rst Z and
there will be no Zs in the string. This is the correct way to load most text les
because the Zs can cause problems when trying to print the string to a printer.
If the le is loaded in binary mode, it will be loaded just like it is with no changes.
Example
Create a le examp.e containing the following program.
library pgraph;
graphset;
x = seqa(0,0.1,100);
y = sin(x);
xy(x,y);
Then execute the following.
y = getf("examp.e",0);
print y;
library pgraph;
graphset;
x = seqa(0,0.1,100);
y = sin(x);
xy(x,y);
See also
load, save, let, con
578
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE getname
Purpose
Returns a column vector containing the names of the variables in a GAUSS data set.
Format
y = getname(dset );
Input
dset string specifying the name of the data set from which the function will
obtain the variable names.
Output
y N1 vector containing the names of all of the variables in the specied
data set.
Remarks
The output, y, will have as many rows as there are variables in the data set.
Example
y = getname("olsdat");
format 8,8;
print $y;
TIME
DIST
TEMP
FRICT
The above example assumes the data set olsdat contained the variables: TIME, DIST,
TEMP, FRICT.
NOTE that the extension is not included in the lename passed to the getname
function.
See also
getnamef, indcv
579
getnamef 25. COMMAND REFERENCE
Purpose
Returns a string array containing the names of the variables in a GAUSS data set.
Format
y = getnamef(f );
Input
f scalar, le handle of an open data set
Output
y N1 string array containing the names of all of the variables in the
specied data set.
Remarks
The output, y, will have as many rows as there are variables in the data set.
Example
open f = olsdat for read;
y = getnamef(f);
t = vartypef(f);
print y;
time
dist
temp
frict
The above example assumes the data set olsdat contained the variables: time, dist,
temp, frict. Note the use of vartypef to determine the types of these variables.
See also
getname, indcv, vartypef
580
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE getnr
Purpose
Compute number of rows to read per iteration for a program that reads data from a
disk le in a loop.
Format
nr = getnr(nsets,ncols);
Input
nsets scalar, estimate of the maximum number of duplicate copies of the data
matrix read by readr to be kept in memory during each iteration of the
loop.
ncols scalar, columns in the data le.
Output
nr scalar, number of rows readr should read per iteration of the read loop.
Remarks
If row is greater than 0, nr will be set to row.
If an insucient memory error is encountered, change rowfac to a number less than
1.0 (e.g., 0.75). The number of rows read will be reduced in size by this factor.
Source
gauss.src
Globals
row, rowfac, maxvec
581
getpath 25. COMMAND REFERENCE
Purpose
Returns an expanded lename including the drive and path.
Format
fname = getpath(pfname);
Input
pfname string, partial lename with only partial or missing path information.
Output
fname string, lename with full drive and path.
Remarks
This function handles relative path references.
Example
y = getpath("temp.e");
print y;
/gauss/temp.e
Source
getpath.src
Globals
None
582
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE gosub
Purpose
Causes a branch to a subroutine.
Format
gosub label ;
.
.
.
label:
.
.
.
return;
Remarks
See Chapter 9 for multi-line recursive user-dened functions.
When a gosub statement is encountered the program will branch to the label and begin
executing from there. When a return statement is encountered, the program will
resume executing at the statement following the gosub statement. Labels are 1-32
characters long and are followed by a colon. The characters can be A-Z or 0-9 and they
must begin with an alphabetic character. Uppercase or lowercase is allowed.
It is possible to pass parameters to subroutines and receive parameters from them when
they return. See the second example below.
The only legal way to enter a subroutine is with a gosub statement.
If your subroutines are at the end of your program, you should have an end statement
before the rst one to prevent the program from running into a subroutine without
using a gosub. This will result in a return without gosub error message.
The variables used in subroutines are not local to the subroutine and can be accessed
from other places in your program. See Chapter 9.
Example
In the program below the name mysub is a label. When the gosub statement is
executed, the program will jump to the label mysub and continue executing from there.
When the return statement is executed, the program will resume executing at the
statement following the gosub.
x = rndn(3,3); z = 0;
583
gosub 25. COMMAND REFERENCE
gosub mysub;
print z;
end;
/* ------ Subroutines Follow ------ */
mysub:
z = inv(x);
return;
Parameters can be passed to subroutines in the following way (line numbers are added
for clarity):
1. gosub mysub(x,y);
2. pop j; /* b will be in j */
3. pop k; /* a will be in k */
4. t = j*k;
5. print t;
6. end;
7.
8. /* ---- Subroutines Follow ----- */
9.
10. mysub:
11. pop b; /* y will be in b */
12. pop a; /* x will be in a */
13.
14. a = inv(b)*b+a;
15. b = ab;
16. return(a,b);
In the above example, when the gosub statement is executed, the following sequence of
events results:
1. x and y are pushed on the stack and the program branches to the label
mysub in line 10.
11. the second argument that was pushed, y, is popped into b.
12. the rst argument that was pushed, x, is popped into a.
14. inv(b)*b+a is assigned to a.
15. a

b is assigned to b.
16. a and b are pushed on the stack and the program branches to the
statement following the gosub, which is line 2.
584
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE gosub
2. the second argument that was pushed, b, is popped into j.
3. the rst argument that was pushed, a, is popped into k.
4. j*k is assigned to t.
5. t is printed.
6. the program is terminated with the end statement.
Matrices are pushed on a last-in/rst-out stack in the gosub() and return() statements.
They must be popped o in the reverse order. No intervening statements are allowed
between the label and the pop or the gosub and the pop. Only one matrix may be
popped per pop statement.
See also
goto, proc, pop, return
585
goto 25. COMMAND REFERENCE
Purpose
Causes a branch to a label.
Format
goto label ;
.
.
.
label:
Remarks
Label names can be any legal GAUSS names up to 32 alphanumeric characters,
beginning with an alphabetic character or an underscore, not a reserved word.
Labels are always followed immediately by a colon.
Labels do not have to be declared before they are used. GAUSS knows they are labels
by the fact that they are followed immediately by a colon.
When GAUSS encounters a goto statement, it jumps to the specied label and
continues execution of the program from there.
Parameters can be passed in a goto statement the same way as they can with a gosub.
Example
x = seqa(.1,.1,5);
n = { 1 2 3 };
goto fip;
print x;
end;
fip:
print n;
1.0000000 2.0000000 3.0000000
See also
gosub, if
586
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE gradp
Purpose
Computes the gradient vector or matrix (Jacobian) of a vector-valued function that has
been dened in a procedure. Single-sided (forward dierence) gradients are computed.
Format
g = gradp(&f ,x0);
Input
&f a pointer to a vector-valued function (f :K1 > N1) dened as a
procedure. It is acceptable for f(x) to have been dened in terms of global
arguments in addition to x, and thus f can return an N1 vector:
proc f(x);
retp( exp(x.*b) );
endp;
x0 K1 vector of points at which to compute gradient.
Output
g NK matrix containing the gradients of f with respect to the variable x at
x0.
Remarks
gradp will return a row for every row that is returned by f . For instance, if f returns a
scalar result, then gradp will return a 1K row vector. This allows the same function
to be used regardless of N, where N is the number of rows in the result returned by f .
Thus, for instance, gradp can be used to compute the Jacobian matrix of a set of
equations.
Example
proc myfunc(x);
retp( x.*2 .* exp( x.*x./3 ) );
endp;
x0 = 2.5|3.0|3.5;
y = gradp(&myfunc,x0);
587
gradp 25. COMMAND REFERENCE
y =
82.98901842 0.00000000 0.00000000
0.00000000 281.19752975 0.00000000
0.00000000 0.00000000 1087.95414117
It is a 33 matrix because we are passing it 3 arguments and myfunc returns 3 results
when we do that; the o-diagonals are zeros because the cross-derivatives of 3
arguments are 0.
Source
gradp.src
Globals
None
See also
hessp
588
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

G
25. COMMAND REFERENCE graph
Purpose
Graphs a set of points, taking the horizontal coordinates of the points from one matrix
and the vertical coordinates from the other.
Format
graph x,y;
Input
x NK matrix of horizontal coordinates.
y LM matrix, vertical coordinates, EE conformable with x.
Remarks
This command matches up the x and y values in the standard element-by-element
fashion and sets the appropriate pixels.
The origin 0,0 is at the lower lefthand corner of the screen.
Note that the screen must be in graphics mode for this command to operate. See
setvmode.
Example
x = seqa(0,1,640);
y = 50~100~150;
call setvmode(17);
graph x,y;
wait;
The program above will draw three horizontal lines across the screen, one at y = 50,
one at y = 100, and one at y = 150.
When GAUSS returns to COMMAND level, the screen will be reset automatically to
text mode because the editor requires the screen in text mode. Your program should
contain a pause to allow viewing the graph or printing with the DOS graphics screen
dump.
See also
setvmode, color, plot
589
hasimag 25. COMMAND REFERENCE
Purpose
Tests whether the imaginary part of a complex matrix is negligible.
Format
y = hasimag(x);
Input
x NK matrix.
Output
y scalar, 1 if the imaginary part of x has any nonzero elements, 0 if it
consists entirely of 0s.
The function iscplx tests whether x is a complex matrix or not, but it does not test the
contents of the imaginary part of x. hasimag tests the contents of the imaginary part
of x to see if it is zero.
hasimag actually tests the imaginary part of x against a tolerance to determine if it is
negligible. The tolerance used is the imaginary tolerance set with the sysstate
command, case 21.
Some functions are not dened for complex matrices. iscplx can be used to determine
whether a matrix has no imaginary part and so can pass through those functions.
hasimag can be used to determine whether a complex matrix has a negligible imaginary
part and could thus be converted to a real matrix to pass through those functions.
iscplx is useful as a preliminary check because for large matrices it is much faster than
hasimag.
Example
x = { 1 2 3i,
4-i 5 6i,
7 8i 9 };
y = hasimag(x);
y = 1.0000000
See also
iscplx
590
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

H
25. COMMAND REFERENCE header
Purpose
Print a header for a report.
Format
header(prcnm,dataset ,ver);
Input
prcnm string, name of procedure that calls header.
dataset string, name of data set.
ver 21 numeric vector, the rst element is the major version number of the
program, the second element is the revision number. Normally this
argument will be the version/revision global ( ?? ver) associated with the
module within which header is called. This argument will be ignored if set
to 0.
Global Input
header string, containing the letters:
t title is to be printed
l lines are to bracket the title
d a date and time is to be printed
v version number of program is printed
f le name being analyzed is printed
title string, title for header.
Source
gauss.src
Globals
header, title
591
hess 25. COMMAND REFERENCE
Purpose
Computes the Hessenberg form of a square matrix.
Format
{ h,z } = hess(x);
Input
x KK matrix.
Output
h KK matrix, Hessenberg form.
z KK matrix, transformation matrix.
Remarks
hess computes the Hessenberg form of a square matrix. The Hessenberg form is an
intermediate step in computing eigenvalues. It also is useful for solving certain matrix
equations that occur in control theory (see Charles F. Van Loan, Using the
Hessenberg Decomposition in Control Theory, in Algorithms and Theory in Filtering
and Control, D.C. Sorenson and R.J. Wets (eds), Mathematical Programming Study
No. 18, North Holland, Amsterdam, pp. 102-111, 1982).
z is an orthogonal matrix that transforms x into h and vice versa. Thus:
h = z

xz
and since z is orthogonal,
x = zhz

x is reduced to upper Hessenberg form using orthogonal similiarity transformations.


This preserves the Frobenious norm of the matrix and the condition numbers of the
eigenvalues.
hess uses the ORTRAN and ORTHES functions from EISPACK.
592
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

H
25. COMMAND REFERENCE hess
Example
let x[3,3] = 1 2 3
4 5 6
7 8 9;
{ h,z } = hess(x);
h =
1.00000000 3.59700730 0.24806947
8.06225775 14.04615385 2.83076923
0.00000000 0.83076923 0.04615385
z =
1.00000000 0.00000000 0.00000000
0.00000000 0.49613894 0.86824314
0.00000000 0.86824314 0.49613894
See also
schur
593
hessp 25. COMMAND REFERENCE
Purpose
Computes the matrix of second partial derivatives (Hessian matrix) of a function
dened as a procedure.
Format
h = hessp(&f ,x0);
Input
&f pointer to a single-valued function f(x), dened as a procedure, taking a
single K1 vector argument (f :K1 > 11); f(x) may be dened in
terms of global arguments in addition to x.
x0 K1 vector specifying the point at which the Hessian of f(x) is to be
computed.
Output
h KK matrix of second derivatives of f with respect to x at x0; this matrix
will be symmetric.
Remarks
This procedure requires K*(K+1)/2 function evaluations. Thus if K is large, it may
take a long time to compute the Hessian matrix.
No more than 3-4 digit accuracy should be expected from this function, though it is
possible for greater accuracy to be achieved with some functions.
It is important that the function be properly scaled, in order to obtain greatest possible
accuracy. Specically, scale it so that the rst derivatives are approximately the same
size. If these derivatives dier by more than a factor of 100 or so, the results can be
meaningless.
Example
x = { 1, 2, 3 };
proc g(b);
retp( exp(xb) );
endp;
b0 = { 3, 2, 1 };
h = hessp(&g,b0);
594
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

H
25. COMMAND REFERENCE hessp
The resulting matrix of second partial derivatives of g(b) evaluated at b=b0 is:
22027.12898372 44054.87238165 66083.36762901
44054.87238165 88111.11102645 132168.66742899
66083.36762901 132168.66742899 198256.04087836
Source
hessp.src
Globals
None
See also
gradp
595
hsec 25. COMMAND REFERENCE
Purpose
Returns the number of hundredths of a second since midnight.
Format
y = hsec;
Remarks
The number of hundredths of a second since midnight can also be accessed as the [4,1]
element of the vector returned by the date function.
Example
x = rndu(100,100);
ts = hsec;
y = x*x;
et = hsec-ts;
In this example, hsec is used to time a 100100 multiplication in GAUSS. A 100100
matrix, x, is created, and the current time, in hundredths of a second since midnight, is
stored in the variable ts. Then the multiplication is carried out. Finally, ts is
subtracted from hsec to give the time dierence which is assigned to et.
See also
date, time, timestr, ethsec, etstr
596
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE if
Purpose
Controls program ow with conditional branching.
Format
if scalar expression;
list of statements;
elseif scalar expression;
list of statements;
elseif scalar expression;
list of statements;
else;
list of statements;
endif;
Remarks
scalar expression is any expression that returns a scalar. It is TRUE if it is not zero,
and FALSE if it is zero.
A list of statements is any set of GAUSS statements.
GAUSS will test the expression after the if statement. If it is TRUE (nonzero), then
the rst list of statements is executed. If it is FALSE (zero), then GAUSS will move to
the expression after the rst elseif statement if there is one and test it. It will keep
testing expressions and will execute the rst list of statements that corresponds to a
TRUE expression. If no expression is TRUE, then the list of statements following the
else statement is executed. After the appropriate list of statements is executed, the
program will go to the statement following the endif and continue on.
if statements can be nested.
One endif is required per if statement. If an else statement is used, there may be only
one per if statement. There may be as many elseifs as are required. There need not be
any elseifs or any else statement within an if statement.
Note the semicolon after the else statement.
597
if 25. COMMAND REFERENCE
Example
if x < 0;
y = -1;
elseif x > 0;
y = 1;
else;
y = 0;
endif;
See also
do
598
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE imag
Purpose
Returns the imaginary part of a matrix.
Format
zi = imag(x);
Input
x NK matrix.
Output
zi NK matrix, the imaginary part of x.
Remarks
If x is real, zi will be an NK matrix of zeros.
Example
x = { 4i 9 3,
2 5-6i 7i };
y = imag(x);
y =
4.0000000 0.0000000 0.0000000
0.0000000 6.0000000 7.0000000
See also
complex, real
599
#include 25. COMMAND REFERENCE
Purpose
Inserts code from another le into a GAUSS program.
Format
#include lename;
#include lename;
Remarks
lename can be any legitimate le name.
This command makes it possible to write a section of general-purpose code, and insert
it into other programs.
The code from the #included le is inserted literally as if it were merged into that
place in the program with a text editor.
If a complete drive and pathname is specied for the le, then no additional searching
will be attempted if the le is not found.
If a complete drive and pathname is not specied and a src path conguration variable
is dened in the GAUSS conguration le, then each path listed in src path will be
searched for the specied lename. Any drive or path on the user-specied lename will
be stripped o prior to being combined with the paths found in src path.
#include /gauss/myprog.prc; No additional search will be made if the le is not
found.
#include myprog.prc; The paths listed in src path will be searched for myprog.prc
if the le is not found.
The src path conguration variable can be dened in the GAUSS conguration le by
editing the le with any text editor.
Compile time errors will return the line number and the name of the le in which they
occur. For execution time errors, if a program is compiled with #lineson, the line
number and name of the le where the error occurred will be printed. For les that
have been #included this reects the actual line number within the #included le.
See #lineson for a more complete discussion of the use of and the validity of line
numbers when debugging.
Example
#include "/gauss/inc/cond.inc";
The command will cause the code in the program cond.inc to be merged into the
current program at the point at which this statement appears.
See also
run, #lineson
600
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE indcv
Purpose
Checks one character vector against another and returns the indices of the elements of
the rst vector in the second vector.
Format
z = indcv(what ,where);
Input
what N1 character vector which contains the elements to be found in vector
where.
where M1 character vector to be searched for matches to the elements of what .
Output
z N1 vector of integers containing the indices of the corresponding element
of what in where.
Remarks
If no matches are found for any of the elements in what , then the corresponding
elements in the returned vector are set to the GAUSS missing value code.
Both arguments will be forced to uppercase before the comparison.
If there are duplicate elements in where, the index of the rst match will be returned.
Example
let what = AGE PAY SEX;
let where = AGE SEX JOB date PAY;
z = indcv(what,where);
what =
AGE
PAY
SEX
where =
AGE
SEX
JOB
date
PAY
z =
1
5
2
601
indexcat 25. COMMAND REFERENCE
Purpose
Returns the indices of the elements of a vector which fall into a specied category
Format
y = indexcat(x,v);
Input
x N1 vector.
v scalar or 21 vector.
If scalar, the function returns the indices of all elements of x equal to v.
If 21, then the function returns the indices of all elements of x that fall
into the range:
v[1] < x v[2].
If v is scalar, it can contain a single missing to specify the missing value as
the category.
Output
y L1 vector, containing the indices of the elements of x which fall into the
category dened by v. It will contain error code 13 if there are no elements
in this category.
Remarks
Use a loop to pull out indices of multiple categories.
Example
let x = 1.0 4.0 3.3 4.2 6.0 5.7 8.1 5.5;
let v = 4 6;
y = indexcat(x,v);
x =
1.0
4.0
3.3
4.2
6.0
5.7
8.1
5.5
v =
4
6
y =
4
5
6
8
602
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE indices
Purpose
Processes a set of variable names or indices and returns a vector of variable names and
a vector of indices.
Format
{ name,indx } = indices(dataset ,vars);
Input
dataset string, the name of the data set.
vars N1 vector, a character vector of names or a numeric vector of column
indices.
If scalar 0, all variables in the data set will be selected.
Output
name N1 character vector, the names associated with vars.
indx N1 numeric vector, the column indices associated with vars.
Remarks
If an error occurs, indices will either return a scalar error code or terminate the
program with an error message, depending on the trap state. If the low order bit of the
trap ag is 0, indices will terminate with an error message. If the low order bit of the
trap ag is 1, indices will return an error code. The value of the trap ag can be tested
with trapchk; the return from indices can be tested with scalerr. You only need to
check one argument; they will both be the same. The following error codes are possible:
1 Cant open dataset.
2 Index of variable out of range, or
undened data set variables.
Source
indices.src
Globals
None
603
indices2 25. COMMAND REFERENCE
Purpose
Processes two sets of variable names or indices from a single le. The rst is a single
variable and the second is a set of variables. The rst must not occur in the second set
and all must be in the le.
Format
{ name1,indx1,name2,indx2 } = indices2(dataset ,var1,var2);
Input
dataset string, the name of the data set.
var1 string or scalar, variable name or index.
This can be either the name of the variable, or the column index of the
variable.
If null or 0, the last variable in the data set will be used.
var2 N1 vector, a character vector of names or a numeric vector of column
indices.
If scalar 0, all variables in the data set except the one associated with var1
will be selected.
Output
name1 scalar character matrix containing the name of the variable associated with
var1.
indx1 scalar, the column index of var1.
name2 N1 character vector, the names associated with var2.
indx2 N1 numeric vector, the column indices of var2.
Remarks
If an error occurs, indices2 will either return a scalar error code or terminate the
program with an error message, depending on the trap state. If the low order bit of the
trap ag is 0, indices2 will terminate with an error message. If the low order bit of the
trap ag is 1, indices2 will return an error code. The value of the trap ag can be
tested with trapchk; the return from indices2 can be tested with scalerr. You only need
to check one argument; they will all be the same. The following error codes are possible:
604
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE indices2
1 Cant open dataset.
2 Index of variable out of range, or
undened data set variables.
3 First variable must be a single name or index.
4 First variable contained in second set.
Source
indices2.src
Globals
None
605
indnv 25. COMMAND REFERENCE
Purpose
Checks one numeric vector against another and returns the indices of the elements of
the rst vector in the second vector.
Format
z = indnv(what ,where);
Input
what N1 numeric vector which contains the values to be found in vector where.
where M1 numeric vector to be searched for matches to the values in what .
Output
z N1 vector of integers, the indices of the corresponding elements of what
in where.
Remarks
If no matches are found for any of the elements in what , then those elements in the
returned vector are set to the GAUSS missing value code.
If there are duplicate elements in where, the index of the rst match will be returned.
Example
let what = 8 7 3;
let where = 2 7 8 4 3;
z = indnv(what,where);
what =
8
7
3
where =
2
7
8
4
3
z =
3
2
5
606
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intgrat2
Purpose
Integrates the following double integral, using user-dened functions f, g
1
and g
2
and
scalars a and b:

b
a

g1(x)
g2(x)
f(x, y)dydx
Format
y = intgrat2(&f ,xl ,gl );
Input
&f scalar, pointer to the procedure containing the function to be integrated.
xl 21 or 2N matrix, the limits of x. These must be scalar limits.
gl 21 or 2N matrix of function pointers, the limits of y.
For xl and gl , the rst row is the upper limit and the second row is the
lower limit. N integrations are computed.
intord scalar, the order of the integration. The larger intord, the more precise
the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,
32, 40.
Default = 12.
intrec scalar. This variable is used to keep track of the level of recursion of
intgrat2 and may start out with a dierent value if your program
terminated inside of the integration function on a previous run. Always set
intrec explicitly to 0 before any call to intgrat2.
Output
y N1 vector of the estimated integral(s) of f(x, y) evaluated between the
limits given by xl and gl .
Remarks
The user-dened functions specied by f and gl must either
1. Return a scalar constant, OR
2. Return a vector of function values. intgrat2 will pass
to user-dened functions a vector or matrix for x and
y and expect a vector or matrix to be returned. Use .*
and ./ instead of * and /.
607
intgrat2 25. COMMAND REFERENCE
Example
proc f(x,y);
retp(cos(x) + 1).*(sin(y) + 1));
endp;
proc g1(x);
retp(sqrt(1-x^2));
endp;
proc g2(x);
retp(0);
endp;
xl = 1|-1;
gl = &g1|&g2;
_intord = 40;
_intrec = 0;
y = intgrat2(&f,xl,gl);
This will integrate the function f(x, y) = (cos(x) +1)(sin(y) +1) over the upper half of
the unit circle. Note the use of the .* operator instead of just * in the denition of
f(x, y). This allows f to return a vector or matrix of function values.
Source
intgrat.src
Globals
intgrat2, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,
intq4, intq40, intq6, intq8, intrec
See also
intgrat3, intquad1, intquad2, intquad3, intsimp
608
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intgrat3
Purpose
Integrates the following triple integral, using user-dened functions and scalars for
bounds:

b
a

g1(x)
g2(x)

h1(x,y)
h2(x,y)
f(x, y, z)dzdydx
Format
y = intgrat3(&f ,xl ,gl ,hl );
Input
&f scalar, pointer to the procedure containing the function to be integrated.
F is a function of (x, y, z).
xl 21 or 2N matrix, the limits of x. These must be scalar limits.
gl 21 or 2N matrix of function pointers. These procedures are functions of
x.
hl 21 or 2N matrix of function pointers. These procedures are functions of
x and y.
For xl , gl , and hl , the rst row is the upper limit and the second row is the lower limit.
N integrations are computed.
intord scalar, the order of the integration. The larger intord, the more precise
the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,
32, 40.
Default = 12.
intrec scalar. This variable is used to keep track of the level of recursion of
intgrat3 and may start out with a dierent value if your program
terminated inside of the integration function on a previous run. Always set
intrec explicitly to 0 before any call to intgrat3.
Output
y N1 vector of the estimated integral(s) of f(x, y, z) evaluated between the
limits given by xl , gl and hl .
Remarks
User-dened functions f, and those used in gl and hl must either:
609
intgrat3 25. COMMAND REFERENCE
1. Return a scalar constant, OR
2. Return a vector of function values. intgrat3 will pass
to user-dened functions a vector or matrix for x and
y and expect a vector or matrix to be returned. Use .*
and ./ operators instead of just * or /.
Example
proc f(x,y,z);
retp(2);
endp;
proc g1(x);
retp(sqrt(25-x^2));
endp;
proc g2(x);
retp(-g1(x));
endp;
proc h1(x,y);
retp(sqrt(25 - x^2 - y^2));
endp;
proc h2(x,y);
retp(-h1(x,y));
endp;
xl = 5|-5;
gl = &g1|&g2;
hl = &h1|&h2;
_intrec = 0;
_intord = 40;
y = intgrat3(&f,xl,gl,hl);
This will integrate the function f(x, y, z) = 2 over the sphere of radius 5. The result
will be approximately twice the volume of a sphere of radius 5.
Source
intgrat.src
Globals
intgrat3, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,
intq4, intq40, intq6, intq8, intrec
See also
intgrat2, intquad1, intquad2, intquad3, intsimp
610
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intquad1
Purpose
Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and
lower bounds may be calculated in one procedure call.
Format
y = intquad1(&f ,xl );
Input
&f scalar, pointer to the procedure containing the function to be integrated.
This must be a function of x.
xl 2N matrix, the limits of x.
The rst row is the upper limit and the second row is the lower limit. N
integrations are computed.
intord scalar, the order of the integration. The larger intord, the more precise
the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,
32, 40.
Default = 12.
Output
y N1 vector of the estimated integral(s) of f(x) evaluated between the
limits given by xl .
Remarks
The user-dened function f must return a vector of function values. intquad1 will pass
to the user-dened function a vector or matrix for x and expect a vector or matrix to
be returned. Use the .* and ./ instead of * and /.
Example
proc f(x);
retp(x.*sin(x));
endp;
xl = 1|0;
y = intquad1(&f,xl);
611
intquad1 25. COMMAND REFERENCE
This will integrate the function f(x) = xsin(x) between 0 and 1. Note the use of the .*
instead of *.
Source
integral.src
Globals
intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32, intq4,
intq40, intq6, intq8
See also
intsimp, intquad2, intquad3, intgrat2, intgrat3
612
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intquad2
Purpose
Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and
lower bounds may be calculated in one procedure call.
Format
y = intquad2(&f ,xl ,yl );
Input
&f scalar, pointer to the procedure containing the function to be integrated.
xl 21 or 2N matrix, the limits of x.
yl 21 or 2N matrix, the limits of y.
For xl and yl , the rst row is the upper limit and the second row is the
lower limit. N integrations are computed.
intord global scalar, the order of the integration. The larger intord, the more
precise the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16,
20, 24, 32, 40.
Default = 12.
intrec global scalar. This variable is used to keep track of the level of recursion of
intquad2 and may start out with a dierent value if your program
terminated inside of the integration function on a previous run. Always set
intrec explicitly to 0 before any calls to intquad2.
Output
y N1 vector of the estimated integral(s) of f(x,y) evaluated between the
limits given by xl and yl .
Remarks
The user-dened function f must return a vector of function values. intquad2 will pass
to user-dened functions a vector or matrix for x and y and expect a vector or matrix
to be returned. Use .* and ./ instead of * and /.
intquad2 will expand scalars to the appropriate size. This means that functions can be
dened to return a scalar constant. If users write their functions incorrectly (using *
instead of .*, for example), intquad2 may not compute the expected integral, but the
integral of a constant function.
To integrate over a region which is bounded by functions, rather than just scalars, use
intgrat2 or intgrat3.
Example
613
intquad2 25. COMMAND REFERENCE
proc f(x,y);
retp(x.*sin(x+y));
endp;
xl = 1|0;
yl = 1|0;
_intrec = 0;
y = intquad2(&f,xl,yl);
This will integrate the function x. sin(x +y) between x = 0 and 1, and between y = 0
and 1.
Source
integral.src
Globals
intquad2, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,
intq4, intq40, intq6, intq8, intrec
See also
intquad1, intquad3, intsimp, intgrat2, intgrat3
614
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intquad3
Purpose
Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and
lower bounds may be calculated in one procedure call.
Format
y = intquad3(&f ,xl ,yl ,zl );
Input
&f scalar, pointer to the procedure containing the function to be integrated. f
is a function of (x, y, z).
xl 21 or 2N matrix, the limits of x.
yl 21 or 2N matrix, the limits of y.
zl 21 or 2N matrix, the limits of z.
For xl , yl , and zl , the rst row is the upper limit and the second row is the
lower limit. N integrations are computed.
intord global scalar, the order of the integration. The larger intord, the more
precise the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16,
20, 24, 32, 40.
Default = 12.
intrec global scalar. This variable is used to keep track of the level of recursion of
intquad3 and may start out with a dierent value if your program
terminated inside of the integration function on a previous run. Always set
intrec explicitly to 0 before any calls to intquad3.
Output
y N1 vector of the estimated integral(s) of f(x,y,z) evaluated between the
limits given by xl , yl and zl .
Remarks
The user-dened function f must return a vector of function values. intquad3 will pass
to the user-dened function a vector or matrix for x, y and z and expect a vector or
matrix to be returned. Use .* and ./ instead of * and /.
intquad3 will expand scalars to the appropriate size. This means that functions can be
dened to return a scalar constant. If users write their functions incorrectly (using *
615
intquad3 25. COMMAND REFERENCE
instead of .*, for example), intquad3 may not compute the expected integral, but the
integral of a constant function.
To integrate over a region which is bounded by functions, rather than just scalars, use
intgrat2 or intgrat3.
Example
proc f(x,y,z);
retp(x.*y.*z);
endp;
xl = 1|0;
yl = 1|0;
zl = { 1 2 3, 0 0 0 };
_intrec = 0;
y = intquad3(&f,xl,yl,zl);
This will integrate the function f(x) = x y z over 3 sets of limits, since zl is dened
to be a 23 matrix.
Source
integral.src
Globals
intquad3, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,
intq4, intq40, intq6, intq8, intrec
See also
intquad1, intquad2, intsimp, intgrat2, intgrat3
616
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intrleav
Purpose
Interleaves the rows of two les that have been sorted on a common variable, to give a
single le sorted on that variable.
Format
intrleav(inle1,inle2,outle,keyvar,keytyp);
Input
inle1 string, name of input le 1.
inle2 string, name of input le 2.
outle string, name of output le.
keyvar string, name of key variable, this is the column the les are sorted on.
keytyp scalar, data type of key variable.
1 numeric key, ascending order
2 character key, ascending order
1 numeric key, descending order
2 character key, descending order
Remarks
The two les MUST have exactly the same variables, i.e., the same number of columns
AND the same variable names. They must both already be sorted on the key column.
This procedure will combine them into one large le, sorted by the key variable.
If the inputs are null or 0, the procedure will ask for them.
Example
intrleav("freq.dat","freqdata.dat","intfile","AGE",1);
Source
sortd.src
Globals
None
617
intrsect 25. COMMAND REFERENCE
Purpose
Returns the intersection of two vectors, with duplicates removed.
Format
y = intrsect(v1,v2,ag);
Input
v1 N1 vector.
v2 M1 vector.
ag scalar, if 1, v1 and v2 are numeric, if 0, character.
Output
y L1 vector containing all unique values that are in both v1 and v2, sorted
in ascending order.
Remarks
Place smaller vector rst for fastest operation.
If there are a lot of duplicates within a vector, it is faster to remove them with unique
before calling intrsect.
Source
intrsect.src
Globals
None
Example
let v1 = mary jane linda dawn;
let v2 = mary sally lisa ruth linda;
y = intrsect(v1,v2,0);
618
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE intsimp
Purpose
Integrates a specied function using Simpsons method with end correction. A single
integral is computed in one function call.
Format
y = intsimp(&f ,xl ,tol );
Input
&f pointer to the procedure containing the function to be integrated.
xl 21 vector, the limits of x.
The rst element is the upper limit and the second element is the lower
limit.
tol The tolerance to be used in testing for convergence.
Output
y The estimated integral of f(x) between xl[1] and xl[2] .
Remarks
Example
proc f(x);
retp(sin(x));
endp;
let xl = { 1,
0 };
y = intsimp(&f,xl,1E-8);
This will integrate the function between 0 and 1.
Source
intsimp.src
Globals
None
See also
intquad1, intquad2, intquad3, intgrat2, intgrat3
619
inv, invpd 25. COMMAND REFERENCE
Purpose
inv returns the inverse of an invertible matrix.
invpd returns the inverse of a symmetric, positive denite matrix.
Format
y = inv(x);
y = invpd(x);
Input
x NN matrix.
Output
y NN matrix containing the inverse of x.
Remarks
x can be any legitimate matrix expression that returns a matrix that is legal for the
function.
For inv, x must be square and invertible.
For invpd, x must be symmetric and positive denite.
If the input matrix is not invertible by these functions, they will either terminate the
program with an error message or return an error code which can be tested for with the
scalerr function. This depends on the trap state as follows:
trap 1, return error code
inv invpd
50 20
trap 0, terminate with error message
inv invpd
Matrix singular Matrix not positive denite
If the input to invpd is not symmetric, it is possible that the function will (erroneously)
appear to operate successfully.
Positive denite matrices can be inverted by inv. However, for symmetric, positive
denite matrices (such as moment matrices), invpd is about twice as fast as inv.
Example
620
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE inv, invpd
n = 4000;
x1 = rndn(n,1);
x = ones(n,1)~x1;
btrue = { 1, 0.5 };
y = x*btrue + rndn(n,1);
bols = invpd(xx)*xy;
bols = 1.017201 0.484244
This example simulates some data and computes the ols coecient estimator using the
invpd function. First, the number of observations is specied. Second, a vector x1 of
standard Normal random variables is generated and is concatenated with a vector of 1s
(to create a constant term). The true coecients are specied, and the dependent
variable y is created. Then the ols coecient estimates are computed.
Technical Notes
For complex matrices, inv uses the ZGECO, ZGEDI path in the LINPACK routines.
For real matrices, it uses the croutp function.
The inv function uses the Crout decomposition. The advantage of this routine is that
on some platforms it allows most of the intermediate results to be computed in
extended precision.
The invpd function uses the Cholesky decomposition and is based upon the LINPACK
routines for positive denite matrices. On OS/2 and DOS, if prcsn 80 is in eect, all
intermediate calculations and intermediate results will be in the 80-bit extended
precision of the 80x87 temporary real format. The nal results will be rounded to
64-bit double precision.
The tolerance used to determine singularity is 1.0e14. This can be changed. See
Appendix E.
See also
scalerr, trap, prcsn
621
invswp 25. COMMAND REFERENCE
Purpose
Computes a generalized sweep inverse.
Format
y = invswp(x);
Input
x NN matrix.
Output
y NN matrix, the generalized inverse of x.
Remarks
This will invert any general matrix. That is, even matrices which will not invert using
inv because they are singular will invert using invswp.
x and y will satisfy the four Moore-Penrose conditions:
1. xyx = x
2. yxy = y
3. xy is symmetric
4. yx is symmetric
The tolerance used to determine if a pivot element is zero is taken from the crout
singularity tolerance. The corresponding row and column are zeroed out. See Appendix
E.
Example
let x[3,3] = 1 2 3 4 5 6 7 8 9;
y = invswp(x);
y =
1.6666667 0.66666667 0.0000000
1.3333333 0.33333333 0.0000000
0.0000000 0.0000000 0.0000000
622
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE iscplx
Purpose
Returns whether a matrix is complex or real.
Format
y = iscplx(x);
Input
x NK matrix.
Output
y scalar, 1 if x is complex, 0 if it is real.
Example
x = { 1, 2i, 3 };
y = iscplx(x);
y = 1.0000000
See also
hasimag, iscplxf
623
iscplxf 25. COMMAND REFERENCE
Purpose
Returns whether a data set is complex or real.
Format
y = iscplxf(fh);
Input
fh scalar, le handle of an open le.
Output
y scalar, 1 if the data set is complex, 0 if it is real.
See also
hasimag, iscplx
624
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

I
25. COMMAND REFERENCE ismiss
Purpose
Returns a 1 if its matrix argument contains any missing values, otherwise returns a 0.
Format
y = ismiss(x);
Input
x NK matrix.
Output
y scalar, 1 or 0.
Remarks
y will be a scalar 1 if the matrix x contains any missing values, otherwise it will be a 0.
An element of x is considered to be a missing if and only if it contains a missing value
in the real part. Thus, for x = 1 + .i, ismiss(x) will return a 0.
Example
x = { 1 6 3 4 };
y = ismiss(x);
y = 0.0000000
See also
scalmiss, miss, missrv
625
isSparse 25. COMMAND REFERENCE
Purpose
Tests whether a matrix is a sparse matrix.
Format
r = isSparse(x);
Input
x MN sparse or dense matrix.
Output
r scalar, 1 if x is sparse, 0 otherwise.
Source
sparse.src
626
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

K
25. COMMAND REFERENCE key
Purpose
Returns the ASCII value of the next key available in the keyboard buer.
Format
y = key;
Portability
Unix, OS/2, Windows
key gets input from the active window. If you are working in terminal mode, key
doesnt see any keystrokes until Enter is pressed.
Remarks
The value returned will be zero if no key is available in the buer or it will equal the
ASCII value of the key if one is available. The key is taken from the buer at this time
and the next call to key will return the next key.
Here are the values returned on a PC if the key pressed is not a standard ASCII
character in the range of 1-255.
1015 Shift Tab
1016-1025 Alt Q, W, E, R, T, Y, U, I, O, P
1030-1038 Alt A, S, D, F, G, H, J, K, L
1044-1050 Alt Z, X, C, V, B, N, M
1059-1068 F1-F10
1071 Home
1072 Cursor Up
1073 Pg Up
1075 Cursor Left
1077 Cursor Right
1079 End
1080 Cursor Down
1081 Pg Dn
1082 Ins
1083 Del
1084-1093 Shift F1-F10
1094-1103 Ctrl F1-F10
1104-1113 Alt F1-F10
1114 Ctrl-PrtSc
1115 Ctrl-Cursor Left
1116 Ctrl-Cursor Right
1117 Ctrl-End
1118 Ctrl-PgDn
1119 Ctrl-Home
1120-1131 Alt 1,2,3,4,5,6,7,8,9,0,-,=
1132 Ctrl-PgUp
627
key 25. COMMAND REFERENCE
Example
format /rds 1,0;
kk = 0;
do until kk == 27;
kk = key;
if kk == 0;
continue;
elseif kk == vals(" ");
print "space \\" kk;
elseif kk == vals("\r");
print "carriage return \\" kk;
elseif kk >= vals("0") and kk <= vals("9");
print "digit \\" kk chrs(kk);
elseif vals(upper(chrs(kk))) >= vals("A") and
vals(upper(chrs(kk))) <= vals("Z");
print "alpha \\" kk chrs(kk);
else;
print "\\" kk;
endif;
endo;
This is an example of a loop that processes keyboard input. This loop will continue
until the escape key (ASCII 27) is pressed.
See also
vals, chrs, upper, lower, con, cons
628
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

K
25. COMMAND REFERENCE keyw
Purpose
Waits for and gets a key.
Format
k = keyw;
Output
k scalar, ASCII value of the key pressed.
Portability
Unix, OS/2, Windows
keyw gets the next key from the input buer of the active window.
If you are working in terminal mode, GAUSS will not see any input until you press the
Enter key.
Remarks
keyw gets the next key from the keyboard buer. If the keyboard buer is empty, keyw
waits for a keystroke. For normal keys, keyw returns the ASCII value of the key. See
key for a table of return values for extended and function keys.
See also
key
629
keyword 25. COMMAND REFERENCE
Purpose
Begins the denition of a keyword procedure. Keywords are user-dened functions
with local or global variables.
Format
keyword name(str);
Input
name literal, name of the keyword. This name will be a global symbol.
str string, a name to be used inside the keyword to refer to the argument that
is passed to the keyword when the keyword is called. This will always be
local to the keyword, and cannot be accessed from outside the keyword or
from other keywords or procedures.
Remarks
A keyword denition begins with the keyword statement and ends with the endp
statement. See Chapter 9.
Keywords always have 1 string argument and 0 returns. GAUSS will take everything
past name, excluding leading spaces, and pass it as a string argument to the keyword.
Inside the keyword, the argument is a local string. The user is responsible to
manipulate or parse the string.
An example of a keyword denition is:
keyword add(str);
local tok,sum;
sum = 0;
do until str $== "";
{ tok, str } = token(str);
sum = sum + stof(tok);
endo;
print "Sum is: " sum;
endp;
To use this keyword, type:
add 1 2 3 4 5;
This keyword will respond by printing:
Sum is: 15
See also
proc, local, endp
630
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

L
25. COMMAND REFERENCE lag1
Purpose
Lags a matrix by one time period for time series analysis.
Format
y = lag1(x);
Input
x NK matrix.
Output
y NK matrix, x lagged 1 period.
Remarks
lag1 lags x by one time period, so the rst observations of y are missing.
Source
lag.src
Globals
None
See also
lagn
631
lagn 25. COMMAND REFERENCE
Purpose
Lags a matrix a specied number of time periods for time series analysis.
Format
y = lagn(x,t );
Input
x NK matrix.
t scalar, number of time periods.
Output
y NK matrix, x lagged t periods.
Remarks
If t is positive, lagn lags x back t time periods, so the rst t observations of y are
missing. If t is negative, lagn lags x forward t time periods, so the last t observations
of y are missing.
Source
lag.src
Globals
None
See also
lag1
632
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

L
25. COMMAND REFERENCE let
Purpose
Creates a matrix from a list of numeric or character values. The result is always of type
MATRIX.
Format
let x = constant list;
Example
let x;
x = 0
let x = { 1 2 3, 4 5 6, 7 8 9 };
x =
1 2 3
4 5 6
7 8 9
let x[3,3] = 1 2 3 4 5 6 7 8 9;
x =
1 2 3
4 5 6
7 8 9
let x[3,3] = 1;
x =
1 1 1
1 1 1
1 1 1
let x[3,3];
x =
0 0 0
0 0 0
0 0 0
let x = 1 2 3 4 5 6 7 8 9;
x =
1
2
3
4
5
6
7
8
9
633
let 25. COMMAND REFERENCE
let x = dog cat;
x =
DOG
CAT
let x = "dog" "cat";
x =
dog
cat
Remarks
Expressions and matrix names are not allowed in the let command, expressions such as
this:
let x[2,1] = 3*a b
are illegal. To dene matrices by combining matrices and expressions, use an expression
containing the concatenation operators: and | .
Numbers can be entered in scientic notation. The syntax is dEn, where d is a
number and n is an integer (denoting the power of 10).
let x = 1e+10 1.1e-4 4.019e+2;
Complex numbers can be entered by joining the real and imaginary parts with a sign
(+ or -); there can be no spaces between the numbers and the sign. Numbers with no
real part can be entered by appending an i to the number.
let x = 1.2+23 8.56i 3-2.1i -4.2e+6i 1.2e-4-4.5e+3i;
If curly braces are used, the let is optional. You will need the let for statements that
you want to protect from the beautier using the -l ag on the beautier command line.
let x = { 1 2 3, 4 5 6, 7 8 9 };
x = { 1 2 3, 4 5 6, 7 8 9 };
If indices are given, a matrix of that size will be created:
let x[2,2] = 1 2 3 4;
x =
1 2
3 4
If indices are not given, a column vector will be created:
634
C
o
m
m
a
n
d

R
e
f
e
r
e
n
c
e

L
25. COMMAND REFERENCE let
let x = 1 2 3 4;
x =
1
2
3
4
You can create matrices with no elements, i.e., empty matrices . Just use a set of
empty curly braces.
x = {};
Empty matrices are chiey used as the starting poin