The correct bibliographic citation for this manual is as follows: SAS Institute Inc., SAS/C Development System User's Guide, Volume 1: Introduction, Editor, Compiler, Version 6.0, Cary, NC: SAS Institute Inc., 1992. 316 pp. SAS/C- Dewelopment System User's Guide, Volume 1: Introduction, Editor, Compiler, Version 6.0 Copyright (c) 1992 by SAS Institute Inc., Cary, NC, USA. ISBN 1-55544-496-2 All rights reserved. Printed in the United States of America. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, or otherwise,M without the prior written permission of the publisher, SAS Institute Inc. 1st printing, July 1992 The SASI System is an integrated system of software providing complete control over data access, management, analysis, and presentationn Base`SAS software is the foundation`of the SAS System. Products within the SAS System include SAS/ACCESS, SAS/AFI, SAS/ASSIST, SAS/CPE, SAS/DMI, SAS/ETS, SAS/FSP, SAS/GRAPH, SAS/IML, SAS/IMS-DLoI, SAS/OR, SAS/QC, SAS/REPLAY-CICS, SAS/SHARE, SAS/STAT, SAS/TOOLKIT, SAS/CALC, SAS/CONNECT, SAS/DB2, SAS/EIS, SAS/ENGLISH, SAS/INSIGHT, SAS/LAB, SAS/LOOKUP, SAS/NVISION, SAS/PH-Clinical, SAS/SQL-DS, and SAS/TUTOR software. Other SAS Institute products are SYSTEM 2000 Data Management Software, with basic SYSTEM 2000, CREATE, Multi-User, QueX, Screen Writer, and CICS interface software; NeoVisuals software; JMP, JMP IN and JMP Server software; SAS/RTERM`software; and the SAS/C Compiler and the SAS/CX Compiler. MultiVendor Architecture and MVA are trademarks of SAS Institute Inc. SAS Institute also offers SAS Consulting and On-Site Ambassador services. SAS Communications, SAS Training, SAS Views, the SASware Ballot, and Observations are published by SAS Institute Inc. All trademarks above are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. (R) indicates USA registration. The Institute is a private company devoted to the support and further development of its software and related services. Amiga Includes and Development Tools Version 2.0 Copyright (c) 1990 Commodore-Amiga, Inc. All rights reserved. Amiga Workbench Version 2.0 Copyright (c) 1988, 1990 Commodore-Amiga, Inc. All rights reserved. Installer Copyright (c) 1991-1992 Commodore Amiga, Inc. All rights reserved. AmigaGuide and WDisplay Copyright (c) 1991-1992 Commodore-Amiga, Inc. All rights reserved. Distributed under license from Commodore. Enforcer and Mungwall Copyright (c) 1990-1992 Commodore-Amiga, Inc. Distributed with permission from Commodore. Amiga- AmigaDOS, Workbench, and AmigaGuide are registered trademarks or trademarks of Commodore Amiga, Inc. Commodore is a registered trademark or trademark of Commodore Electronics Limited. IBM is a registered trademark of International"Business Machines Corporation. Other brand and product names are registered trademarks or trademarks of their respective companies. Doc S17, Ver112.6, 071692 Contents ix Reference Aids xi Credits xiii Acknowledgments xv Using This Book xxiii Changes and Enhancements Part 1 Getting Started Page 3 Chapter 1 Installing Your SAS/C Development System 3 Introduction 3 Protecting Your Investment 4 Installing the Product on A Hard Disk 8 Installing the Product on Floppy Disks 10 Assigning Logical Device Names 10 Setting Environment Variables 13 Chapter 2 Using Your SAS/C Development System 13 Introduction 14 Using SAS/C Tools from the Workbench Screen 22 Using SAS/C Tools from the Shell 25 Using Icons 27 Chapter 3 Getting Help 27 Introduction 27 Using the Help System 29 Contacting the Technical Support Division Part 2 Using the Screen Editor (se) 37 Chapter 4 Using se 37 Introduction 38 Starting the Editor 39 Reading the Status Line 40 Moving Around in a File 40 Entering and Editing Text 46 Saving Your File and Exiting se 47 Managing Windows iv Contents 48 Compiling from within the Editor 48 Getting Help 49 Chapter 5 Controlling se 49 Introduction 50 Selecting Menu Options 51 Moving Around in the File 52 Inserting Text 52 Deleting Text 53 Working with Blocks of Text 53 Searching for and Replacing Strings 54 Managing Windows 54 Changing Colors 55 Creating and Using Keystroke Macros 55 Editing a New File 56 Naming Files 56 Undoing Changes 56 Saving Your File and Exiting the Editor 57 Chapter 6 Customizing the Editor 57 Introduction 57 Displaying the Configuration Window 59 Displaying Key Definitions 60 Setting Key Definitions 61 Setting Tab Stops 61 Setting Other Options 64 Saving the New Settings 64 Reusing Saved Settings 65 Chapter 7 Using the AREXX`Interface to seM 65 Introduction 65 Executing A Series of Editor Commands 68 Communicating with External Programs 69 AREXX Macros Provided with the Compiler 70 AREXX Command Summary Part 3 Using the Compiler and Linker 77 Chapter 8 Compiling and Linking Your Program 77 Introduction 77 Compiling Your Program 120 Linking Your Program 127 Using Overlays Contents v 135 Chapter 9 Running Your Program from the Workbench Screen 135 Introduction 135 Working with argc and argv 137 Managing the Standard I/O Window 139 Chapter 10 Using Startup Modules, Autoinitialization, and Autotermination Functions 139 Introduction 140 Understanding Startup Modules 140 Modifying __main 141 Linking with a Startup Module 145 Writing Applications without a Startup Module 145 Using Autoinitialization and Autotermination Functions 147 Initializing System Library Bases 153 Chapter 11 Using Amiga Specific Features of the SAS/C Language 153 Introduction 154 Using Special Keywords 160 Managing Stack Space 161 Using #pragma Statements 163 Using Unnamed Unions 164 Using Implicit Structure References 164 Using Equivalent Structures 166 Using Zero-Length Arrays 167 Specifying the Size of Enumerated Types 168 Using the sizeof and Comma Operators in Preprocessor Directives 168 Using C++ Style and Nested Comments 168 Using National Characters in Variable Names 168 Using Common Model External Data 171 Chapter 12 How Does the Compiler Work? 171 Introduction 171 Compiling Your Program 173 Linking Your Program 174 Running Your Program 175 Changing Hunk Names 176 Addressing Data 177 Understanding Data Types and Sizes 179 Storing Data vi Contents 181 Chapter 13 Writing Portable Code 181 Introduction 181 Compiling Your Program 182 Writing Your Program Part 4 Appendices 193 Appendix 1 Solving Common Problems 193 Introduction 193 Resolving Undefined Symbols 195 Fixing Compilation Errors 197 Using CodeProbe 197 Using Formatted Print Functions 198 Using getchar 199 Getting Incorrect Results from Function Calls 200 Crashing the Machine 200 Using The asctime Function 201 Managing the Standard I/O Window 201 Linking Resident Programs or Creating Resident Libraries 202 Writing Replacement Functions for SAS/C Library Functions 202 Eliminating Informational Messages 203 Appendix 2 Error and Warning Messages 203 Introduction 203 Using Error and Warning Messages 204 Explanations of Unnumbered Compiler Messages 206 Explanations of Numbered Compiler Messages 258 Explanations of Linker Messages 265 Enabling Suppressed Messages 267 Appendix 3 Implementation-Defined Behavior 267 Introduction 268 F.3.1 Translation 268 F.3.2 Environment 268 F.3.3 Identifiers 269 F.3.4 Characters 269 F.3.5 Integers 270 F.3.6 Floating-Point 270 F.3.7 Arrays and Pointers 271 F.3.8 Registers 271 F.3.9 Structures, Unions, Enumerations, and Bit-Fields 272 F.3.10 Qualifiers 272 F.3.11 Declarators 272 F.3.12 Statements 272 F.3.13 Preprocessing Directives Contents vii 273 F.3.14 Library Functions 278 F.3.15 Locale-Specific Behavior 281 Appendix 4 Converting From Aztec C Options to SAS/C Options 285 Appendix 5 Converting from Version 5 to Version 6 285 Introduction 285 Upgrading from Previous Versions 286 Converting Compiler Options 294 Specifying Version 6 Libraries 295 Index viii Reference Aids Displays 17 2.1 The SAS/C Compiler Options Index Screen 18 2.2 The SAS/C Message Browser Window 19 2.3 The Edit Window Showing example.c 21 2.4 CodeProbe Windows with example.c 28 3.1 Editor Help Screen 39 4.1 Editing hello.c and example.c 58 6.1 se Configuration Window 59 6.2 se Configuration Window Showing Ctrl-F4 Figures 128 8.1 An Example Overlay Tree 130 8.2 Example Overlay Tree with Filenames 132 8.3 Overlay Tree for hw 147 10.1 Startup Modules, Autoinitialization Functions, and Autotermination Functions Tables 70 7.1 AREXX Commands with Keystroke Equivalents 73 7.2 AREXX Commands without Keystroke Equivalents 80 8.1 Summary of Compiler Options 119 8.2 Preprocessor Symbols Defined by the Compiler 120 8.3 Preprocessor Symbols Defined by Compiler Options 148 10.1 Library Bases for .library Files 281 A4.1 Converting From Aztec C Options to SAS/C Options 287 A5.1 Converting Version 5 Options to Version 6 Options 294 A5.2 Specifying Version 6 Libraries x xi Credits Software The SAS/C Development System is designed, built, and tested through the combined effort of many people at SAS Institute. The AmigaDOS development group includes the following individuals: Development Steve Krueger, Douglas Walker, Michael S. Whitcher Testing and Twilah K. Blevins, Jim Cooper, Bob Patten, Technical Khristi Tomlinson Support These individuals continue to support future development of the SAS/C Development System. Documentation Composition Candy R. Farrell, Denise T. Jones, Blanche W. Phillips, Pamela A. Troutman Graphic Design Creative Services Department Proofreading Heather B. Dees, Laurie J. Medley, Karen A. Olander, Josephine P. Pope, Christian Schwoerke Technical Review Jim Cooper, Steve Krueger, Khristi Tomlinson, Douglas Walker, Michael S. Whitcher Writing and Jeanne Ferneyhough, Steve Krueger, Jeffrey Lopes, Editing Khristi Tomlinson, Douglas Walker, Helen Weeks, John M. West xii xiii Acknowledgments Many people make significant and continuing contributions to the development of the SAS/C Development System. First among them is John A. Toebes VIII, who was instrumental in the development of Versions 4.0 and 5.0 and who directed the early development of Version 6.0. Others who have contributed to the development and testing of Version 6.0 of the SAS/C Development System include Aaron Avery, Ralph Babel, Jim Biggs, Bruce M. Drake, Andy Finkel, Nathan S. Fish, Jose M. Gallego, John Gerlach Jr., Maximilian Hantsch, Randell Jesup, David N. Junod, Andrew Kopp, Martin J. Laubach, John Lindwall, Christian Ludwig, Andrew N. Mercier, Mike Meyer, Tony Preston, Julius Oklamcak, Joe Porkka, Loren J. Rittle, Tomas Rokicki, Larry Rosenman, Carolyn Scheppner, Steve Shireman, Michael Sinz, Martin Taillefer, Steve Tibbett, John Wiederhirn, Loren Wilton, and Kenneth Yarnall. The final responsibility for the SAS/C Development System lies with SAS Institute alone. We hope that you will always let us know your feelings about our product and its documentation. It is through such communication that the progress of SAS software continues to be accomplished. xiv xv Using This Book Purpose SAS/C Development System User's Guide, Volume 1: Introduction, Editor, Compiler, Version 6.0 describes how to install and use your SAS/C Development System. This books describes the editor and compiler in detail and provides an overview of some of the of the major tools available to the SAS/C programmer under AmigaDOS, such as the debugger, the message browser, and the scopts utility. "Using This Book" describes how you can best use this book. It describes the book's intended audience, the audience's prerequisite knowledge, the book's organization and its conventions, and additional documentation that is available to you. Audience This book assumes you have a working knowledge of the C language and the AmigaDOS operating system. For a list of publications you can use to learn the C language or the AmigaDOS operating system, refer to the "Additional Documentation" section at the end of "Using This Book." How to Use This Book This section gives an overview of the book's organization and content. The book's chapters are described, followed by a section on how to use each chapter. Organization SAS/C Development System User's Guide, Volume 1: Introduction, Editor, Compiler is divided into four parts; the chapters and appendices contained in each part are described here: Part 1: Getting Started Part 1 contains three chapters that show you how to install the SAS/C Development System, use its major features, and get help when necessary. Chapter 1, "Installing Your SAS/C Development System" describes how to install the SAS/C Development System, assign logical device names, set environment variables, and upgrade from previous versions of the product. xvi Using This Book Chapter 2, "Using Your SAS/C Development System" describes briefly how to use the major features of the SAS/C Development System: the editor, the compiler, the debugger, the scmsg utility, and the scopts utility. Chapter 3, "Getting Help" describes how to use the online help system and how to contact the Technical Support Division. Part 2: Using the Screen Editor (se) Part 2 contains four chapters that describe how to use the editor, how to customize the keymap, and how to use AREXX with the editor. Chapter 4, "Using se" describes the most frequently used se commands and options. Chapter 5, "Controlling se" lists all of the options and commands available in se. Chapter 6, "Customizing the Editor" describes how to use the se configuration window. The configuration window enables you to customize the meaning of various keystrokes within se. Chapter 7, "Using the AREXX Interface to se" describes how to use AREXX to create complicated macros and to communicate with other programs from se. Part 3: Using the Compiler and Linker Part 3 contains six chapters that describe how to compile, link, and run your program. These chapters also provide guidelines for writing your application. Chapter 8, "Compiling and Linking Your Program" describes how to use the compiler and linker. Chapter 9, "Running Your Program from the Workbench Screen" describes special considerations for running your program from the Workbench screen. Chapter 10, "Using Startup Modules, Autoinitialization, and Autotermination Functions" describes what functions the startup modules perform and how to write your own autoinitialization and autotermination functions. Chapter 11, "Using Amiga Specific Features of the SAS/C Language" describes how to use SAS/C extensions to the C Language. Using This Book xvii Chapter 12, "How Does the Compiler Work?" describes briefly the format of the object files produced by the compiler. This chapter also describes what happens when you compile, link, and run your program. Chapter 13, "Writing Portable Code" provides guidelines for improving the portability of your program. Part 4: Appendices Part 4 contains five appendices. Appendix 1, "Solving Common Problems" contains answers to the questions that users ask most frequently when they call the Technical Support Division. Appendix 2, "Error and Warning Messages" contains explanations for the diagnostic messages produced by the compiler and linker. Appendix 3, "Implementation-Defined Behavior" describes how the SAS/C Compiler behaves for each of those areas where the ANSI Standard allows an implementation to define its own behavior. Appendix 4, "Converting from Aztec C Options to SAS/C Options" lists each of the Version S Aztec C options and their equivalent Version 6 SAS/C options. Appendix S, "Converting from Version S to Version 6" lists each of the Version 5.10 options and their equivalent Version 6 options. This appendix also provides guidelines for converting your projects to Version 6 SAS/C software. xviii Using This Book What You The following table points you to specific chapters in this book for Should Read information on particular topics. For other references, refer to "Additional Documentation" later in this section. ___________________________________________________________________ For information on You should read ___________________________________________________________________ installing the product Chapter 1 upgrading from previous versions of the product Chapter 1 and Appendix 5 using the major features of the SAS/C Chapter 2 Development System contacting the Technical Support Division Chapter 3 using online help Chapter 3 using the editor Chapters 4 and 5 specifying the sc command and compiler options Chapter 8 managing the environment in which your program Chapters 9 and runs 10 using extensions to ANSI C Chapter 11 ___________________________________________________________________ Conventions This section covers the typographical and syntax conventions used in this book. Typographical The SAS/C books for AmigaDOS use special fonts to depict specific Conventions types of information. These typographical conventions are as follows: roman is the basic type style used for most text. monospace is used to show example statements or programs. Monospace is used also for items specific to the C language, such as the names of functions, header files, and keywords. oblique is used for arguments or variables whose values are supplied by the user; for example, you should enter an appropriate filename when you see filename. italic is used for terms that are defined. Italic is also used to indicate arguments for which you supply a value. Using This Book xix Syntax This book uses the following conventions for syntax: Conventions monospace indicates commands, keywords, and switches that should be spelled exactly as shown. These arguments may or may not be optional, depending on whether they are enclosed in square brackets. italic indicates arguments for which you supply a value. [] (square indicate an optional argument when they surround brackets) the argument. ...(gllipsis) indicates that you can repeat the argument or group of arguments preceding the ellipsis any number of times. | means to choose one item from a group of items (vertical bar) separated by the bars. The following example illustrates these syntax conventions: env [function | integer] env is a command name, so it appears in monospace type. function is a function for which you supply the name, so it appears in italic type. [function | integer] are both optional, so they are enclosed in square brackets. function | integer indicates that you can specify only one of the items separated by the vertical bar. Additional Documentation The following sections list documentation you may find helpful in using the SAS/C Development System. SAS If you are interested in SAS documentation, you need to contact the Documentation Book Sales department by writing to the following address or by calling the following number: SAS Institute Inc Book Sales Department SAS Campus Drive Cary, NC 27513 919-677-8000 xx Using This Book SAS/C Development System This book is part of a set of publications for the SAS/C Development System. There are three other publications in the set: [] SAS/C Development System User's Guide, Volume 2: Debugger, Utilitles, Assembler, Version 6.0 describes how to use [] CodeProbe, the SAS/C Source Level Debugger [] the utilities such as smake, grep, scopts, and scmsg [] the SAS/C Macro Assembler [] the global and peephole optimizers. [] SAS/C Development System Library Reference, Version 6.0 describes how to [] access libraries [] create your own libraries [] use header files to reduce the amount of time and space required ` by your program. [] SAS/C Development System Quick Reference, Version 6.0 contains reference tables for the library functions, compiler and linker options, and debugger commands. These volumes are sold together as a set with the software. You can order the entire package by specifying order #A56185. Other The following sections list additional reference material specific to the Documentation C language, Amiga and AmigaDOS programming, and the Motorola 68xxx microprocessor family. C Language The following books describe the C programming language: American National Standards Committee (1990), American National Standard for Information Systems--Programming Language C, Document Number X3J11/90-013, Washington, D.C.: X3 Secretariat: Computer and Business Equipment Manufacturers Association. Harbison, Samuel P. and Steele, Guy L., Nr. (1990), C: A Reference Manual, Third Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. Kernighan, Brian W. and Ritchie, Dennis M. (1988), The C Programming Language, Second Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. Kochan, Stephen G. (1988), Programming in ANSI C, First Edition, Indianapolis, Indiana: Hayden Books. Using This Book xxi Amiga and AmigaDOS The following books provide information specifically about programming on the Amiga system. Most of the examples in these books are written in C or assembly language. Commodore-Amiga, Inc. (1990), Using the System Software, Reading, MA: Addison-Wesley Publishing Company. Commodore Amiga, Inc. (1991), Amiga Hardware Reference Manual, 3rd Edition, Reading, MA: Addison-Wesley Publishing Company. Commodore-Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: Devices, 3rd Edition, Reading, MA: Addison-Wesley Publishing Company. Commodore Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: Includes and Autodocs, 3rd Edition, Reading, MA: Addison-Wesley Publishing Company. Commodore-Amiga, Inc. (1991), Amiga User Interface Style Guide, Reading, MA: Addison-Wesley Publishing Company. Commodore-Amiga, Inc. (1991), The AmigaDOS Manual, 3rd Edition, New York, NY: Bantam Books. Commodore-Amiga, Inc. (1992), Amiga ROM Kernel Reference Manual: Libraries, 3rd Edition, Reading, MA: Addison-Wesley Publishing Company. Motorola 68xxx The following books contain information specifically about programming the Motorola 68xxx family of microprocessors. Motorola, Inc. (1987), MC68881/MC68882 Floating-Point Coprocessor User's Manual, First Edition, Englewood Cliffs, NJ: Prentice Hall, Inc. Motorola, Inc. (1989), MC68030 Enhanced 32-Bit Microprocessor User's Manual, Second Edition, Englewood Cliffs, NJ: Prentice Hall, Inc. Motorola, Inc. (1989), Programmer's Reference Manual, Phoenix, AZ: Motorola Literature Distribution. Contacting You can contact Commodore Application and Technical Support at the CATS following address: 1200 Wilson Drive West Chester, PA 19380 215-429-0643 xxii xxiii Changes and Enhancements The following sections describe some of the changes and enhancements for the SAS/C Development System, Version 6.0. [] The SAS/C Development System has an extensive online help system implemented using the AmigaGuide hypertext system from Commodore. The online help describes each utility, CodeProbe command, editor command, library function, diagnostic message, and compiler option. For a complete description of using the help system, see Chapter 3, "Getting Help." [] The SAS Institute Technical Support Division has a new facility called EMITS (Electronic Mail Interface to Technical Support) that allows you to report problems and receive help through Internet. For more information, see Chapter 3, "Getting Help." [] Compiler executables and other files are installed in a directory tree pointed to by the assign sc:. Unlike the Version 5 assign lc:, sc: points to the root of the compiler's installation directory. [] The lc compiler front-end has been replaced with the new sc front- end, which takes options in a different form. The new sc front-end accepts C source files, assembly language files, object files, and libraries. You may specify options before or after the filenames. See Chapter 8, "Compiling and Linking Your Program," for more information. To help you make the transition to Version 6, the SAS/C Development System provides two utilities, sc5 and lctosc. The sc5 command accepts options in the form accepted by lc and invokes the Version 6 compiler. The lctosc utility accepts options in the form accepted by lc and prints the equivalent sc options to stdout. Both sc5 and lctosc read the sascopts file, if present. Appendix 5, "Converting from Version 5 to Version 6," provides guidelines for converting your projects to Version 6. xxiv Changes and Enhancements [] The names of various other executables have changed. The following table lists the names of the Version 5 executables and the corresponding Version 6 names. Version 5 Version 6 ____________________________ blink slink lse se sascopts scopts sascsetup scsetup [] Many symbols and functions in the link libraries have new names that adhere to the ANSI Standard. The Standard requires that all non-ANSI symbols referenced in ANSI header files start with two underscores or an underscore and a capital letter. The Version 5 symbols that violated this standard have been renamed, usually by adding one or two underscores to the front of the name. For information on a specific symbol, refer to Chapter 6, "Predefined Data Name Reference," in SAS/C Development System Library Reference. [] The name of the file that is created by the scopts utility has been changed from sascopts to scoptions. [] The AmigaDOS 1.3 header files are no longer shipped with the SAS/C Compiler. However, all AmigaDOS 1.3 functions are available under AmigaDOS 2.0, so you can develop code that runs under AmigaDOS 1.3 by restricting your program from using any AmigaDOS 2.0 functions. [] The SAS/C Development System, Version 6, does not have separate libraries for use with registerized parameters. The normal link libraries have both registerized and nonregisterized entry points. If you write a function that has the same name as a library function, you need to add the _ _ regargs keyword to your function or compile with the parms=both or parms=register option. For example, you may want to replace the SAS/C library function malloc with your own version of malloc. If you compile with the parms=stack option or define your version of malloc with the _ _ stdargs keyword, then two versions of malloc are linked into your executable. If you use other SAS/C library functions that call malloc, these functions use the version of malloc in the SAS/C libraries. However, your functions that call malloc use your version of malloc. To make sure that all calls to malloc are using your version Changes and Enhancements xxv of malloc, define your version with __ regargs or compile with the parms=both or parms=register option. For information on using registerized parameters, refer to the description of the __ regargs keyword in Chapter 11, "Using Amiga Specific Features of the SAS/C Language," and the description of the parameters compiler option in Chapter 8, "Compiling and Linking Your Program." [] The lc1, lc2, and go commands are not included in Version 6 of the SAS/C Development System. The sc driver loads AmigaDOS shared libraries to handle the work of the various phases instead of invoking multiple programs. [] The lseinst program has been removed, and the se configuration window added in its place. Select the Configuration Window option from the Options pulldown menu in se to invoke the configuration window. For complete description of using the configuration window, see Chapter 6, "Customizing the Editor." [] The precompiled header files in Version 5 have been replaced with GSTs (Global Symbol Tables). GSTs are much faster than precompiled headers because they remain in RAM between compiles. Some additional utilities, gst and hypergst, allow you to browse the RAM-resident GST files for information on symbols defined in system header files or in your header files. For information on creating and using GSTs refer to SAS/C Development System Library Reference and to the descriptions of the gst and hypergst utilities in SAS/C Development System User's Guide, Volume 2: Debugger, Uhlities, Assembler. See also the descriptions of the gst and makegst compiler options in Chapter 8, "Compiling and Linking Your Program." [] The new scmsg utility enables you to integrate any editor that supports AREXX into the SAS/C Development System. For more information, see the description of the errorrexx compiler option in Chapter 8, "Compiling and Linking Your Program," and the description of the scmsg utility in SAS/C Development System User's Guide, Volume 2. [] The global optimizer supports many new optimizations, including inline functions. You can use the __ inline keyword to specify a function that is to be inlined. See Chapter 11, "Using Amiga Specific Features of the SAS/C Language," for information on special keywords supported by the SAS/C Compiler. Refer to SAS/C Development System User's Guide, Volume 2 for information on the global optimizer. xxvi Changes and Enhancements [] The new peephole optimizer improves code quality significantly. The peephole optimizer is run automatically when you choose the optimize compiler option, unless you specifically suppress it with nooptpeep. Refer to SAS/C Development System User's Guide, Volume 2 for information on the peephole optimizer. [] The CodeProbe debugger has numerous enhancements. The major enhancements include the following: [] The command syntax has been totally rewritten and greatly extended. [] The debugger has new support for debugging AmigaDOS shared libraries. [] The debugger automatically detects Enforcer hits caused by your program and halts your program at the location of the hit. [] The debugger now has cross-debugging capability. This new feature allows you to run your program on one machine and debug the program using another machine connected through the serial port or a network file system. Refer to SAS/C Development System User's Guide, Volume 2 for a complete description of using the debugger. [] The compiler still generates code by default to check for stack overflow at the entry to each function. However, this code is more reliable under Version 6.0. The compiler also supports a new option that generates code to allocate a new stack and allow your program to continue running if the old stack runs out. For more information, see the description of the stackextend compiler option in Chapter 8, "Compiling and Linking Your Program." See also the description of the__ stackextend keyword in "Managing Stack Space" in Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] The compiler now supports the common model for external data as well as the strict reference-definition model. For more information, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] The compiler now supports a coverage option that generates special code that tells you which portions of your program were executed by your test cases. A new utility, the cover utility, analyzes the data produced by the compiler when you specify cover age. This information helps you design test cases that test all portions of your code. For more information, see the description of the coverage compiler option in Chapter 8, "Compiling and Linking Your Program," and the descriqtion of the cover utility in SAS/C Development System User's Guide, Volume 2. Changes and Enhancements xxvii [] The stringmerge compiler option, equivalent to the -cs in Version 5, merges all string constants and places them in the code section. Unlike tie Version S option, stringmerge also places all data declared stat i c cons t and all automatic initializer data in the code section. For more information, see the description of the stringmerge compiler option in Chapter 8, "Compiling and Linking Your Program." [] The compiler can now produce a disassembly of the generated object code. For more information, see the description of the disassem compiler option in Chapter 8, "Compiling and Linking Your Program." [] The compiler now adjusts dynamically to low-memory situations. If you compile your program and your machine runs low on memory, the compiler displays the message ***Freeing Resources and frees memory to enable it to continue the compilation. You can also use the memorysize compiler option to limit the compiler's memory use. For more information, see the description of the memorysize option in Chapter 8, "Compiling and Linking Your Program." [] You can designate autoinitialization functions that you waot the compiler to call automatically before it calls your main routine. You can also designate autotermination functions that you want the compiler to call after main returns. For more information, see Chapter 10, "Using Startup Modules, Autoinitialization, and Autotermination Functions." [] System library bases that are not defined in your code are automatically opened and initialized. For more information, see Chapter 10, "Using Startup Modules, Autoinitialization, and Autotermination Functions." [] The SAS/C Compiler now permits references to unnamed unions and direct references to members of substructures. The compiler also permits zero-length arrays as members of structures. For more information, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] The new #pragma tagcall allows you to call AmigaDOS functions that take a variable parameter list without using`assembler stubs. For more information, refer to SAS/C Development System Library Reference. xxviii Changes and Enhancements [] The new #pragma msg allows you to control`compiler diagnostic output more closely. For information, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] The compiler now supports char, short, and long enum types. For more information, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] Part 1 Getting Started Chapters 1 Installing Your SAS/C Development System 2 Using Your SAS/C Development System 3 Getting Help 2 1 Installing Your SAS/C Development System 3 Introduction 3 Protecting Your Investment 4 Installing the Product on A Hard Disk 5 Modifying Your Startup File 6 What Directories Does the Installation Program Create? 8 Installing the Product on Floppy Disks 10 Assigning Logical Device Names 10 Setting Environment Variables Introduction This chapter describes how to install your SAS/C Development System and provides guidelines for upgrading your projects to Version 6. Protecting Your Investment Before you install your SAS/C Development System, you should do the following: [] Make backup copies of the disks distributed with this product. To make copies, you can use the AmigaDOS diskcopy command, or you can select the disk icon and choose copy from the"Icons menu. Refer to your AmigaDOS manual for more information on copying disks. [] Write down your registration number where you can find it easily. You must give your registration number to the Technical Support staff before you can receive help from the SAS Institute Technical Support Division. [] Complete the registration card that comes with this product and return it to SAS Institute Inc. You must"register your purchase to qualify for technical support and to be notified about future upgrades. If you are upgrading from a previous version, and you have already registered the previous version, you do not need to send in a new registration card. If you are not sure if you are in the SAS Institute database of registered users, write your old registration number and a brief explanation on the new card before sending in the card. 4 Chapter 1 Installing the Product on A Hard Disk The installation program is distributed on disk number 1. You should run the installation program from the Workbench screen, not the Shell. To install the SAS/C Development System, insert disk number 1 in the disk drive and double-click on the disk icon to open the SASC_6.0_Disk_1 window. Double-click on the Install-SASC icon to open the Install-SASC window. If you want to see exactly what the installation program will do before you actually install the product, you can select the Pretend to Install and Log File options, and then proceed through the installation process. As you go through the installation process, the installation program writes to a log file all of the commands it would have executed if you were actually installing the product. The log file is named install_log_file and is written to the directory in which you are installing the product (or to ram:, if it cannot write to that directory). As you go through the installation process, the installation program asks you some questions, including the name of the directory, or destination, where you want to install the SAS/C Development System. The installation program allows you to save disk space by asking you which parts of the product you want to install. For example, you may choose not to install the cross debugger. The installation program also allows you to choose whether you want to install compressed or normal C header files. Choose compressed header files only if you need to conserve space on your hard disk. If you choose not to install parts of the product, include this information in any communication you have with the Technical Support Division. After you have answered all of the questions (and if you select Install for Real), the installation program then proceeds to install the product. The program prompts you to insert disks as necessary. Context-sensitive online help is available at any point in the installation process by clicking on the Help button, and you can abort the installation process at any time by clicking on the Abort button. After all the files on the distribution disks have been copied to your hard disk, the installation program asks you if you want the following statements added to your s:user-startup file. assign sc: destination:sc assign lib: sc:lib assign include: sc:include path sc:c add The installation program adds these statements automatically if you select Proceed. If you decide to add these statements manually and do not Installing Your SAS/C Development System 5 select Proceed, make sure you add them before any line that calls a utility that creates a new Shell, such as PopCLI. Finally, the installation program displays the read.me file. Note: Read the read.me file carefully. This file contains important information that is not contained in the documentation distributed with the product. This information may concern new or enhanced features, bug fixes, or changes to the documentation. The read.me file is installed with the rest of the product, so you can refer to this file later. Modifying Your If you are running AmigaDOS 2.0, the modifications that the installation Startup File program makes to your startup file (if you selected Proceed) are sufficient to allow the compiler to run. If you are running AmigaDOS 1.3, you may need to make an additional change to your s: startup-sequence file to make sure that these assign and path statements take effect. The installation program adds the path and assign statements to the file s:user-startup. The installation also asks you where to add the following lines: if exists s:User-startup execute s:user-startup endif The installation program suggests a place to enter these lines, but you can specify a different place if necessary. Make sure that these lines are entered before any line that calls a utility that creates a new Shell, such as PopCLI. The installation program adds these lines to either s:startup-sequence or s:startupII . If the lines are added to s:startupII, you must verify that s: startupII is properly executed from s: startup-sequence. Under some older versions of AmigaDOS Version 1.3, s: startupII is executed from s: startup-sequence through either a newshell command or a run execute command. Therefore, any path statements added to the s:user-startup file do not have any effect under the Workbench screen or the Shell. Edit your s:startup- sequence file, and verify that s:startupII is executed with an execute command only. If not, change the command to the following: execute s:startupII If this command is not in your s: startup-sequence file, add it. If s: startupII is executed with a run execute command, delete the word run. 6 Chapter 1 After you have saved your s:startup-sequence file with the correct command and completed the installation process, re-boot your machine. Your compiler should work correctly. What Directories After you finish installing the product, you will have a directory named Does the sc that contains several files and subdirectories. The following list Installation describes the directories that have icons. Program Create? Note: Some of these icons may not be present if you choose not to install the entire package. [] starter_project is the directory that the scsetup utility uses as a model whenever you set up a project. (A project consists of all of the files that make up an application.) You can add icons and programs to starter_project as necessary. For example, you can create an scoptions file in this directory that contains any compiler options that you want to be copied into each of your project directories. scsetup copies the entire contents of starter_project into the project drawer you specify. The installation program places the following icons (and files) in this drawer: Edit invokes the se editor Build builds the project Debug runs the debugger SCoptions sets compiler options. [] c contains the executable modules for the SAS/C Development System, including the assembler, compiler, debugger, linker, and various utilities. [] icons is a directory used by scsetup, se, and other utilities that contains default icons for different file types. You can replace any of the icons in this directory or add your own icons. For more information on using icons, see Chapter 2, "Using Your SAS/C Development System." [] examples contains example programs. For each example, this directory contains complete source code and a read.me file that explains the example program and describes how to run the example. Some of the examples are in their own subdirectory under the examples directory. [] help contains help files used by the various SAS/C utilities. Chapter 3, "Getting Help," describes the contents of this directory and how to use the help system. Installing Your SAS/C Development System 7 The installation program also creates some directories that do not have icons. These directories are as follows: [] env contains default configuration information for tools such as the editor. The tools look first in env: sc for their configuration files, and if the files are not there, the tool looks in sc: env. [] source contains C and assembly language source code for various parts of the SAS/C Development System. For example, this directory includes the source code to the different startup modules. [] Include contains C header files and assembler header files. The INCLUDE: logical device name should point to this directory. [] Lib contains link libraries. The LIB: assign should point to this directory. [] libs contains resident libraries used by the various SAS/C commands. These libraries must exist in the sc:libs drawer. Do not attempt to copy them into libs: with the AmigaDOS system libraries. The following libraries are included in this drawer: sc1.library is required by the compiler. This library must be present to compile any code. sc2.library is required by the compiler. This library must be present to compile any code. scgo.library is required by the global optimizer. This library must be present if you compile with the optimize option and do not specify the nooptglobal option. scpeep.library is required by the peephole optimizer. This library must be present if you compile with the optimize option and do not specify the nooptpeep option. scdebug.library generates debugging information. Without this library, the compiler can generate partial line number information but cannot generate any symbolic debugging information. scgst.library generates or accesses GSTs (Global Symbol Tables). This library is not required if you never use the GSTs. Refer to SAS/C Development System Librar,v Reference, Version 6.0 for information on using GSTs. 8 Chapter 1 schi.library is used by CodeProbe to read the debugging information in an executable module. This library is required if you run the debugger. sekeymap.library is used by the editor to allow you to modify the editor's configuration. scspill.library detects low-memory conditions and attempts to reduce the compiler's memory usage. This library is required if you want the compiler to react dynamically to low-memory conditions. If you compile your program and your machine runs low on memory, the compiler displays the message ***Freeing Resources and frees memory to enable it to continue the compilation. You can force the compiler to free memory at any time by pressing Control-F in the window to which the compiler is sending output. sclist.library generates listing and cross-reference files. This library is not required if you never use the list or xref compiler options. It is recommended that you do not place your source code in the sc directory tree. Installing updates to the SAS/C Development System is easier if you can replace the entire directory without worrying about losing any of your own program files. Instead, you should set up a different directory for your C development work. You may find it useful to keep different projects in different directories. Keeping projects separated makes it easier to keep track of the smakefiles and compiler options required for each project. Remember, a project consists of all of the files that make up an application. Installing the Product on Floppy Disks The installation program is distributed on disk number 1. You should run the installation program from the Workbench screen, not the Shell. Before installing the SAS/C Development System, make sure you have at least two blank disks on which to install this product. To install the SAS/C Development System, insert disk number 1 in the drive df0: and double-click the disk icon to open the SASC_6.0_Disk_1 window. Double-click the Install-SASC icon to open the Install-SASC window. If you want to see exactly what the installation program will do before you actually install the product, you can select the Pretend to Install and Installing Your SAS/C Development System 9 Log File options, and then proceed through the installation process. As you go through the installation process, the installation program writes to a log file all of the commands it would have executed if you were actually installing the product. The log file is named install_log_file and is written to ram:. As you go through the installation process, the installation program asks you some questions, then proceeds to install the product. The program`prompts you to insert disks as necessary. The installation program produces the following two working disks: Disk 1 is a bootable disk that contains the compiler (sc), linker (slink), editor (se), and the smake, scopts, and scmsg utilities. Disk 2 contains compressed header files, CodeProbe, sc.lib, scm.lib, and a small version of amiga.lib containing only global symbols (no stubs). The installation program asks you if you want to create a third disk: Disk 3 contains the remaining utilities and the global and peephole optimizers, if you choose to create disk 3. Under AmigaDOS 1.3, you will not be able to use the global and peephole optimizers. Under AmigaDOS 2.0, a multiple-directory assign statement is used to access the optimizers. Online help is available at any point in the installation process, and you can abort the installation process at any time. Finally, the installation program displays the read.me file. Note: Read the read.me file carefully. This file contains important information that is not contained in the documentation distributed with the product. This information may concern new or enhanced features, bug fixes, or changes to the documentation. 10 Chapter 1 Assigning Logical Device Names When you install the SAS/C Development System (either on floppy disks or on a hard drive), the installation program tells you that specific assign statements must be added to your startup file. You may choose to allow the installation program to add these statements for you. The following list describes each of the logical device names that need to be added to your startup file. sc: specifies the directory in which the compiler and other utility programs are located. For example, the following statement indicates that the compiler and utilities are in the directory work:sc. assign sc: work:sc include: specifies the directory in which the compiler can find system header files included in your programs by specifying the #include statement with angle brackets (<>). For example, you could enter the following assign statement from the Shell prompt: assign include: df0:sc/include Then, if you compile a program containing the statement #include , the compiler attempts to include the file df0: sc/include/stdio.h. lib: specifies the directory in which the linker can find the libraries and other modules needed to build executable files. For example, the following Shell command indicates that the libraries are in the directory sc/lib on the work: volume: assign lib: work:sc/lib Setting Environment Variables The various tools in the SAS/C Development System sometimes require information in environment variables. For example, the sc command looks for default options in a file called scoptions; if the compiler does not find such a file in the current directory, it looks in the environment variable ENV:sc/scoptions. Environment variables are stored in the logical device ENV: in files with the same name as the variable. ENV: is usually assigned to the Installing Your SAS/C Development System 11 ram: device or some other temporary location. You can set environment variables from the Shell with the setenv command. All SAS/C utilities that use environment variables access them from the ENV: sc subdirectory, so be sure to create this subdirectory in env: each time you boot your machine. Under AmigaDOS 2.0, the installation program creates this subdirectory by creating the directory ENVARC: SC. Under AmigaDOS 1.3, ENVARC: does not necessarily exist, so you must make sure that the ENV: SC subdirectory is created each time you boot your machine. 12 13 2 Using Your SAS/C Development System 13 Introduction 14 Using SAS/C Tools from the Workbench Screen 14 Setting Up a Project 15 Creating a Source File with se 16 Compiling, Linking, and Running Your Program 20 Debugging Your Program 22 Using SAS/C Tools from the Shell 22 Creating a Source File with se 22 Compiling, Linking, and Running Your Program 25 Debugging Your Program 25 Using Icons Introduction This chapter introduces the primary features of the SAS/C Development System. It shows you how to perform the following tasks: [] set up a project [] set compiler options for the project [] create a C source file [] compile, link, and run a C program [] use the debugger to look at your program. As you perform these tasks, the SAS/C Development System creates several icons. The icons it creates depend on the filename extension of the file you create. The last section in this chapter, "Using Icons," describes the default icons for each of these files and how to customize these icons. Each of the tools used to perform these tasks are described in more detail in subsequent chapters in this book and in SAS/C Development System User's Guide, Volume 2: Debugger, Utilities, Assembler, Version 6.0. The SAS/C Development System provides an environment based on Intuition from which you can perform each of these tasks. However, you can also perform these tasks from the Shell. 14 Chapter 2 Using SAS/C Tools from the Workbench Screen The following sections describe how to use the SAS/C Development System from the Workbench screen. Specifically, these sections discuss the following: [] setting up a project using the scsetup utility [] creating a C source file using the se editor [] setting compiler options for the project using scopts [] compiling and linking a program using the Build icon [] running your program [] using the debugger to look at your program. This chapter provides example directions that you can enter on your machine as you read through the chapter. These examples illustrate how the many features of the SAS/C Development System work together. Setting Up a To make your C development work easier, you can set up either a new or Project existing project using the scsetup utility. When you set up a project, scsetup creates icons for any files or directories that already exist in the project and copies the contents of the sc: starter_project directory into the project. The starter_project directory contains icons for each of the tools you need most often during your development work: SCoptions starts the scopts utility and allows you to specify the compiler options with which you most often want to compile the programs in the directory you are setting up. Debug starts the CodeProbe Source Level Debugger. Build starts the smake utility. smake is a utility that helps you manage projects that are composed of many files. Edit starts the editor, se. You can substitute your own editor for se by selecting Info from the Workbench pull-down menu and changing the default tool in the Edit icon from sc:c/se to your editor. It is recommended that you do not place your source code in the sc directory tree. Installing updates to the SAS/C Development System is easier if you can replace the entire directory without worrying about losing any of your own program files. Using Your SAS/C Development System 15 To set up a project, run the scsetup utility by double-clicking the scsetup icon in the sc:c drawer. scsetup asks you for the name of the new project drawer (directory). For example, to create a new directory called csvuff on the Work: volume, you would enter: Work:cstuff scsetup creates a new directory called cstuff in Work: that contains the four icons described previously. For more information about the scsetup utility, refer to SAS/C Development System User's Guide, Volume 2. Creating a After you set up a directory for your C files, you can start entering your Source File C programs. To create a new file, double-click on the Edit icon to start with se the se editor. se displays a window into which you can enter your program. Type in the following program: #include #include #include int main(void) { int i=42; double d d=i/2; printf("i = %d, d=%2.1f\nl",i,d); Delay(60); return(O); Note: Enter this text exactly as shown. The semicolon missing from the declaration of d produces an error message that is used to illustrate scmsg, the message browser utility. 16 Chapter 2 If you enter any text differently from that shown here, simply use the backspace or delete key to delete the incorrect characters and correct the error. When you have finished entering the program, you must name the file, save it, and close the editor window as follows: 1. Press and hold the right mouse button to display the se menu. 2. Point to the Project heading in the menu bar to open the Project menu. 3. Select the Rename option. At the bottom of the screen, se asks you to enter a new filename for the current file. 4. Type example.c and press Return. 5. Hold down the right Amiga key and press the letter S to save the file and close the editor window. Under AmigaDOS 1.3, the icon for this new file is not displayed until you close and reopen the window for the directory in which you created the file. If necessary, close and reopen the window to display the icon for example.c. For more information about the se editor, see Chapter 4, "Using se," and Chapter 5, "Controlling se." Compiling, After you have created a C source program using the editor, you can Linking, and compile, link, and run your program. If you want to compile and link Running Your your program with the default compiler options, simply double-click on Program the Build icon. However, if you want to change the default values or specify additional options, you can use the scopts utility. With scopts, you can set compiler options simply by clicking on the option. To successfully run the example shown in this chapter, you need to set additional compiler options. Setting Compiler Options with scopts Usually, you compile all of the programs in a project with the same compiler options. The scopts utility allows you to click on the options with which you want to compile and to save the options in an scoptions file in the project drawer. To run scopts, double-click on the SCoptions icon. scopts displays the first of several windows on which you can select the options with which you want to compile. To run the example.c program, you must specify the math=standard and the link options. To use the message browser as described in the section "Compiling and Linking with the Build icon," you must specify the errorrexx option. Also, to use the CodeProbe debugger as described in the section "Debugging Your Program," later in this chapter, you must specify the debug=symbolflush option. Using Your SAS/C Development System 17 The link option appears on the first screen that scopts displays, the SAS/C Compiler Options Index screen, as shown in Display 2.1. Display 2.1 The SAS/C Compiler Options Index Screen To select the link option, click once on the NoLink cycle gadget. The gadget changes colors, and the text now reads Link. To select the math=standard option, click on the CODE OPTIONS... gadget, and then click once on the NoMath gadget. NoMath changes to Math=STANDARD. Click on OK to return to the SAS/C Compiler Options Index screen. To select the debug option, click on the COMPILER OPTIONS . . . gadget, and then click three times on the NoDebug gadget. NoDebug changes to Debug=SymbolFlush. Click on the OK gadget to return to the SAS/C Compiler Options Index screen. To select the errorrexx option, click once on the MESSAGE OPTIONS... gadget, and then click on the NoErrorRexx gadget. NoErrorRexx changes to ErrorRexx. Click on OK to return to the SAS/C Compiler Options Index screen. To save the option settings, click on the Save gadget. The scopts utility saves the options you select in the file scoptions in the project directory. When you compile your program, the compiler reads the options from scoptions. 18 Chapter 2 For more information about the scopts utility, refer to SAS/C Development System User's Guide, Volume 2. Compiling and Linking with the Build icon After you have selected the appropriate options, you can compile and link your program by double-clicking the build icon to start the smake utility. smake examines the drawer and determines that it contains only one C source file, example.c. smake then invokes the sc command to compile example.c using the options you specified with the scopts utility. When the compiler finds the missing semicolon in your program, the compiler invokes scmsg, the message browser. scmsg opens a window in which it displays each of the messages generated by the compiler. Display 2.2 shows the message browser window generated when you compile example.c. Display 2.2 The SAS/C Message Browser Window Double click on the message in the message browser window, and the message browser invokes the editor on the file and line number specified in the message, as shown in Display 2.3. Using Your SAS/C Development System 19 Display 2.3 The Edit Window Showing example.c Correct the error by inserting a semicolon at the end of the declaration for d. Save the corrected file by selecting the Save & Close option from the Project menu or by pressing Right Amiga-S. Close the message browser window by clicking on the Close gadget, and then close the smake window by pressing Return. Recompile and link your program (also referred to as rebuilding your program) by double-clicking on the Build icon. As before, smake invokes the sc command to recompile your file. smake then invokes the linker, slink, to produce the executable module, example. The linker also creates an icon for the executable module. (If you are running under AmigaDOS 1.3, you need to close then reopen the project drawer to see the icon for example.) For more information about the scmsg and smake utilities, refer to SAS/C Development System User's Guide, Volume 2. Running Your Program The build process produces an executable module and creates an icon for this module in the project directory. If the icon for this module is not displayed, close and reopen the window for the directory in which you created the file. To run example, double-click on the example icon. 20 Chapter 2 When you run a program from the Workbench screen, the compiler opens a standard I/O window in which your program can display output. In the case of the example program, the output is as follows: i = 42, d=21.00 If you are running under AmigaDOS 1.3, this window closes as soon as your program is finished running. For short programs, this window opens and closes so fast that it is difficult to see what is displayed in it. To make the window stay open for at least a second, the example program calls the AmigaDOS function Delay. If you are running under AmigaDOS 2.0, this window remains open until you click on its Close gadget. For information on changing the attributes of this window, see Chapter 9, "Running Your Program from the Workbench Screen." Debugging Your When you compile your program with the debug option, you can use the Program CodeProbe debugger to monitor the behavior of your program, line-by- line, as it executes. To run the debugger with the example file, click once on the Debug icon, then hold down the Shift key and double-click on the icon for the executable module. As shown in Display 2.4, CodeProbe opens two windows: the Source window that contains the source code for your program and the Dialog window into which you can enter CodeProbe commands. Using Your SAS/C Development System 21 Display 2.4 CodeProbe Windows with example.c CodeProbe stops on the first line of your main program. To step through your program one line at a time, you can press the Return key. Pressing the Return key is equivalent to entering the proceed command. The current (highlighted) line is the line that will execute next if you press Return. Press Return until the line containing printf is the current line. To display the value of a variable, you can use the display command, which you can abbreviate as d. To display the value of the variable d, enter d d on the command line of the Dialog window. If you have already stepped through the line containing d=i/2;, then the debugger displays 21 as the value of d. To finish executing your program, enter g (for go) on the command line of the Dialog window. You should always finish executing your program before quitting CodeProbe, or your machine may be left in an uncertain state and may crash later for no reason. To exit from the debugger, enter q (for quit). The Debugger has considerably more capabilities than those described here. For a complete description of the CodeProbe debugger, refer to SAS/C Development System User's Guide, Volume 2. 22 Chapter 2 Using SAS/C Tools from the Shell The following sections describe how to use the SAS/C Development System from the Shell. Specifically, these sections discuss the following: [] creating a C source file using the se editor [] setting compiler options for the project using scopts [] compiling and linking a program using the sc command [] running your program [] using the debugger to look at your program. If you are doing all of your work from the Shell, you do not need to use scsetup to set up a directory for your C files. However, you should create a new working directory using the AmigaDOS makedir command. It is recommended that you do not place your source code in the sc directory tree. Installing updates to the SAS/C Development System is easier if you can replace the entire directory without worrying about losing any of your own program files. Creating a After you have created a directory for your C files, you can start entering Source File your C programs. To create a new file, enter the se command, as with se follows: se se displays a window into which you can enter your program. The se editor works the same whether you start it from the Workbench screen or from the Shell. See "Creating a Source File with se" under the previous section, "Using SAS/C Tools from the Workbench Screen," for a description of entering a sample program. Of course, after you save the file and close the window, icons are not displayed. You are prompted for another command. For more information about the se editor, see Chapters 4 and 5 in Part 2, "Using the Screen Editor (se)." Compiling, After you have created a C source program using the editor, you can Linking, and compile, link, and run your program. If you want to compile your Running Your program with the default compiler options, simply enter the sc command Program followed by the name of the source file. However, to successfully run the examples shown in this chapter, you need to set additional compiler options. From the Shell, you can set compiler options using the scopts utility, or you can specify the compiler options on the sc command line. The next section, "Setting Compiler Options with scopts," describes two different ways to use the set options from the Shell. The section Using Your SAS/C Development System 23 "Compiling and Linking with sc" describes how to specify options on the se command line. Setting Compiler Options with scopts Usually, you compile all of the programs in a project with the same compiler options. The scopts utility allows you to set and save the options with which you want to compile the programs in a project. From the Shell, you can run scopts in two different ways: [] You can enter the scopts command followed by the options with which you want to compile. For the example programs in this chapter, you should enter the following command: scopts math=standard debug=symbolflush errorrexx link You can enter the options in uppercase, lowercase, or in mixed case. When you specify options on the scopts command, the scopts utility does the following: 1. reads the scoptions file in the current directory, if it exists 2. adds or changes the options, depending on the options you specify on the scopts command 3. writes the new option settings to the scoptions file in the current directory. [] You can enter the scopts command without specifying options and use the scopts screens to set the options: scopts scopts displays the first of`several windows on which you can select the options with which you want to compile. For the example program in this chapter, you should select the math=standard, link, errorrexx, and debug=symbolflush options as described in "Setting Compiler Options with scopts" under the previous section, "Using SAS/C Tools from the Workbench Screen." The scopts utility saves the options you select in the file scoptions in the project directory. When you compile your program, the compiler reads the options from scoptions. For more information about the scopts utility, refer to SAS/C Development System User's Guide, Volume 2. 24 Chapter 2 Compiling and Linking with sc If you chose to use scopts to set compiler options, then you can compile and link your example.c program by entering the sc command as follows: sc example.c sc reads the options from the scoptions file and compiles your program. However, if you chose not to use scopts to set compiler options, you must enter the following command to compile and link the example.c program: sc math=standard debug=symbolflush errorrexx link example.c In either case, you specified the link option, so the compiler calls slink to link your program using the correct libraries. If your program links correctly, the linker creates an executable module named example. When the compiler finds the missing semicolon in your program, the compiler invokes scmsg, the message browser. scmsg opens a window in which it displays each of the messages generated by the compiler. Display 2.2, earlier in this chapter, shows the message browser window generated when you compile example.c. (However, Display 2.2 shows the smake window behind the message browser window. On your machine, you will see a Shell window.) Double-click on the message in the message browser window. The message browser invokes the editor on the file and line number specified in the message, as shown in Display 2.3, also shown earlier in this chapter. Correct the error by inserting a semicolon at the end of the declaration for d. Save the corrected file by selecting the Save & Close option from the Project menu or by pressing Right Amiga-S. Close the message browser window by clicking on the Close gadget. Recompile and link your program by entering the sc command as before. slink produces the executable module example. For more information about the sc command, see Chapter 8, "Compiling and Linking Your Program." Running Your Program To run a program, enter the program name at the AmigaDOS prompt. To run example, enter the following: example Using Your SAS/C Development System 25 The example program displays the following output: i = 42, d=21.00 Debugging Your When you compile your program with the debug option, you can use the Program CodeProbe debugger to monitor the behavior of your program, line by- line, as it executes. To run the debugger with the example file, enter the following command at the Shell prompt: cpr example As shown in Display 2.4, CodeProbe opens two windows: the Source window that contains the source code for your program and the Dialog window into which you can enter CodeProbe commands. Enter debugger commands as described in "Debugging Your Program" under the previous section, "Using SAS/C Tools from the Workbench Screen." To finish executing your program, enter g (for go) on the command line of the Dialog window. You should always finish executing your program before quitting CodeProbe, or your machine may be left in an uncertain state and may crash later for no reason. To exit from the debugger, enter q (for quit). The Debugger has considerably more capabilities than those described here. For a complete description of the CodeProbe debugger, refer to SAS/C Development System User's Guide, Volume 2. Using Icons The tools included with the SAS/C Development System produce icons for most files that they generate. The sc: icons drawer contains template icons used by these tools. The icons in this drawer all have names starting with def_. With the exception of def_exe and def_se, the letter or letters after the def_ represent the file extension of the files for which the icon is intended. For example, the def_c icon is the icon for files that end in .c (C source files), and the def_h icon is the icon for files that end in .h (C header files). If a file does not have an extension (that is, the filename does not contain a period), the entire filename is used as an extension. Therefore, you can create a default icon for smakefile files called def_smakefile. If a SAS/C tool needs to create an icon, it copies the icon matching the file's extension from sc: icons to the correct directory and renames the icon to match the new filename. 26 Chapter 2 If you save a file for which the editor cannot find an icon in sc: icons, the editor uses the default icon def_se. Whenever the linker creates icons for executable modules (which do not have filename extensions), it uses the icon def_exe. The following table lists, for each tool that creates icons, the different types of items for which they create icons and the default icon each tool uses. Command Item Icon __________________________________________________ sc listing files def_lst object files def_o preprocessor output def_p generated prototypes def_h GST files def_gst slink executable programs def_exe map files def_map se any saved file def_se is used if the correct icon does not exist scsetup creates icons for any file with an extension for which an icon exists in sc: icons. By default, the SAS/C Development System does not create icons for object (.o) files. However, the compiler and assembler check for an icon called def_o when they create an object file. If you want to see icons for object files, create an icon named def_o. info using any icon editor and save it to the sc: icons drawer under the name def_o. To prevent all of the SAS/C commands from creating icons, rename the sc: icons drawer to sc: noicons or to any other name you like. If a tool cannot find the icons drawer, it does not create an icon. To prevent a specific type of icon from appearing, rename or delete the template for that icon from the sc: icons drawer. For example, if you do not want your header (.h) files to have icons, rename or delete the def_h icon. You can modify the icons in the sc: icons drawer in any way you choose. For example, you could replace the provided imagery with your own art work. For additional information on using icons, refer to the descriptions of the Information option or Information window in Using the System Software (Commodore-Amiga, Inc. 1990). 27 3 Getting Help 27 Introduction 27 Using the Help System 29 Contacting the Technical Support Division 29 Deciding When to Call Technical Support 30 Contacting Technical Support by Phone, Mail, or Fax 31 Contacting Technical Support through BIX 31 Contacting Technical Support through Internet or Usenet 33 Collecting the Information Needed by Technical Support Introduction This chapter describes how to get help with any of the features of the SAS/C Development System. You have three primary sources of help: [] Appendix 1, "Solving Common Problems." Appendix 1 describes solutions to the questions that users ask most frequently when they contact the Technical Support Division. This appendix also includes Questions that the Technical Support Division anticipates will be generated by the conversion to Version 6. [] The online help system. This system describes how to use each of the features provided by the SAS/C Development System. [] The Technical Support Division. You can contact the Technical Support Division if, for example, the compiler generates bad object code or error messages for correct code. Read the section "Contacting the Technical Support Division," later in this chapter, before contacting the Technical Support Division. Using the Help System The SAS/C Development System provides an extensive online help facility using the AmigaGuide hypertext system provided by Commodore. From within se, scopts, scmsg, and CodeProbe, you can display help information by pressing the Help key. Within CodeProbe, you can also enter the help command on the command line. Display 3.1 shows the help screen that is displayed when you press the Help key while inside se. 28 Chapter 3 Display 3.1 Editor Help Screen You can also display help inform ation by invoking the A migaGuide system directly with the following command: amigaguide database-name The help databases are located in the directory sc: help. You can specify one of the following databases: scmsg . guide describes the error and warning messages returned by the compiler. When you press the Help key from within scmsg, you are accessing this database. cpr.guide describes the purpose of and parameters accepted by each of the CodeProbe commands. When you press the Help key from within CodeProbe, you are accessing this database. se.guide describes how to use se. When you press the Help key from within the editor, you are accessing this database. sc_util.guide describes how to use each ofthe utilities provided with the SAS/C Development System. Getting Help 29 sc . guide describes each of the options you can specify in the sc command. When you press the Help key from within scopts, you are accessing this database. sc_lib.guide describes each of the library functions. This database also allows you to display lists of functions by category or view an alphabetical list of all functions. To navigate through a database, simply click on any of the buttons that appear on a screen or select an option from the menu bar. The menu bar on all of the help screens contains the following options: Contents displays the main help screen for the database that you are viewing. Index is a standard AmigaGuide option that is not used by the SAS/C Development System. Help displays information about using the help facility. Retrace backtracks through the help screens that you have already displayed. Browse < displays the previous screen in the database. Browse > displays the next screen in the database. To exit the help system, click on the Close gadget. Contacting the Technical Support Division When you purchased the SAS/C Development System, you received access to the SAS Institute Technical Support Division. Technical Support can help you with unexpected problems that might arise with the compiler. Technical Support also gathers users' comments on the current product and their suggestions for enhancements. Deciding When to Before you call the Technical Support Division, read through Appendix 1, Call Technical "Solving Common Problems." This appendix describes the solutions to Support several frequently encountered problems. If you cannot find the answer to your problem in Appendix 1, you may need to call Technical Support. The following list describes some of the more common situations for which you should call Technical Support: [] The compiler generates an error for code that is correct. [] The compiler does not generate an error or warning for code that is incorrect. 30 Chapter 3 [] The compiler generates bad object code. [] The compiler detects an internal error (CXERR) condition. [] The compiler or any utilities crash or end abnormally. [] The library functions or utilities do not perform as specified. [] The manuals contain errors or do not provide enough information. Contacting If you live in the United States, Europe, or Canada, you can contact the Technical Technical Support Division in writing, by phone, or by fax: Support by Phone, Mail, or Fax Address: SAS Institute Inc. ATTN: Amiga SAS/C Technical Support SAS Campus Drive Cary, North Carolina 27513 USA Phone: 919-677-8009 Fax: 919-677-8123 If you live in Australia, you should contact our Australian office: Address: SAS Institute Australia Pty. Ltd. ATTN: Amiga SAS/C Technical Support Private Bag No. 52 Lane Cove, NSW 2066 Phone: (02) 428 0428 Fax: (02) 418 7211 If you live in New Zealand, you should contact our New Zealand office: Address: SAS Institute (NZ) Ltd. ATTN: Amiga SAS/C Technical Support PO Box 10-109 The Terrace Wellington Phone: (04) 727 595 Fax: (04) 727 055 Getting Help 31 Whether you choose to call, send a letter, or send a fax, make sure you include or have with you all of the information described in the section "Collecting the Information Needed by Technical Support." Contacting BIX (Byte Information Exchange) is a subscription service bulletin board Technical system available to users in Canada and the Continental United States. Support through You can contact BIX at the following address: BIX Address: BIX/General Videotex Corporation 1030 Massachusetts Avenue Cambidge, MA 02138 USA Phone: 1-800-695-4775 (outside Massachusetts) 617-354-4137 (inside Massachusetts) You can sign up for a BIX subscription as follows: 1. Through a modem, dial BIX at 1-800-225-4129. 2. At the login: prompt, enter bix. 3. At the Name? prompt, enter bix.amiga. When you subscribe to BIX, you receive a user's manual that covers all aspects of their services, including: [] the various conferences available [] how to access a conference [] how to access source listings. SAS Institute maintains a support conference on BIX named sas.c. This conference is monitored Monday through Friday for new messages. You can contact Technical Support by posting messages to this conference. Note: Do not post your registration number to the public conference. You can also send private email messages on BIX to the ID sas.c (the same name as the conference). Whether you choose to post to the public conference sas.c or to send a private message, make sure you include all of the information described in the section "Collecting the Information Needed by Technical Support." Contacting You can also contact the Technical Support Division through Internet Technical using the EMITS (Electronic Mail Interface to Technical Support) facility. Support through Internet or Usenet 32 Chapter 3 EMITS logs your mail for the attention for the Technical Support Division and sends an email message acknowledging receipt of your mail. Before you can use this facility, you must register with EMITS. If you have accounts on multiple machines, register from the same host system that you want to use for sending messages to the Technical Support Division. EMITS extracts your email address from the header of your message and uses this address as your account ID. You may register from multiple machines if you want to send messages to Technical Support from more than one machine. Register with EMITS by sending the following information to support@sas.com: ./register=your name ./site=registration number ./company=company name or your name (if registering a private copy) ./phone=phone number Include the word EMITS in the subject of the message. Begin the ./ in column 1. Mail that does not include all of this information or that is syntactically incorrect is returned to you. Here are some examples: ./register=John Doe ./tsite=SAS-OOOOO1 ./company=Jane Doe ./phone=(555)555-5555 Note: Your phone number does not need to conform to this syntax. You can specify phone numbers in any form necessary. When your account has been added, EMITS notifies you by email and sends you a complete guide to using EMITS. There are several points to keep in mind when sending mail to EMITS. [] All email messages to EMITS should be sent to support@sas.com. [] All email messages intended for EMITS must contain the words EMITS in the subject. [] EMITS is not case sensitive. [] EMITS can process only one request for each email message you send. For example, send two separate email messages to support@sas . com to register and to request the help file. When you contact Technical Support through EMITS, make sure you include in your message all of the information described in the next section. Getting Help 33 Collecting the The Technical Support staff requires specific information before they can Information handle your questions. Include the following information in your Needed by correspondence, or have this information ready if you call: Technical Registration number Technical Support cannot answer any questions unless you provide a valid registration number. This number is found on a cardboard sheet included with the compiler documentation. The postcard that is part of that sheet should be torn loose and mailed to SAS Institute as soon as possible after purchasing the compiler. Please keep the other portion of that sheet with your documentation. If you have upgraded the compiler from an older, registered release, you do not need to send in the new card. If you decide to send in the new card, please note your old number, so that it may be removed from our database. If you do not know your registration number, please contact Book Sales at (919) 677-8000, extension 5042. If you purchased your copy of the compiler from someone who has already registered with us, please contact Book Sales with the following information: [] the name, address, phone number, and registration number for the previous owner, so that their name may be removed from our database. [] your name, address, phone number, and registration number so that you may be added to the database and become eligible for Technical Support. Version number The version number of the compiler is displayed in the header that appears on the screen each time you run the compiler. You can also display the version number with the AmigaDOS version command. Return address and phone number If you send a letter or fax, include your return address in the correspondence--not just on the envelope. Whether you call or write, Technical Support will need a phone number where you can be reached from 9:00 am to 5:00 pm EST. Complete problem description Include all error messages and symptoms of the problem. If you are not able to call when you have access to your machine, write down the following information before contacting Technical Support: [] the exact text of any error messages, guru meditation numbers, and so on, that you see on the screen [] whether the problem occurs when you are compiling, linking, or executing your program 34 Chapter 3 [] any commands, options, or code needed to consistently reproduce the problem (for example, compiler or linker options and CodeProbe commands). [] any parts of the product that you chose not to install. [] the configuration of your machine, including the type of processor, the amount of memory, and the version of the AmigaDOS operating system. If you have problems with a large piece of code, try to isolate the code that is causing the problem into a test case of 30 lines or less. Technical Support staff can respond faster if you can reduce the problem to a small test case. 35 [] Part 2 Using the Screen Editor (se) Chapters 4 Using se 5 Controlling se 6 Customizing the Editor 7 Using the AREXX Interface to se 36 37 4 Using se 37 Introduction 38 Starting the Editor 39 Reading the Status Line 40 Moving Around in a File 40 Entering and Editing Text 41 Searching for and Replacing Character Strings 43 Working with Blocks of Text 44 Undoing Your Last Change 45 Using Keystroke Macros 46 Entering Control Characters 46 Saving Your File and Exiting se 47 Managing Windows 48 Compiling from within the Editor 48 Getting Help Introduction This chapter describes how to use the editor, se. Specifically, this chapter describes how to: [] invoke the editor [] insert text into and delete text from a file [] search for and replace character strings [] create and use keystroke macros [] save your file and exit the editor [] open, close, and switch between windows [] compile your program from within se [] get help from within se. This chapter describes the most commonly used features of se. It does not cover all of the commands available or all of the ways in which you can execute commands. Chapter S, "Controlling se," contains comprehensive lists of the commands available in se. Note: The instructions in this chapter assume that you are using the default keystroke definitions. If you have customized your key definitions with the se configuration window, use your customized keystrokes when required. 38 Chapter 4 Starting the Editor You can start se by: [] double-clicking on the Edit icon. [] entering the se command at the Shell prompt. The se command has the following format: se [option] [filename]... where option is one of the following: -v displays the se version number and copyright statement and exits se. If you specify the -v option, se ignores anything else you specify in the se command. You need the version number from this display if you call the Technical Support Division for help with se. -dfilename uses the data file that you specify instead of se . dat. This file contains keyboard definitions and default information, including color, window size, and so on. When you start the editor, se looks for a data file. By default, se looks for se . dat in env: sc and, if it does not find the file, se looks in sc: env. You can tell se to use a different data file by specifying the filename with the -d option. If you start se by double clicking on the Edit icon or by entering the se command without a filename, se displays an empty edit window. When you start se from the Shell prompt, you can specify the names of the files that you want to edit. If you specify more than one filename, se opens a window for each file. se displays the first file in the top window and the second file in the bottom window. If you enter more than two filenames, you must press the F6 (cycle windows) key to display the additional files. You can specify up to nine filenames on the se command line. For example, you can edit the files hello.c and example.c from the sc/examples directory by entering the following commands: cd sc:examples se hello.c example.c Display 4.1 shows the two edit windows displayed by se. Using se 39 Display 4.1 Editing hello.c and example.c At the bottom of each edit window is a status line that shows, among other things, the name of the file in that window. The last two lines on the screen are the lines that se uses to display messages and to prompt you for additional information. You can have up to nine files open at one time. To open an additional file, select Open Window from the Windows pull-down menu. se asks you for the file that you want to open. If you are running AmigaDOS 2.0, se displays a file requester. Each open file is displayed in a different window, and you can switch between files by selecting Switch Windows from the Windows pull-down menu. The current window is the window that contains the cursor. The default text window size is 20 lines by 78 columns. You can set each window to occupy a half screen or a full screen by selecting Toggle Display Size from the Windows pull-down menu. Reading the Status Line The status line contains the following items: [] current line number. [] current column number. If you turn on the Column Display option from the se configuration menu, se displays the current column number in the status line. Chapter 6, "Customizing the Editor," describes how to use the se configuration menu. 40 Chapter 4 [] current filename. [] the current mode. You can switch between two modes, insert mode and overwrite mode, by pressing the Insert key (NUM-O). In insert mode, any character you enter is inserted at the current cursor position. In overwrite mode, any character you enter replaces the character at the current cursor position. [] window number. se displays the window number within braces. For example, for window number 2, se displays ( 2 ). [] keystroke saver active indicator. By default, the Alt-n key sequence starts recording your keystrokes in that macro. On the status line, se displays the number n that you entered. For more information on creating keystroke macros, see "Using Keystroke Macros," later in this chapter. [] marked block indicator. When you mark a block of text, se displays [*] in the status line. The section "Working with Blocks of Text," later in this chapter describes how to mark a block of text. Moving Around in a File In addition to the arrow keys, you can use the following keys to move around in your file: Home (NUM-7) moves the cursor to the beginning of the current line End (NUM-1) moves the cursor to the end of the current line Control-Home moves the cursor to the beginning of the file Control-End moves the cursor to the end of the file PgUp (NUM-9) displays the previous page of text PgDn (NUM-3) displays the next page of text. Entering and Editing Text The following paragraphs describe the most common commands used to insert and delete characters. se offers many more commands that are described in Chapter 5, "Controlling se." When you first open your file, you are in insert mode. Any character that you enter is inserted at the current cursor position. If you press the Using se 41 Insert key, se switches to overwrite mode, and any character you enter replaces the character at the current cursor position. Each time you press the Insert key, you switch modes. As stated previously, the default window width is 78 columns. The maximum line length in se is 256 characters. If you have not selected Autowrap from the Options pull-down menu in the se configuration menu, then se does not automatically start a new line when you type past column 78. Instead, se moves the text to the left so that you can still see what you are typing. When you press Return, se redisplays the window beginning with column 1 and displays a greater than (>) sign at the right side of the screen on the line that exceeds 78 columns. (For more information about the Options pulldown menu, see Chapter 6, "Customizing the Editor.") You can use the following keys to delete text: Backspace deletes the character to the left of the cursor Delete deletes the character at the cursor position Control-Y deletes the current line Control-E deletes all characters from the current cursor position to the end of the current line. If you decide you want to restore the last line that you deleted with Control-Y, press Alt-Y. Searching for The following sections describe the Search command and the Search and and Replacing Replace command. To use these commands, you can enter strings as Character Strings regular expressions or as simple character strings. By default, se expects you to enter regular expressions. Regular expressions are character strings that may contain characters that have special meanings. For example, abcd, a little lamb, and [tT]+he$ are all valid regular expressions. "Entering Regular Expressions," later in this chapter, provides additional information on using regular expressions under se. If you select String Matching as the Searches Method in the se configuration menu, then se interprets any special regular expression symbols as plain text. Searching for Character Strings To search for a character string, press Right Amiga-F. se asks you to enter the string for which you want to search: REGULAR EXPRESSION SEARCH STRING: (MENU KEY to search backwards) To search forward (from the current position toward the end) through the file, type the character string and press Return. 42 Chapter 4 Note: The Search and Search and Replace commands are case- sensitive. Enter the character string exactly as it appears in the file. To search backward (from the current position toward the beginning) through the file, press the F2 key, and se displays the following prompt: (BACKWARDS) REGULAR EXPRESSION SEARCH STRING: Type the character string and press Return. After you press Ruturn, se positions the cursor at the first occurrence of the character string. To repeat the search, press Right Amiga-A. Replacing Character Strings To replace one character string with another character string, press Right Amiga-R. se displays the same prompt as if you had pressed Right Amiga-F. You can type the character string that you want to replace and press Return, or you can press the F2 key if you want to search backward through the file. If you press F2, se displays the same prompt as if you were simply searching for the string, and you should type the character string that you want to replace and press Return. After you enter the character string for which you want to search, se prompts you for a second character string: REPLACE STRING: Type the string with which you want to replace the first character string and press Return. se then asks you if you want to be prompted before it replaces any occurrences of the first string with the second string: REPLACE: Prompt No Prompt If you want se to ask you before it replaces any strings, select Prompt. (Use the arrow keys to highlight Prompt and press Return, or press the letter p.) If you select No Prompt, se replaces all occurrences of the first string with the second string from vhe current position through the remainder of the file. (That is, to the end of the file for a forward search or to the beginning of the file for a backward search). If you select Prompt, se positions the cursor at the first occurrence of the character string, and asks you what you want to do: REPLACE: Yes No Quit Global Using se 43 Select one of the options: Yes replaces the string and positions the cursor at the next occurrence of the character string. No moves the cursor to the next occurrence of the character string. Quit stops the search and replace without replacing any strings. Global replaces all remaining occurrences of the string without displaying any prompts. You can highlight your selection by pressing the arrow keys or by pressing the first letter of the option. Entering Regular Expressions As previously stated, regular expressions are character strings that may contain characters that have special meanings. Regular expressions are also referred to as patterns. Refer to the section "Specifying the Pattern" in the description of the grep utility in`SAS/C Development`System User's Guide, Volume 2: Debugger, Utilities, Assembler, Version 6.0 for a complete description of entering regular expressions. se supports regular expressions in the same manner as grep except that you do not need to enclose in double quotes (") a string that contains spaces. For example, to search for the string a little lamb, you would enter a little lamb instead of "a little lamb". Working with You can copy, delete, move, print, and write entire blocks of text within Blocks of Text the same file, between different files, or to and from the clipboard. To perform an operation on a block of text, you must first mark the block. You can mark a block of text in one of two ways: [] Position your cursor on the first character that you want included in the block, and press Control-[. se displays a left bracket in the status line. Then, position your cursor after the last character that you want included in the block, and press Control-]. [] Position your mouse cursor on the first character that you want included in the block, and press and hold down the left mouse button. Move the mouse cursor to the last character that you want included in the block, and release the mouse button. se displays the marked block in reverse video and displays [*] in the status line. You can have only one marked block at a time. After you have marked a block, you can delete or print the block by selecting the appropriate option from the Block pulldown menu. You can move or copy the block to another open file by positioning the cursor at 44 Chapter 4 the location to which you want to move or copy the block and selecting the appropriate option from the Block pull-down menu. You can also use the keyboard shortcuts displayed beside the menu selection. To write the block to a file that is not open, select the Write option from the Block pull-down menu. se asks you to enter the name of the file to which you want to write the text: WRITE BLOCK TO FILE: Filename Type the appropriate filename and press Return. se writes the block to the filename you enter. The block text replaces any text that is already in the file. If you mark a block of text and then decide that you do not want to perform any operations on the block, you can unmark the block by pressing Control-[, then Control-] without moving the cursor. Note: The Read option in the Block pull-down menu performs the same function as the Insert File option in the Project menu. Undoing Your se remembers the changes you entered for the last 50 lines that you Last Change changed, inserted, deleted, and so on. You can undo these changes with the undo command. You can run the undo command in any of three ways: [] press Right Amiga-U [] press Control-U [] select Undo Last Change from the Project menu. When you select the undo command, se displays a prompt depending on the last command you entered: UNDO -- DELETE INSERTED LINE?: Yes No UNDO -- DELETE ADDED BLOCK?: Yes No UNDO -- RESTORE DELETED BLOCK?: Yes No UNDO -- RESTORE DELETED LINE?: Yes No UNDO -- RESTORE REPLACED LINE?: Yes No Select the appropriate answer and press Return. Note: se remembers changes for the last 50 lines only. If you delete or add a block of text larger than 50 lines, se remembers only the first 50 lines. Using se 45 Using Keystroke If you need to perform repeatedly a task that requires several keystrokes, Macros you may want to create a keystroke macro to do the task. If you save your keystrokes as a macro, then you can perform the task by pressing only the Alt key and a function key. Creating and Replaying Keystroke Macros To create a keystroke macro, hold down the Alt key and press a number (0-9) key (for example, Alt-O). The number that you press is displayed in the right side of the status line between the window number and the marked block indicator (if present). se displays the following message: Key Saver Begun Note: If you press 0, the status line shows the number 10. From this point, all of your keystrokes are stored as part of the macro. Enter all of the keystrokes necessary to perform the task. After you have completed the task, press Alt and the same number key again to stop recording keystrokes. To execute, or replay, the macro, press Alt-Fn, where n is the number you pressed to define the macro (for example, Alt-F10). Any macros you define are saved until you exit from se. The following section, "Saving and Reloading Keystroke Macros," describes how to save keystroke macros in a file and reuse them later. Saving and Reloading Keystroke Macros If you do not save your keystroke macros in a file or convert them to a key as described under "Assigning a Macro to a Different Key," they are lost when you complete your editing session and terminate se. To save your keystroke macros in a file, select the Save Macros option from the Project pull-down menu. se prompts you for a filename in which to save the macros: SAVE MACRO FILE: SPECIFY MACRO FILENAME (default is SE.MAC) Type a filename and press the Return key. To reuse your macros, select the Load Macros option from the Project pull-down menu. se prompts you for the name of the file in which you saved the macro definitions: LOAD MACRO FILE: SPECIFY MACRO FILENAME (default is SE.MAC) 46 Chapter 4 Type the filename and press the Return key. The file that you specify is loaded over any macro files that you may have already loaded. se does not check the file to determine if the file is a valid macro file. Assigning a Macro to a Different Key When you create a keystroke macro, that macro is assigned to one of the 10 possible Alt-Fn key sequences. If necessary, you can assign one or more of the macros to a different key sequence. For example, you may want to assign the Alt-F10 macro to Control-Z. After you assign a macro to a key, you can edit and save the macro using the se configuration window. To assign a keystroke macro to a different key sequence, select the Convert Macro to Key option from the Options pull-down menu. se asks you to enter the macro number: Enter the macro number to convert to a key(l-10) Type the appropriate number and press Return. To convert macro number 10, type the number 10, not just a 0 as you did when you created the macro. se displays the keymap portion of the configuration window. Select the key sequence to which you want to assign the macro by clicking on or pressing the appropriate keys such as the Control key and the letter Z. After you have selected the keys, click on the Close gadget. To save the macro assignment for your next editing session, you must redisplay the se configuration menu by selecting the Configuration Window option from the Options pull-down menu. Then, click on the Save gadget or select the Save As option from Project pulldown menu. Entering Control You can enter control characters into your text file by preceding the Characters control character with the se escape character, Control-\. For example, to enter a form feed character into your text file, press Control-\ Control-L. Saving Your File and Exiting se After you have finished editing your file, you can save the file, exit the file without saving your changes, and/or exit se. You cannot save an unnamed file. If you started se by double clicking on the Edit icon or by entering the se command without a filename, then you must name the file before you can save it. To name the file, Using se 47 select the Rename option from the Project pulldown menu. se asks you to enter a filename: ENTER NEW FILENAME for current file: Type the appropriate filename and press Return. You can now save the file and quit se. To save your file and/or quit the editor, select the appropriate option from the Project pull-down menu: Save & Close saves your file and closes the current window. If you have only one window open, this option also terminates se. If you have more than one window open, the next window becomes the current window. Close Window closes the current window. This option does not save your file. If you have only one window open, this option also terminates se. If you have more than one window open, the next window becomes the current window. Save & Continue saves your file. This option does not close any windows. Save & ReOpen saves and closes your file, then asks you for the name of a new file to edit. This option does not open an additional window to edit the new file. Exit SE terminates the editor. This option does not save your file. You may also use the keyboard shortcuts displayed beside the menu options. Managing Windows In se, you can have up to nine files open at one time, and each open file is displayed in a different window. To open an additional window, select the Open Window option from the Windows pull-down menu. se asks you for the name of the file to read into the new window: OPEN WINDOW: Filename (Menu Key for view mode only) Type the appropriate filename and press Return. 48 Chapter 4 If you have only one window open, that window occupies the entire screen. By default, if you open two or more windows, se displays two windows at a time in split-screen mode. In split-screen mode, each window occupies half of the screen. Display 4.1, earlier in this chapter, shows two windows in split-screen mode. In split-screen mode, you can move between the two currently displayed windows by pressing Control-F6. Within the same window, you can cycle through the remaining (hidden) windows by pressing F6. To switch between split-screen mode and full-screen mode, select the Toggle Display Size option from the Windows pull-down menu. To display the names of each open file, select the Display Names option from the Project pull-down menu. Compiling from within the Editor Before you compile your program, make sure that you have the correct options specified in scopts. To specify compiler options from within se, press Control-F4 to run the scopts utility. If you change any settings, save the new settings before exiting scopts. To compile your program, press F4. se displays a message telling you that your program is compiling. If the compiler finds any errors in your program, it sends the errors to the scmsg utility, and scmsg displays the errors in the Message Browser window. To locate the line causing an error, double-click on the error message. To move to the next error, press F5. For additional information on using the scmsg and scopts utilities, refer to Chapter 2, "Using Your SAS/C Development System," or to the description of the scmsg utility in SAS/C Development System User's Guide, Volume 2. Getting Help To display help in se, press the Help key or press F1. se displays either the SAS/C Screen Editor Help menu or context-sensitive help information for the command you are executing. Chapter 3, "Getting Help," describes how to use the help system. 49 5 Controlling se 49 Introduction ` 50 Selecting Menu Options 51 Moving Around in the File 52 Inserting Text 52 Delehng Text 53 Working with Blocks of Text 53 Searching for and Replacing Strings 54 Managing Windows 54 Changing Colors 55 Creating and Using Keystroke Macros 55 Editing a New File 56 Naming Files 56 Undoing Changes 56 Saving Your File and Exiting the Editor Introduction This chapter describes all of the commands available within se and how to invoke each command. Some of the commands listed in this chapter are described in more detail in Chapter 4, "Using se." Note: This chapter describes the default keystroke definitions. If you have customized your key definitions with the se configuration window, substitute your customized keystrokes when necessary. The first section in this chapter, "Selecting Menu Options," describes the different ways in which you can select options. The remaining sections describe the options and commands you can use to perform specific tasks: [] moving around in a file [] inserting text [] deleting text [] marking, copying, deleting, and moving blocks of text [] searching for and replacing character strings [] opening, closing, and changing windows [] creating and using keystroke macros [] editing a new file [] saving your file and exiting the editor. 50 Chapter 5 Each section includes a table that shows, for each specific task, which keys/options to press/select to perform the task. For example, to move to a specific line in your file, you can: [] Press Control-L. [] Press Right Amiga-L. [] Select the Line Number option from the Search pull-down menu. Selecting Menu Options You can select an option or enter a command in one of three ways: [] Select an option from a pull-down menu. [] Enter the appropriate accelerator key for the option or command. Many of the menu options are also associated with menu accelerator keys (also called keyboard shortcuts). These shortcuts are displayed to the right of the option in the pull-down menus. For example, the keyboard shortcut for the Save & Close option in the Project menu is Right Amiga-S. [] Select an option from the abbreviated menus displayed with the F2 (Main Menu) key. If you press the F2 key, se displays an abbreviated menu of the most frequently used commands at the bottom of the screen: COMMAND: B C F H L O P R S Q U Each of these options either displays a submenu or executes a command. For example, B displays the Block menu, and Q exits the editor. To display a brief description of an option, move the cursor to that option. se also provides context-sensitive help that describes each command in detail. To display help information, press the Help key. Controlling se 51 Moving Around in the File The following table lists the keys/options that you can use to move around in your file. Task Key Menu/Option ______________________________________________________________________________ Move up one line Up arrow Move down one line Down arrow Move left one character Left arrow Move left one word Control-Left arrow Shift-Left arrow Move right one character Right arrow Move right one word Control-Right arrow Shift-Right arrow Go to a specific line Control-L Search/Line Number Right Amiga-L Go to the beginning of the line Home Go to the end of the line End Go to the top of the file Control-Home Go to the end of the file Control-End Move up one page PgUp Move down one page PgDn Scroll the text up Control-6 Scroll the text down Control-V Go to the beginning of a marked block Block/Beginning Go to the end of a marked block Block/End 52 Chapter 5 Inserting Text The following table lists the keys and options that you can use to insert text into your file. Task Key Menu/Option ____________________________________________________________________________ Switch between Insert and Overwrite modes Ins Insert a line before current line Control-I Restore deleted line Alt-Y Enter control characters Control-\c Insert a file at current position Project/Insert File Deleting Text The following table lists the keys/options that you can use to delete text from your file. Task Key Menu/Option _____________________________________________________________________________ Delete current character Del Delete previous character Backspace Delete word Control-W Delete line Control-Y Delete from cursor position to end of line Control-E Delete a marked block Right Amiga-D Block/Delete Controlling se 53 Working with Blocks of Text The following table lists the keys/options that you can use to mark, copy, move, insert, and delete blocks of text. For a more detailed description of these commands, see Chapter 4, "Using se." Task Key Menu/Option _______________________________________________________________________ Mark beginning of block Control-[ Mark end of block Control-] Copy a marked block Right Amiga-C Block/Copy Delete a marked block Right Amiga-D Block/Delete Move a marked block Right Amiga-M Block/Move Print contents of a marked block Block/Print Read a disk file into the editor window Block/Read Write contents of marked block to a file Block/Write Go to the beginning of a marked block Block/Beginning Go to the end of a marked block Block/End Searching for and Replacing Strings The following table lists the keys/options that you can use to locate character strings and to replace a string with another string. For a more detailed description of these commands, see Chapter 4, "Using se." Task Key Menu/Option ___________________________________________________________________________ Search for a character string Control-S Search/String Search Right Amiga-F Replace one character string with another Control-R Search/Search and Replace Right Amiga-R Repeat last search or replace command Alt-S Search/Search Again Right Amiga-A 54 Chapter 5 Managing Windows The following table lists the keys/options that you can use to open, close, and cycle through windows. Some of these commands are described in more detail in Chapter 4, "Using se." Task Key Menu/Option ________________________________________________________________________ Switch window (in split-screen mode) Control-F6 Windows/Switch Windows NUM-S Cycle windows (in full-screen mode) F6 Change window size F9 Windows/Toggle Display Size Switch between 20 lines and 45 lines NUM Enter Windows/Interlace Toggle Right Amiga-H Open new window Control-O Windows/Open Window Open a new Shell Control-F Windows/Create New CLI Move window front to back F10 Close a window Right Amiga-Q Project/Close Window Changing Colors The colors used in the se windows are based on your Workbench colors. You can change the way the Workbench colors are used in the se windows with the keys listed in the following table. These keys allow you to cycle through the foreground and background colors. Task Key ________________________________________________________________ Cycle foreground colors F7 Cycle background colors F8 Controlling se 55 Creating and Using Keystroke Macros The following table lists the keys/options that you can use to create, save, and load keystroke macros. For a more detailed description of these commands, see Chapter 4, "Using se." Task Key Menu/Option ___________________________________________________________________________ Start/stop saving keystrokes Alt-n Execute a keystroke macro Alt-Fn Save macros in a file Project/Save Macros Load macros from a file Project/Load Macros Assign keystroke macro to a different key Options/Convert Macro to Key Editing a New File The following table lists the keys/options that you can use to open new files. For a more detailed description of these commands, see Chapter 4, "Using se." Task Key Menu/Option _________________________________________________________________________ Save current file and edit new file Right Amiga-N Project/Save & Reopen Open a new file in the current window Right Amiga-O Project/Open New Window Open a new file in a new window Control-O Windows/Open Window 56 Chapter 5 Naming Files The following table lists the keys/options that you can use to change the names of files from inside se. For a more detailed description of these commands, see Chapter 4, "Using se." Task Menu/Option Rename current file Project/Rename Display names of files being edited Project/Display Names Undoing Changes The following table lists the keys/options that you can use to undo your last change. Note: The action taken by the Undo Last Change option depends on the last command you entered. For a complete description of this option, see Chapter 4, "Using se." Task Key Menu/Option ______________________________________________________________________ Restore the last line you deleted Alt-Y Undo last change Control-U Project/Undo Last Change Right Amiga-U Saving Your File and Exiting the Editor The following table lists the keys/options that you can use to save your file and exit the editor. For a more detailed description of these commands, see Chapter 4, "Using se." Task Key Menu/Option __________________________________________________________________________ Save the file in the current window Right Amiga-W Project/Save & Continue Save the file and close the current window Right Amiga-S Project/Save & Close Save current file and edit new file Right Amiga-N Project/Save & Reopen Exit the editor without saving your file F3 Project/Exit SE Right Amiga-X 57 6 Customizing the Editor 57 Introduction 57 Displaying the Configuration Window 59 Displaying Key Definitions 60 Setting Key Definitions 61 Setting Tab Stops 61 Setting Other Options 64 Saving the New Settings 64 Reusing Saved Settings Introduction This chapter describes how to use the se configuration window. The configuration window allows you to set options and change the functions assigned to different keys and key combinations (sequences). For example, you can do the following: [] set the input processing mode [] set tab stops [] set automatic indention [] specify whether searches are to be simple string searches or pattern searches [] change the command assigned to a key or key combination. Displaying the Configuration Window To display the se configuration window shown in Display 6.1, open the Options pull-down menu on the se menu bar, and select the Configuration Window option. (Alternatively, you can press Control-M.) 58 Chapter 6 Display 6.1 se Configuration Window To display the configuration window menu bar, press and hold the right mouse button. The menu bar contains six pull-down menus: Project contains options that allow you to save any changes you make while in the configuration menu or to quit the configuration window without saving your changes. The sections "Saving the New Settings" and "Reusing Saved Settings," later in this chapter, describe how to use the Project menu. Options allows you to specify several options that determine how the editor works. For example, you can specify how tab characters are processed, whether Search and Replace commands are case sensitive, whether the se status line shows the current column number, and so on. The section "Setting Other Options," later in this chapter, describes how to use this option. Keys 1-4 lists the different commands that you can assign to a key or key combination. The following sections "Displaying Key Definitions" and "Setting Key Definitions" describe how to use these menus. Customizing the Editor 59 Displaying Key Definitions To display the command assigned to a key or key sequence, you can [] click on that key or key sequence in the keymap. [] press that key, if the key is a qualifier key. Qualifier keys are keys that modify the function of other keys, such as the Control key, the Alt key, the Shift key, and so on. For example, to display the definition of Control-F4 as shown in Display 6.2, click on the Ctrl key and the F4 key. Display 6.2 se Configuration Window Showing Ctrl-F4 The name of the key or key sequence appears in the Key Name field, CTRL F4, and the command assigned to the key appears in the text gadget below the Key Name, CO. To determine the function of a specific command, open the Keys pull- down menus. These menus contain the explanations of each of the commands that you can assign to a key or key sequence. For example, the Keys 2 pulldown menu shows the function of the CO command as Set SC Options. The configuration screen also displays the raw code and qualifier associated with a specific key combination. 60 Chapter 6 Raw code is a hexadecimal code associated with a specific key on the keyboard by the hardware. The AmigaDOS operating system uses keymaps to convert this raw code into a recognizable character. Qualifier indicates which qualifier keys are part of a key sequence. As stated before, qualifier keys are keys that modify the function of other keys, such as the Control key, the Alt key, the Shift key, and so on. The raw codes and qualifiers are displayed for reference only. For more information about raw codes and qualifiers, refer to the description of keyboard.device in Amiga ROM Kernel Reference Manual: Devices, 3rd Edition (Commodore-Amiga, Inc. 1991). After you have displayed a key definition, you can press Return to unselect the key, clear the text gadget, and remain in the configuration program. You can also select CANCEL or click on the Close gadget to exit the configuration program. Setting Key Definitions By default, the left and right Alt keys are equivalent. For example, Left Alt-y performs the same function as Right Alt-y. You can choose to make the left Alt and right Alt keys work independently. That is, you can choose for the left Alt-y key sequence to perform a different function than the right Alt-y sequence. Similarly, you can choose for the left and right Shift keys to work independently. To make the left and right Alt keys or Shift keys work independently, click on the check box next to ALT L = R or SHIFT L = R in the bottom right of the configuration screen. The left and right Amiga keys function independently. You cannot make these keys function equivalently. Caution Do not define the Control, I-ight Amiga key, left Amiga key sequence. This key combination reboots the machine. To set or change the definition of a key or key sequence, follow these steps: 1. Select the key or key sequence by clicking on the appropriate keys. For example, to assign a command to the key sequence Control-C, press or click on the Control key and the C key. 2. Enter the command code in the text gadget. You can type in the command code, or you can select the code from the Keys pull-down menus. Press Return after entering the command code. For example, to assign the CW (Change Window) command to Control-C, Customizing the Editor 61 type in CW and press Return, or select cw from the Keys 2 menu and press Return. You can repeat this step as many times as necessary to create complex key definitions. 3. Save the new settings as described in "Saving the New Settings," later in this chapter. Setting Tab Stops By default, tab stops are set at every eighth character, as shown in Display 5.1. You can clear all tab stops by clicking on the Clear tabs gadget. To set a tab stop, point and click to the place on the tab bar where you want to set a tab stop. An uppercase T indicates where a tab stop has been set. To delete a single tab stop, point and click at the tab stop. After you have set at least two tab stops, you can set a series of tabs at equidistant intervals, using the Repeat tabs gadget. When you click on the Repeat tabs gadget, the configuration program calculates the interval between the last two tab stops you entered, and sets tab stops for the remainder of the tab bar using that interval. Save the new tab stops as described in "Saving the New Settings," later in this chapter. Setting Other Options The Options pulldown menu in the configuration menu allows you to specify several parameters, including how your input is processed, how the Search and Replace commands work, whether the editor saves backup files, and so on. The following list describes each of the options in the Options pull-down menu. If you change any of the options in the Options pulldown menu, you must save your changes as described in "Saving the New Settings," later in this chapter. Input Processing controls the mode in which you enter text into se. You can choose from five modes: No processing does not convert anything to uppercase or insert carriage returns when you reach the right margin. You must press Return at the end of each line. Asm modes are designed to make entering assembly language code easier. In the assembly language modes, the editor uses the tab stop settings to determine the start of the 62 Chapter 6 next field. In Asm mode 1, the editor converts anything you enter in field 1 into uppercase. In Asm mode 2, the editor also converts anything you enter in field 2 into uppercase, and in Asm mode 3, it also converts anything you enter in field 3. The editor does not convert anything entered on a line after you enter a comment character (; or *). In any of the assembly language modes: [] When you enter a colon (:), space, or tab character into the first field, the cursor moves to the second field. [] When you enter a space or tab character into the second field, the cursor moves to the third field. If you enter a comment character (; or *), the cursor moves to the comment field. [] When you enter a comment character into the third field, the cursor moves to the comment field. You can enter a comment character into the text without causing the cursor to move to the comment field by preceding the comment character with a backslash (\). Autowrap inserts carriage returns into the text when you reach the right margin. When the word you are entering extends past the right margin, the entire last word is moved to the next line. The default setting is No processing. This option affects only the current window. Tab Expansion Method specifies whether tab characters are converted to spaces (Expand Tabs to Spaces) or left as tab characters (Use TAB Character) . Only the tab characters that are entered while Expand Tabs to Spaces is active are converted to spaces. Tab characters that already exist are not converted when you select Expand Tabs to Spaces. The default setting is Use TAB Character. This option affects only the current window. Auto-Indent Mode is designed to make entering C source code easier. When auto-indent mode is on, new lines are indented depending on the following criteria: [] If the previous line contains an open brace ({), the new line is indented one tab stop to the right of the previous line. Customizing the Editor 63 [] Otherwise, if the character is a close brace (}), the new line is indented one tab stop to the left of the previous line. [] For any other character, the new line is indented to the same position as the previous line. The default setting is On. This option affects only the current window. Column Display specifies whether the column number is displayed on the status line. The default setting is Off. This option affects all windows. Prompt Before Undo specifies whether you are asked to confirm each undo command. The default setting is On. This option affects all windows. Backup File Mode specifies how you want the editor to deal with backup files. You can specify one of the following: [] No Backup File indicates that you do not want the editor to save backup copies of each file that you edit. [] Place Backup File in Backup Dir specifies that you want the editor to save a backup copy of each file that you edit using the same filename and extension in a different directory. If you select this option, the configuration program asks you for the name of the backup directory. [] Rename Backup with Backup Ext specifies that you want the editor to save a backup copy of each file that you edit using the same filename in the same directory as the original file but with a different filename extension. If you select this option, the configuration program asks you to enter the backup file extension. The default setting is No backup file. This option affects all windows. Searches Method specifies whether the Search and Replace commands should treat the search patterns you enter as simple character strings (String Matching) or as regular expressions (Use Regular Expressions). If you choose to Use Regular Expressions, you should enter search patterns as described in the description of the grep utility under "Specifying the Pattern" in SAS/C Development System User's Guide, Volume 2: Debugger, Utilities, Assembler, Version 6.0. The default setting is Use Regular Expressions. This option affects all windows. Case Sensitive Characters specifies whether the Search and Replace commands are sensitive to case. For example, if this option is On and you specify a search pattern in lowercase, the Search command will not locate the same 64 Chapter 6 pattern in the file if the pattern occurs only in uppercase. The default setting is On. This option affects all windows. Saving the New Settings To save any changes you make using the configuration window, select the Use, Save, or Save As options. [] Select USE to save the settings to the environment variable sc/se.dat in ENV:. Settings saved to ENV: are active until you reboot your system. [] Select SAVE to save the settings to ENV: and ENVARC: (the equivalent of ENV: on disk). Settings saved to ENVARC: are copied to ENV: each time you boot your system. [] Select the Save As option to save the settings in a file in the current directory. The configuration program asks you to enter a filename in which to save these settings. If you click on the Close gadget without selecting the Use, Save, or Save As option, the new settings are active for your current se session only. Reusing Saved Settings If you use the Save As option to save your configuration settings, you can reload these settings later by selecting the Open option from the Project menu. The configuration program asks you to specify the filename to which you saved the settings. Enter the filename to which you saved the settings. To make the settings active, you must click on the SAVE or USE gadget. 7 Using the AREXX Interface to se 65 Introduction 65 Executing A Series of Editor Commands 68 Communicating with External Programs 69 AREXX Macros Provided with the Compiler 70 AREXX Command Summary Introduction This chapter describes the AREXX interface that is available in the se editor. AREXX is a script language commonly used for interprocess communication on Amiga hardware. AREXX comes with Version 2.0 of the AmigaDOS operating system and can be purchased separately from Commodore for Version 1.3. For more information about using AREXX, refer to Using the System Software (Commodore-Amiga, Inc. 1990) if you are running the AmigaDOS operating system, Version 2.0 or to the documentation that comes with the AREXX package if you are running AmigaDOS operating system, Version 1.3. You can use the AREXX interface to do the following: [] execute a series of editor commands that are too complex to assign to a keystroke macro [] communicate with external programs. Executing A Series of Editor Commands Sometimes you need to perform an action that is more complex than se can handle with simple keystroke macros. For example, you may need to use programming logic such as an if-then-else construction. You can create an AREXX macro to perform the action, and then you can assign that macro to a key. AREXX macros are files that contain AREXX commands. AREXX macros that are to be used with se must have a filename with a .se suffix. Tables 7.1 and 7.2 in "AREXX Command Summary," later in this chapter describe each of the commands supported by AREXX. As you enter AREXX commands, separate each command with a space. You can string multiple commands together. 66 Chapter 7 If you are passing characters to a command prompt, you must terminate the string with a newline character, \n. For example, the following command issues the Open Window command, enters f oo for the filename, and terminates the string with a carriage return: /* Issue the Open Window command, */ /* type in "foo" for the filename, */ /* and terminate data entry with a carriage return. */ 'OW "foo\n"' If you do not specify the \n character, se waits until you type a carriage return before proceeding. After you have created your macro file, you can assign the macro to a key using the se configuration window. To display the se configuration window, select the Configuration Window option from the Options pull- down menu. Select the key to which you want to assign the macro by pressing or clicking on the appropriate key(s). Type the following Rexx Macro command in the text gadget and press Return: RM "macro-filename" The macro-filename is the name of the file containing your macro. If the name you specify does not end in .se, the editor appends . se to the filename when you invoke the macro. se searches for the macro file in the current directory, then in sc: REXX, and finally in REXX: . You can specify a fully-qualified pathname for the filename, if necessary. For example, suppose you have a series of #define statements in your program such as the following: #define FRED 1 #define BARNEY 4 #define WILMA 7 #define BETTY 8 You want to renumber these statements sequentially: #define FRED 1 #define BARNEY 2 #define WILMA 3 #define BETTY 4 Using the AREXX Interface to se 67 You could use the following AREXX macro. If invoked from se, this macro renumbers the last token on each line of a marked block. /* AREXX macro to renumber #define statements */ /* Tell SE to go to the Block Menu and select End. */ /* This effectively moves the cursor to the end of the */ /* current marked block. */ ' BN "En"' /* Ask SE for the line number of the current line. */ /* Assign the line number to the variable 'end'. */ options results 'GL' end = result options /* Tell SE to go to the Block Menu and seleet Beginning. */ /* This moves the cursor to the beginning of the marked */ /* block. * 'BM "B"' /* Ask SE for the text of the current line. */ /* Assign the text of the line to the variable 'line'. */ options results 'GT' options line = result /* Move the cursor to the end of the current line. */ 'EL' /* Back up one word */ 'PW' /* Get the index of the current position in the current */ /* line. This index can differ from the current column */ /* number if tab characters are present in the line. */ /* Assign the index to the variable 'index'. */ options results 'GI' options index = result 68 Chapter 7 /* Read the line and get the number at the end of it. */ /* Since the variable 'index' points to the first */ /* character of the number, the number consists of */ /* everything from the 'indexlth byte of the line to the */ /* end of the line. */ num = SUBSTR(Iine, index+l, length(line)-index) /* 'num' now contains the number at the end of the first */ /* line of the marked block. Move down a line, */ /* go to the end of the line, back up a word, and */ /* delete to the end of the line. The following */ /* sequence of four SE commands does this. */ 'NL EL PW DE' /* Loop until the end of the block, replacing the last */ /* token on the line with the appropriate number. */ do forever num = num + 1 /* Increment #define number */ num /* Insert the number as text */ options results /* Get the current line number */ 'GL' options if result >= end then exit(0) /* Exit if past the end */ 'NL EL PW DE' /* Go to next line and delete last token */ end Communicating with External Programs You can also use AREXX to communicate with other programs from within the editor. For example, you may want to send messages to the scmsg utility, which allows you to browse your error and warning messages. You can also invoke external commands that are unrelated to the editor or send AREXX commands to another program that has an AREXX port. Each program that has an AREXX port names its port so that other programs can find it. The name of se's AREXX port is SC_ SE. If more than one copy of se is running, only one copy will have an AREXX port. When you invoke an AREXX script from within an application, any external commands that the script attempts to execute are sent to the AREXX port of the application that launched it. Therefore, when se launches a script, it should send se commands as external commands. If the script wants to communicate with another utility, it should switch to that utility's AREXX port using the AREXX ADDRESS command. The Using the AREXX Interface to se 69 script can then send commands in whatever format required by that utility. To switch back to se, specify the ADDRESS command with "SC_SE" as its argument. For example, the following se script tells scmsg to go to the next error, then gets the information on the error, and positions the cursor on the correct line number. /* REXX script to advance to next error */ address "SC_SCMSG" /* Switch to the message browser. */ 'NEXT' /* Go to the next message on the list. */ options results /* Remember the results of commands. */ 'FILE' /* Get the filename of the next error. */ file = result 'LINE' /* Get the line number. */ line = result options address "SC_SE" /* Back to the editor now */ 'OW "' || file ||'\n"' /* Issue Open Window command */ 'LL "' || line ||'\n"' /* Issue Go to line command */ AREXX Macros Provided with the Compiler The SAS/C Development System provides seven AREXX macros that you can use from inside of se. The files for these macros are in sc: rexx. These macros are as follows: amigaguide.se displays the help information in the AmigaGuide databases in the sc: help directory. By default, this macro is assigned to Alt-D. When you invoke this macro, it asks you to enter the name of an AmigaGuide database. For a description of each of the AmigaGuide databases in the sc: help directory, see Chapter 3, "Getting Help." deletetabs.se converts all of the tabs within a marked block to spaces. By default, this macro is assigned to the asterisk (*) key in the numeric keypad (NUM ). findsym.se looks in the GSTs in memory for the definition of the symbol that is under the cursor. If it finds the symbol in a GST, f indsym displays the source file in which the symbol is defined. If you do not have any GSTs in memory, this macro does nothing. By default, this macro is assigned to the left parenthesis key on the numeric keypad, NUM (. 70 Chapter 7 indent.se indents a marked block three spaces. By default, this macro is assigned to the plus (+) key on the numeric keypad (NUM +). unindent.se unindents a marked block three spaces. By default, this macro is assigned to the minus (--) key on the numeric keypad (NUM--). tolower.se converts the current character to lowercase. This macro is not assigned to a key by default, but you can assign it to a key using the se Configuration Window. toupper.se converts the current character to uppercase. This macro is not assigned to a key by default, but you can assign it to a key using the se Configuration Window. To assign any of these macros to a key, use the Rexx Macro command as described in "Executing A Series of Editor Commands," earlier in this chapter. AREXX Command Summary The following tables list the AREXX commands and their keystroke equivalents supported by the editor. Table 7. 1 AREXX Commands with Default Key Keystroke Equivalents Command Function Definition ____________________________________________________________________________ A1 assign macro 1 Alt-1 A2 assign macro 2 Alt-2 A3 assign macro 3 Alt-3 A4 assign macro 4 Alt-4 A5 assign macro 5 Alt-5 A6 assign macro 6 Alt-6 A7 assign macro 7 Alt-7 A8 assign macro 8 Alt-8 A9 assign macro 9 Alt-9 (continued) Using the AREXX Interface to se 71 Table 7.1 Default Key (continued) Command Function Detinition _______________________________________________________________________ AO assign macro O Alt-O BL beginning of line Num 7 BM go to block menu Ctrl-b BT beginning text Ctrl-Num 7 CO invoke scopts utility CtrlF4 CS change display size F9 CW change windows Num 5 DC delete character Num . DE delete to end of line Ctrl-e DL delete line Ctrly DW delete word Ctrl-w EL end of line Num 1 ES se escape character Ctrl\ ET end text CtrlNum 1 FB toggle window front to back F10 FD go to fork command Ctrl-f FW cycle through open windows F6 GL go to locate line command Ctrll HE get se help F1 IL insert line Ctrln IM toggle interlace mode Enter IN toggle insert mode Num O MB mark beginning of block Ctrl[ MC Match character Ctrl-5 ME mark end of block Ctrl] MM go to main se menu F2 (continued) 72 Chapter 7 Table 7.1 Default Key (continued) Command Function Definition ________________________________________________________________________ M1 execute macro 1 Alt-F1 M2 execute macro 2 Alt-F2 M3 execute macro 3 Alt-F3 M4 execute macro 4 Alt-F4 M5 execute macro 5 Alt-F5 M6 execute macro 6 Alt-F6 M7 execute macro 7 Alt-F7 M8 execute macro 8 Alt-F8 M9 execute macro 9 Alt-F9 M0 execute macro 10 Alt-F10 NC next character Num 6 NE go to next compiler error F5 NL next line Num 2 NP next page Num 3 NW next word CtrlNum 6 OM go to configuration menu Ctrlm OW go to open window command Ctrlo PC previous character Num 4 PL previous line Num 8 PM go to project menu Ctrl-p PP previous page Num 9 PW previous word Ctrl-Num 4 QU go to quit se command F3 RK restore kill buffer Alt-y SA go to next string match Alt-s SC invoke SAS/C compiler F4 (continued) Using the AREXX Interface to se 73 Table 7.1 Default Key (continued) Command Function Definition _________________________________________________________________________ SD scroll down Ctrl-v SE go to search command Ctrl-s SR go to search/replace command Ctrl-r SU scroll up Ctrl-6 UN go to undo command Ctrl-u The following AREXX commands do not have keystroke equivalents. AREXX Commands Command Function Example without Keystroke BP build project 'BP' Equivalents CR carriage control 'CR' DM display message 'DMExample Message' GC get column of cursor 'GC' GE get error from last command 'GE' GI get index of cursor 'GI' GL get number of current line 'GL' GM prompt user for input 'GM' GT get text of current line 'GT' GW get word 'GW' RM REXX macro 'RM "filename"' 75 Part 3 Using the Compiler and Linker Chapters 8 Compiling and Linking Your Program 9 Running Your Program from the Workbench Screen 10 Using Startup Modules, Autoinitialization, and Autotermination Functions 11 Using Amiga Specific Features of the SAS/C Language 12 How Does the Compiler Work? 13 Writing Portable Code 76 77 8 Compiling and Linking Your Program 77 Introduction 77 Compiling Your Program 77 Entering the sc Command 79 Using Compiler Options 119 Using Preprocessor Symbols Defined by the Compiler 120 Linking Your Program 121 Entering The slink Command 121 Specifying Linker Options 127 Using Overlays 132 Specifying Compiler Options with Overlays 133 Customizing the Overlay Manager Introduction This chapter describes how to compile and link your program. It describes the sc command and its options, and it describes the slink command and its options. Compiling Your Program As described in Chapter 2, "Using Your SAS/C Development System," you can compile your program from the Shell by entering the sc command or from the Workbench screen by double-clicking on the Build icon. When you double-click the Build icon, you are indirectly running the se command as well. Entering the sc The sc command has the following format: command sc [options] [source-filename(s)] The sc command accepts C source files, assembly source files, object files, and link libraries as input files. You can enter the filenames anywhere on the se command line, and you can use standard AmigaDOS wildcards to specify filenames. 78 Chapter 8 sc determines the input file type by looking at the file extension. sc recognizes the following filename extensions: . c C source file . p C source file (preprocessor output) . h C header file (treated as a C source file) . o Object file .lib Link library . a Assembler source file . asm Assembler source file . s Assembler source file If you have a file that does not end in one of the recognized extensions, you must use the correct sc option to specify the filename: csource=filename specifies a C source file. You can abbreviate this option as csrc. assembler=filename specifies an assembler source file. You can abbreviate this option as asm. object=filename specifies an object file. You can abbreviate this option as obj. library=filename specifies a link library. You can abbreviate this option as lib. See "Compiler Option Descriptions," later in this chapter for a complete description of each of these options. If you specify an item in the s c command that does not end in a recognized extension and is not a valid option, s c appends the . c extension and attempts to compile the resultant filename. If the sc cannot find the file, it reports an error and proceeds to the next file to be compiled. Note: You can use a plus (+) sign or a comma (,) to separate multiple filenames. Therefore, you cannot enter a filename containing a plus sign or a comma unless the name ends in a recognized extension. To display help information about the sc command, enter sc followed by a question mark (?): sc ? Compiling and Linking Your Program 79 Using Compiler You can specify compiler options in the following ways: Options [] saving the options as project options in an scoptions file (using the scopts utility). The se command looks for this file when you compile your program. [] saving the options as global default options in the variable ENV: sc/ scoptions (using the scopts utility). If the se command cannot find a project options file, it looks for global default options. [] entering the options in the se command. Even if you are using an scoptions file, you can also specify options on the se command line. When you enter the se command, the compiler first tries to read options from the file scoptions in the current directory. If this file does not exist, the compiler looks for options stored in the ENV: sc/scoptions environment variable. Finally, the compiler processes any options you enter on the sc command line in the order in which you enter them. If an option is specified twice, the compiler uses the setting of that option that was specified last. Therefore, you can override the setting of an option in the scoptions file or environment variable by specifying that option in the se command. sc reads all options before processing any files, so any options specified on the command line after an input file name still apply to that file. If your current directory contains an scoptions file but you do not want the compiler to use the options specified in the file, specify the resetoptions option as the first option in the sc command. resetoptions sets all options to their default values. resetoptions does not change the contents of the scoptions file but does affect the compilation in progress. For more information, see the description of the resetoptions option later in this section. The compiler accepts two types of options: switch options do not take parameters. All switches have a negative and a positive version. To specify the negative version, precede the option with no. For example, to use ANSI escape sequences to highlight errors in diagnostic output, specify the errorhighlight option. If you do not want to highlight errors, specify noerrorhighlight. keyword options take parameters. Specify the option name, followed by a blank or an equal (=) sign and the parameter. For example, to generate debugging information for your program, you can specify debug=line or debug 1 ine. Some keyword options also have a negative form like the switch options. For example, if you do not want the compiler to generate debugging information, you specify nodebug. 80 Chapter 8 The option descriptions that follow give the full name and minimum acceptable abbreviation for each option (if the option has an abbreviation). You can also use intermediate forms of the options. For example, the minimum abbreviation for the absfunctionpointer option is afp. Other acceptable abbreviations include absfp, absfuncp, and afptr. The compiler options are not casesensitive. You can enter options in upper, lower, or mixed case. Summary of Compiler Options For each option accepted by the compiler, Table 8.1 shows: [] the full name. [] the minimum abbreviation. The minimum acceptable abbreviation is shown with uppercase letters. [] whether the option takes a parameter. An option that takes a parameter is listed with an equals (=) sign. [] whether the option has a negative form. [] the default value, if any. Table 8.1 Summary of Compiler Negative Options Option Name Form? Default Value ___________________________________________________________________________________ AbsFuncPointer Yes noafp ADDSYMbols Yes noaddsym ANSI Yes noansi ARGument SIZe= No 512 ASseMbler= No AUTOREGister Yes autoreg BATCH Yes nobatch BSSMEMory= No any BSSNAME= Yes udata CODE= No near CODEMEMory= No any CODENAME= Yes text CommentNEST Yes nocnest COMMON Yes nocommon (continued) Using Compiler Options 81 Table 8.1 Negative (continued) Option Name Form? Default Value ____________________________________________________________ CONSTLIBbase Yes constlib COVERage Yes nocover CPU= No any CSouRCe= No DATA= No near DATAMEMory= No any DATANAMEe Yes data DeBuG= Yes nodebug DEF i ne = No DISASseMble= Yes nodisasm ERRor= No ERRorCONsole Yes errcon ERRorHIGHl ight Yes errhigh ERRorLIST Yes errlist ERRorREXX Yes errrexx ERRorSouRCe Yes errsrc EXTernalDEFs Yes extdef FindSYMbol= No FROM No GenProtoDATAitems Yes gpdata GenProtoEXTerns Yes gpext GenProtoFILE= Yes filename _ protos.h GenProtoPARaMeters Yes nogpparm GenPROTOs Yes nogproto GenProtoSTATics Yes nogpstat (continued) 2 Chapter 8 Table 8.1 Negative (continued) Option Name Form? Default Value ________________________________________________________________________ GenProtoTypeDEFs Yes gptdef GlobalSymbolTable= Yes nogst GSTIMMediate Yes nogstimm ICONs Yes icons IDentif ierLENgth= No 255 IGNore= No IncludeDIRectory= No KeepLINE Yes nokline LIBCODE Yes nolibcode LIBrary= No LINX Yes nolink LINKerOPTions= Yes nolinkopt LIST Yes nolist ListFILE= Yes filename.1st ListHEADers Yes nolhead ListINCludes Yes listinc ListMACros Yes nolmac ListNARRow Yes lnarr ListSYStem Yes nolsys MakeGlobalSymbolTable= Yes MAP Yes nomap MapFILE= Yes executable.map MapHUNK Yes nomaphunk MapLIB Yes nomlib MapOVerLaY Yes nomovly MapSYMbols Yes nomsym MapXREFerence Yes nomxref (continued) Using Compiler Options 83 Option Name Form? Default Value ____________________________________________________________ MATH= Yes nomath MAXimumERRors= Yes 50 MAXimumWaRNings= Yes nomaxwrn MEMorySIZE= No large MODified Yes nomod MultipleCharacterCONStants Yes nomccons MultipleINCludes Yes minc OBJect= No OBJectLIBrary= Yes OBJectNAME= Yes OLDPreProcessor Yes nooldpp ONERRor= No stop OPTimize Yes noopt OPTimizerALIAS Yes optalias OPTimizerCOMPlexity= Yes 3 OPTimizerDEPth= Yes 3 OPTimizerGlObal Yes optgo OPTimizerINLine Yes optinl OPTimizerINLOCAL Yes nooptinlocal OPTimizerLOOP Yes optloop OPTimizerPEEPhole Yes optpeep OPTimizerRecurDEPth= Yes 3 OPTimizerSIZE Yes nooptsize OPTimizerTIME Yes noopttime PARaMeters= No stack PRECision= No mixed PreProcessorBUFfer= No 8192 PreProcessorONLY Yes nopponly ProgramNAME= No (continued) 84 Chapter 8 Negative Option Name Form? Default Value ______________________________________________________________ RESetOPTions No SAVEDS Yes nosaveds ShortINTegers Yes nosint SmallCODE Yes noscode SmallDATA Yes nosdata SouRCeIS= Yes STacKCHecK Yes stkchk STacKEXTend Yes nostkext STanDardIO Yes stdio STaRTup= Yes c (for c.o) STRICT Yes nostrict STRingsCONst Yes nostrcons STRingMERge Yes nostrmer STRIPDeBuG Yes nostripdbg STRuctureEQuivalence Yes nostreq TO= No TRIGraph Yes notrig UnderSCORE Yes nouscore UnsignedCHAR Yes nouchar UTILityLIBrary Yes noutillib VERBOSE Yes noverbose VERsion Yes version WaRN= No WarnVoidRETurn Yes wvret WITH= No XREFerence Yes noxref XreferenceHEADers Yes noxhead Xref erenceSYStem Yes noxsys Using Compiler Options 85 Compiler Option Descriptions The following pages describe each of the options accepted by the s~ command. The compiler options are not case-sensitive. You can enter options in upper, lower, or mixed case. AbsFuncPointer generates 32-bit references to functions when loading function pointers. The default value is noabsfuncpointer. The minimum acceptable abbreviation is afp. If you specify noabsfuncpointer and you take the address of a function that is more than 32k away, the linker generates an ALV (automatic link vector) jump instruction that allows your code to work. However, if you compare the address of the function to a function pointer assigned elsewhere, you may get a different value. Specify absfuncpointer if your code is larger than 64K or in multiple code hunks and you compare function pointers. Specifying absfuncpointer may increase the size of your executable. AddSymbols tells the linker to add symbol information to the executable module. The default value is noaddsymbols. The minimum acceptable abbreviation is add sym. This option is automatically enabled if you specify the debug option. This option is ignored if you do not specify the link option. ANSI enforces the strictest interpretation of the ANSI C standard. Using this option produces many additional warning messages. The default value isnoansi. To be completely ANSI-compliant (that is, if you require a pure ANSI namespace), you should also define the preprocessor symbol _ STRICT _ ANSI before including any header files. For more information about_ STRICT_ANSI, refer to Chapter 7, "Library Reference," in SAS/C Development System Library Reference, Version 6.0. If you require support for ANSI trigraphs, specify the trigraph option also. For more information about improving the portability of your code, see Chapter 13, "Writing Portable Code." ArgumentSize=n sets the size of the maximum argument to a preprocessor macro. The minimum acceptable abbreviation is argsiz. This option does not have a negative form. The default value is 512. However, the 86 Chapter 8 memorysize option sets the argumentsize (and other internal limits) to different default values if you do not specify argumentsize. See the description of the memorysize option for more information. Assembler=filename(s) specifies assembly-language files that are to be assembled and, if you specify the link option, linked into the program. The minimum acceptable abbreviation is asm. This option does not have a negative form. You can use AmigaDOS wildcard characters to specify filenames. To specify several filenames or wildcard patterns, separate each filename with a plus (+) sign or a comma (,). You can specify the assembler option as many times as necessary. If you are assembling a disassembly that was generated with the disassemble compiler option, specify the underscore compiler option also. (If you assemble a disassembly by calling the assembler directly, specify the -u assembler option.) See also the descriptions of the csource, ob ject, and library options. AutoRegister enables automatic register selection by the code generator. The default value is autoregi ster. The minimum acceptable abbreviation is autoreg. If you specify autoregister, the compiler attempts to add register variables to the variables that have already been chosen by the global optimizer or declared with the register keyword. Batch tells the linker not to prompt for definitions of undefined symbols. The default value is nobatch. This option is ignored if you do not specify the link option. See also the description of the batch linker option. BSSMemory=type specifies the type of memory into which uninitialized external data items should be loaded. You can specify any, chip, or fast for type. You can abbreviate these values as a, c, or f. The default value is any. This option does not have a negative form. This option affects code generated by both the compiler and the assembler. See also the descriptions of the datamem and codemem options. Using Compiler Options 87 BSSName=name names the uninitialized data section. The default value is udata. You can specify bssname=none or nobssname if you want an unnamed BSS section. The linker automatically merges all sections with the same name. See also the descriptions of the codename and dataname options. See Chapter 12, "How Does the Compiler Work?" for information on data and code sections. Code = reference-type specifies whether you want 16-bit or 32-bit references to functions not declared in the current file. You can specify near or n for 16-bit references or far or f for 32-bit references. The default value is near. This option does not have a negative form. Most programs do not need this option even if they are very large, because the linker creates a jump instruction (an ALV) for any references to functions that are out of range. See also the description of the data option. CodeMemory=type specifies the type of memory into which code should be loaded. You can specify any, chip, or fast. You can abbreviate these values as a, c, or f. The default value is any. This option does not have a negative form. This option affects code generated by both the compiler and the assembler. See also the descriptions of the bssmem and datamem options. CodeName =name names the code section. The default value is text. You can specify codename=none or nocodename if you want an unnamed code section. The linker automatically merges all sections with the same name. See also the descriptions of the bssname and dataname options. See Chapter 12, "How Does the Compiler Work?" for information on data and code sections. CommentNest allows nested comments. The default value is nocommentnest. The minimum acceptable abbreviation is cnest. Nested comments occur when one comment is totally contained inside another. The ANSI Standard prohibits nested comments, so in ANSI compliant code, the first comment end sequence (*/) terminates both comments. For example, the statement below generates an error 88 Chapter 8 with nocommentnest, but compiles successfully with commentnest. /* i = i+1;/* This is a comment */ */ The statement below compiles successfully with nocommentnest, but generates an error with commentnest. /* i = i+l; /* This is a comment */ Common tells the compiler to use the common model for external data. If you specify nocommon, the compiler uses the strict reference-definition model. The default value is nocommon. The section "Using Common Model External Data" in Chapter 11, "Using Amiga Specific Features of the SAS/C Language," describes common and strict reference-definition models. ConstLibBase tells the compiler that library base pointers are set once then remain constant throughout your entire program. The default value is constlibbase. The minimum acceptable abbreviation is constlib. If you change the value of your library bases after setting them, you should specify the noconstlibbase option. Specifying constlibbase allows the compiler to prevent extra register loading when making a series of calls to library functions through an external variable containing the library base. Coverage tells the compiler to generate code to collect coverage analysis information. The default value is nocover. The minimum acceptable abbreviation is c over. Coverage analysis information allows you to determine which lines of your program have been executed by your test cases. For more information, refer to the description of the cover utility in SAS/C Development System User's Guide, Volume 2: Debugger, Utlities, Assembler, Version 6.0. Using Compiler Options 89 If you specify the cover option, make sure that you: [] Link with the file sc: examples/cover/covutil.o or LIB:covutil.o. [] Do not specify the nostdio option. [] Use startupsc to link with the standard c.o startup module. CPU=processor generates code specific to the specified processor. You can specify any, a, or 68000 to generate code for any processor. You can also specify 68010, 68020, 68030, or 68040 to generate code for a specific processor. The default value is any. This option does not have a negative form. This option defines one or more preprocessor symbols. See the section "Using Preprocessor Symbols Defined by the Compiler," later in this chapter for a list of those symbols. This option affects code generated by both the compiler and the assembler. CSource=filename specifies C source files that are to be compiled and, if you specify the link option, linked into the program. The minimum acceptable abbreviation is csrc. This option does not have a negative form. You can use AmigaDOS wildcard characters to specify filenames. To specify several filenames or wildcard patterns, separate each filename with a plus (+) sign or a comma (,). You can specify the csource option as many times as necessary. See also the descriptions of the assembler, object, and library options. Data =reference-type specifies whether you want the compiler to generate 16-bit or 32-bit references to external and static data items. You can specify any of the following: near or n tells the compiler to use 16-bit references. If you specify near, all data not declared with the _ _ far or _ _ chip keyword are placed into the near data section. The default value is near. far or f tells the compiler to use 32-bit references. Register A4 is still reserved to point to the near data section so that you can mix code compiled with data=near and data=far. 90 Chapter 8 faronly or fo tells the compiler that your program never uses near data. If you specify faronly, the compiler generates 32-bit references and may use register A4 as an additional register variable. If you compile with the data = faronly option, and you declare data with the __near keyword, the compiler displays the warning message 194: too much local data for NEAR reference, some changed to FAR If your entire project is in one source file or is compiled with data=faronly, you can ignore this warning unless you get an error later in the compilation or link. auto or a indicates that the first 64k of external data should generate 16-bit references and the remaining external data should generate 32-bit references. This option does not have a negative form. You can override this option on individual data items by using the _ _ near, _ _ far, or _ _ chip keywords. _ _ near forces the compiler to generate a 16-bit reference, and _ _ far forces the compiler to generate a 32-bit reference. _ _ chip forces the compiler to place the data item into chip memory. For more information, refer to the section "Using Special Keywords" in Chapter 11, "Using Amiga Specific Features of the SAS/C Language." See also the description of the code option. DataMemory=type specifies the type of memory into which initialized static or external data should be loaded. You can specify any, chip, or fast. You can abbreviate these values as a, c, or f. The default value is any. This option does not have a negative form. This option affects code generated by both the compiler and the assembler. See also the descriptions of the bssmem and codemem options. Using CompilerOptions 91 DataName=name names the initialized data section. The default value is data. You can specify dataname=none or nodataname if you want an unnamed data section. The linker automatically merges all sections with the same name. See also the descriptions of the bssname and codename options. See Chapter 12, "How Does the Compiler Work?" for information on data and code sections. Debug=level sets the debugging level of the compiler. If you do not want the compiler to generate debugging information, specify nodebug. The default value is nodebug. The minimum acceptable abbreviation is dbg. To generate debugging information, specify debug=level, where level is one of the following: line or l produces line number information only. symbol or s produces line number information, information on automatic and formal variables, and information on external and static symbols that are referenced in the module being compiled. symbolflush or sf produces the same information as symbol, and flushes any non- register variables being held in registers to memory at each line boundary to allow the debugger to accurately display their values in C source mode. full or f produces the same information as symbol. However, debug=full produces information on au symbols whether or not the module references the symbol. fullflush or ff produces the same information as full, and flushes any non- register variables being held in registers to memory at each line boundary to allow the debugger to accurately display their values in C source mode. Any debug option except nodebug adds the -d assembler option to any assembled files to force debugging line number information on assembler output. Also, if you specify the link option and any debug option except nodebug, the addsym option is passed to the linker. 92 Chapter 8 Define[=]symbol[=value] defines the specified preprocessor symbol, as if with a #define statement. The minimum acceptable abbreviation is def. This option does not have a negative form. Do not enter a space between the symbol name and the following equal sign. If the value contains a space, enclose the entire argument in double quotes ("). As with all other compiler options, the equal sign between the define option and the symbol name is optional, so both of the following examples are acceptable: define foo=bar define=foo=bar You can specify the define option as many times as necessary. Any symbols defined with the define option are defined in the assembler as well. Note: The define compiler option does not affect the linker. Do not confuse this option with the define linker option. DisAssemble=filename tells the compiler to disassemble the code as it is generated and to send the disassembly to the file you specify. The default value is nodisassemble. The minimum acceptable abbreviation is disasm. To send the disassembly to the Shell, use disasm=*. Error=n tells the compiler to treat the specified message as an error. You can specify all or a to promote all enabled warnings to errors, or you can specify one or more message numbers to promote only those messages. The minimum acceptable abbreviation is err. This option does not have a negative form. To specify several message numbers, separate each number with a plus (+) sign or a comma (,). You can specify the error option as many times as necessary. See also the descriptions of the warn and ignore options. ErrorConsole enables printing of diagnostics to the console (stdout). The default value is errconsole. The minimum acceptable abbreviation is errcon. Using Compiler Options 93 ErrorHighlight highlights the token that caused the error using ANSI escape sequences in diagnostic output that is sent to the console. The default value is errorhighlight. The minimum acceptable abbreviation is errhigh. ErrorList prints diagnostic messages to the listing file. The default value is error list. The minimum acceptable abbreviation is errlist. This option is ignored if you do not specify the list option. ErrorRexx sends diagnostic messages to the scmsg utility. The default value is noerrorrexx. The minimum acceptable abbreviation is errrexx. For more information, refer to the description of the scmsg utility in SAS/C Development System User's Guide, Volume 2. ErrorSource prints lines from the C source file with the diagnostic messages that are sent to the console. The default value is errorsource. The minimum acceptable abbreviation is errsrc. ExternalDefs treats all external definitions as definitions. The default value is externaldefs. The minimum acceptable abbreviation is extdef. If you specify noexternaldefs, all external definitions are treated as external declarations. This action has the same effect as if you had declared each variable with the extern keyword. For example, int i is treated as extern int i, and it would need to be defined in a file compiled without noexternaldefs. FindSymbol=symbol-name tells the compiler to print a warning message each time the specified symbol is defined. The minimum abbreviation is fsym. This option does not have a negative form. You can specify the findsymbol option as many times as necessary. If you specify the findsymbol option, a message is produced for any definition of the symbol, including #def ine statements, structure and union declarations, prototypes, and extern, static, and local variable definitions. Use the fsym option to quickly determine where a given preprocessor symbol or prototype is coming from. 94 Chapter 8 From is included only for compatibility with the slink command. The compiler ignores this option. This option does not have a negative form. GenProtoDataItems generates external declarations for variables defined in the source files that are not defined as static. The minimum abbreviation is gpdata. The default value is gpdata. This option is ignored if you do not specify the genprotos option. GenProtoExterns generates prototypes for externally-known routines. The default value is genprotoexterns. The minimum acceptable abbreviation is gpext. This option is ignored if you do not specify the genprotos option. GenProtoFile=filename specifies the name of the file in which to place the generated prototypes. The default value is filename_protos.h. The minimum acceptable abbreviation is gpfile. This option is ignored if you do not specify the genprotos option. GenProtoParameters generates prototypes using the __PARMS macro. The default value is nogenprotoparameters. The minimum acceptable abbreviation is gpparm. This option allows your C code to compile successfully on compilers that support prototypes and on those that do not. On ANSI compilers, the __PARMS macro expands to the parameter list for the function, thereby creating a prototype. On non-ANSI compilers, the __PARMS macro expands to an open-close parentheses pair, which declares the function's return type without defining a prototype. This option is ignored if you do not specify the genprotos option. GenProtos generates prototypes and data declarations instead of compiling your file. The default value is nogenprotos. The minimum acceptable abbreviation is gproto. This option defines the preprocessor symbol _GENPROTO. If you specify a filename with the genprotofile option, the prototypes are Using Compiler Options 95 written to the specified file. Otherwise, the prototypes are written to the file filename_ protos .h. While generating prototypes, the compiler suppresses most warnings automatically, because many of the warnings may be due to incorrect or missing prototypes. The compiler also checks all #include statements as they are reached. If your file #includes the same prototype file that is being generated, the compiler skips that #include statement. This feature allows you to use this option to maintain declarations for all externally-known symbols in each C source file and regenerate the declarations as the files change. To set up your project so that you can use this option to maintain prototype files, do the following: 1. Create a header file that contains # include statements for each of the files in your project, as follows: #include "file1_protos.h" #include "file2_protos.h" . . . #include "filen_protos.h" 2. Include this header file in each file in your project. 3. Compile your entire project with the genproto option. As each .c file is compiled, the compiler creates the corresponding _protos.h file. The compiler suppresses the header file not found warnings that would normally be produced. GenProtoStatics generates prototypes for static routines. The default value is nogenprotostatics. The minimum acceptable abbreviation is gpstat. This option is ignored if you do not specify the genprotos option. GenProtoTypedefs tells the compiler to use typedefs instead of resolved types when generating prototypes for any functions using typedefs for parameters or return values. The default value is genprototypedefs. The minimum acceptable abbreviation is gptdef. This option is ignored if you do not specify the genprotos option. 96 Chapter 8 GlobalSymbolTable=gst tells the compiler to use the specified GST (Global Symbol Table). The default value is noglobalsymboltable. The minimum acceptable abbreviation is gst. The GST must have been created using the makeglobalsymboltable option during a previous compilation. The gst option is ignored if you specify the makeglobalsymboltable option. Therefore, you can enter the makeglobalsymboltable in the sc command even if your scoptions file contains the gst option. This option defines the preprocessor symbol _ GST. GST=gst-filename is a synonym for the GlobalSymbolTable option. GSTImmediate is included for compatibility with projects using precompiled header files as implemented in Version 5 of the compiler. This option makes the contents of the GST you specify with the gst option immediately available to the program. The default value is nogstimmediate. The minimum acceptable abbreviation is gstimm. Normally, symbols defined in a specific header file in the GST are available to your program only after you have included the header file with a #include statement. This option makes the contents of the GST you specify with the gst option immediately available to the program, even if your program does not contain #include statements for the header file. With Version 5 precompiled header files, all symbols in the precompiled header files were available to your program even if your program did not contain #include statements for the header file. Icons tells the compiler to create icons for files that it creates, including listing files, preprocessor output files, prototype files, and object files. The default value is icon. If you specify icons, then each time the compiler generates a file, it looks in the drawer sc: icons for an icon named def_extension, where extension is the filename extension of the file it created. If the compiler finds an icon file appropriate to the file extension, it copies the icon to the directory in which the file was created. If the compiler cannot find sc: icons or cannot find an icon with the appropriate extension, it does not create an icon. If you UsingCompilerOptions 97 specify noicons and link, the noicons option is also passed to the linker. For more information, see the section "Using Icons" in Chapter 2, "Using Your SAS/C Development System." IdentifierLength=n specifies the maximum number of significant characters in an identifier. The default value is 255. The minimum acceptable abbreviation is idlen. This option does not have a negative form. Identifiers longer than n are truncated without warning. Identifiers longer than n bytes that differ after the first n bytes are treated as identical. Ignore=n tells the compiler to ignore the specified warning message. The minimum acceptable abbreviation is ign. This option does not have a negative form. You cannot ignore error messages. You can specify a 11 or a to ignore all warning messages, or you can specify one or more message numbers to ignore only those messages. To specify several message numbers, separate each number with a plus (+) sign or a comma (,). You can specify the ignore option as many times as necessary. See also the descriptions of the error and warn options. IncludeDirectory=directory adds a directory to the list of directories to search for include files. The default list is the current directory and include:. The minimum acceptable abbreviation is idir. This option does not have a negative form. You can specify the incdirectory option as many times as necessary. Any directories you specify with includedirectory are also passed to the assembler as header file search directories. ReepLine generates #line directives in the preprocessor output file that correspond to the lines in the original source files. The default value is nokeepline. The minimum abbreviation is kline. This option allows you to compile the preprocessed source and get error and warning messages that refer you to the correct line in the nonpreprocessed version of the file. This option is ignored if you do not specify the pponly option. 98 Chapter 8 LibCode tells the compiler that the compiled code will be linked into a shared library. The default value is nolibcode. Any functions compiled with libcode and either the __saveds keyword or the saveds option load their near data section from a point relative to the library base register A6 instead of from a global data area. libcode also guarantees that the current library base will be in register A6 whenever A6 is referenced or an internal call is made. Do not use this option when creating a normal executable module. Library=link-library-filename(s) specifies the link libraries that are to be passed to the linker. The minimum acceptable abbreviation is lib. This option does not have a negative form. You can use AmigaDOS wildcard characters to specify filenames. To specify several filenames or wildcard patterns, separate each filename with a plus (+) sign or a comma (,). You can specify the library option as many times as necessary. Any libraries you specify are passed to the linker before the SAS/C libraries. This option is ignored if you do not specify the link option. See also the description of the csource, object, and asm options. Link tells the compiler to invoke the linker to produce a final executable. The default value is nolink. If you do not specify link, the compiler ignores any object files and link libraries that you specify. The options passed to the linker are placed into the file program. lnk, and the linker is invoked using this file as a with file. To see which linker options were generated, look at the . lnk file after sc runs the linker. LinkerOptions=option(s) passes the provided parameter to the linker as command line options. The default value is nolinkeroptions. The minimum acceptable abbreviation is linkopt. Using Compiler Options 99 If you want to specify more than one option, or if the option you want to specify contains a blank, surround the entire option string with double quotes ("), as in the following example: sc linkeroptions=llbufsize 10000 maxhunk 2" link myprog.c Any options specified in the options string are passed to the linker after any compiler options that are identified as valid only if you specify link. Therefore, the linkeroptions values override the values passed by the sc options. This option is ignored if you do not specify the link option. List tells the compiler or assembler to produce a listing file. The default value is nolist. The compiler writes the output to the filename you specify with the listfile option. If you do not specify an output filename, the compiler uses the name of the first source file you specify but with the extension.lst. ListFile=filename names the listing and/or cross reference file. The default filename is the same filename as the source file but with the extension.lst. The minimum acceptable abbreviation is lfile . This option is ignored if you do not specify the list or xreference options. ListHeaders tells the compiler or assembler to include user header files in the listing. The default value is listheaders. The minimum acceptable abbreviation is lhead. This option is ignored if you do not specify the list option. ListIncludes lists the names of all included .h files in the listing file. The default value is listinc. The minimum acceptable abbreviation is linc. This option is useful for determining: [] .h file dependencies for smake [] the exact path of each .h file used [] exactly which .h files are included by other .h files. 100 Chapter 8 The hierarchy of files is indicated by indention levels; a file included by another file is indented one level deeper than the parent file. This option is ignored if you do not specify the list option. ListMacros tells the compiler or assembler to expand macros in the listing. The default value is nolistmacros. The minimum acceptable abbreviation is lmac. This option is ignored if you do not specify the list option. ListNarrow tells the compiler or assembler to produce a narrow listing (less than 80 columns wide). The default value is listnarrow. The minimum acceptable abbreviation is lnarr. This option is ignored if you do not specify the list option. ListSystem tells the compiler to include system header files in the listing. The default value is nolistsystem. The minimum acceptable abbreviation is lsys . This option is ignored if you do not specify the list option. MakeGlobalSymbolTable=gst-filename creates a GST (Global Symbol Table). The minimum acceptable abbreviation is mgst. If you specify the gst and makegst options, the gst option is ignored. Therefore, you can enter the makegst in the sc command even if your scoptions file contains the gst option. This option automatically enables the nomultipleincludes and noexternaldefs options. For more information on creating and using GSTs, refer to SAS/C Development System Library Reference. This option defines the preprocessor symbol _ MGST. Map produces a map of the executable module. The default value is nomap. This option is ignored if you do not specify the link option. MapFile=filename names the map file. The default value is executable.map. The minimum acceptable abbreviation is mfile. This option is ignored if you do not specify the link and map options. Using Compiler Options 101 MapHunk maps all output hunks by size and originating function. The default value is nomaphunk. The minimum acceptable abbreviation is nomhunk . This option is ignored if you do not specify the link and map options. MapLib generates a list of hunks by library symbol in the map. The default value is nomaplib. The minimum acceptable abbreviation is mlib. This option is ignored if you do not specify the link and map options. MapOverlay includes a list of hunks in each overlay in the map. The default value is nomapoverlay. The minimum acceptable abbreviation is movly. This option is ignored if you do not specify the link and map options. MapSymbols includes a list of defined symbols and the location at which they are defined. The default value is nomapsymbols. The minimum acceptable abbreviation is msym. This option is ignored if you do not specify the link and map options. MapXreference writes a symbol cross-reference to the map file that lists each symbol definition and the places each symbol is used. The default value is nomapxreference. The minimum acceptable abbreviation is mxref. This option can generate a lot of output, but it is useful when you are trying to track down where an unresolved symbol is referenced. This option is ignored if you do not specify the link and map options. 102 Chapter 8 Math=type chooses a format for floating-point math and, if you also specify the link option, links with the appropriate math library. The default value is nomath. You can specify one of the following as the type: standard or s links with the library scm.lib (or with scms.lib if you specify the shortint option). The math format is IEEE. ffp or f generates code to call the FFP shared library provided by Commodore. The math format is FFP. 68881, 68882, or 8 generates inline code for the 68881 and 68882 coprocessors. If you specify one of these coprocessor options, your program will not run if a coprocessor is not available. coprocessor is a synonym for these options. The math format is IEEE. ieee or i generates code to call the IEEE shared library provided by Commodore. The math format is IEEE. Some math options define preprocessor symbols. See the section "Using Preprocessor Symbols Defined by the Compiler," later in this chapter, for a list of those symbols. For additional information about compiling and linking with math libraries, refer to Chapter 3, "Using the SAS/C Libraries," in SAS/C Development System Library Reference. MaximumErrors=n sets the limit on the number of errors for a single compilation. The default value is 50. The minimum acceptable abbreviation is maxerr. If a single compilation generates more than n errors, the compiler aborts the compilation. nomaxerr removes any limits. MaximumWarnings=n sets the limit on the number of warnings for a single compilation. The default value is nomaxwrn. The minimum acceptable abbreviation is maxwrn. If a single compilation generates more than n warnings, the compiler aborts the compilation. nomaxwrn removes any limits. Using Compiler Options 103 MemorySize=size tells the compiler approximately how much memory you have on your system. You can specify one of the following: [] tiny or t [] small or s [] medium or m [] large or l [] huge or h The default value is large. The minimum acceptable abbreviation is memsize. This option does not have a negative form. Larger sizes allow sc to compile more complex programs and to compile faster. Smaller sizes allow sc to continue to work under low- memory conditions. If the compiler runs out of memory during a compilation, it displays the message ***Freeing Resources, attempts to free up memory, and automatically drops to a lower memorysize value. memorysize affects how and where the compiler stores any debugging information. If the compiler begins to run out of memory, it starts writing debugging information to a disk file. This file is referred to as a debug side file. memorysize also affects the disposition and buffering of the compiler intermediate file. This option tells the compiler how much initial memory space to reserve for the intermediate information. For large and huge, the intermediate file is kept totally in memory, which is much faster than writing it to disk when the memory is available. At smaller values, the intermediate file is written to disk, but the memorysize value affects the amount that is buffered. In addition, if you do not specify the preprocessorbuffer (ppbuf) and/or argumentsize (argsize) options, the memorysize option sets these values for you. If you specify the preprocessorbuffer and/or argumentsize options, the values you specify override the values set by memorysize. 104 Chapter 8 The following table lists the default values for argumentsize and preprocessorbuffer by memorysize. It also lists the buffer size and location of the compiler intermediate file. Intermediate Debug Side memsize argsize ppbuf File Buffer File Buffer tiny 127 1024 1024 2K small 255 2048 4096 8K medium 511 4096 8192 32K large 1023 8192 no limit 64K huge 4800 16384 no limit 128K See also the descriptions of the prepro~essorbuffer and argumentsize options. Modified tells the sc command to process only files that are out of date with respect to their output files. The default value is nomodified. The minimum acceptable abbreviation is mod. This option is useful if you are compiling several files with a single sc command and only some of the files need to be recompiled. This option also works when you are generating prototypes or preprocessor output. If you also specify the link option, all object files are included in the link, even if their source files were not recompiled. MultipleCharacterConstants allows up to four bytes to appear within single quotes as a character constant. This option is included only for compatibility with previous releases of the compiler, and its use is not recommended. The minimum acceptable abbreviation is mccons. The default value is nomccons. Using Compiler Ophons 105 If you specify mccons, a single constant of type int is generated. If fewer than four bytes are provided, they are padded on the left with ~eroes, as in the following example: #include void main(void) long l = 'abcd'; long m = '\x01\x02\x03'; printf("l=0x%081x, m=0x%081x\n", l, m); This example program prints the following: l=0x61626364, m=0x00010203 MultipleIncludes tells the compiler to include header files that are included more than once. The default value is multipleincludes. The minimum acceptable abbreviation is minc. This behavior is required by the ANSI Standard. However, many projects do not need this behavior, and specifying nominc can save compilation time. Object=filename(s) lists the object files that are to be linked into the program. The minimum acceptable abbreviation is obj. This option does not have a negative form. The object files must have been created during a previous compilation. Do not specify object files that will be created by the same sc command in which you specify the ob ject option. You can use AmigaDOS wildcard characters to specify filenames. To specify several filenames or wildcard patterns, separate each filename with a plus (+) sign or a comma (,). You can specify the ob ject option as many times as necessary. This option is ignored if you do not specify the 1 ink option. See also the descriptions of the csource, library, and assembler options. 106 Chapter 8 ObjectLibrary=link-library-name specifies that any resulting object files are to be placed in the named link library. The minimum acceptable abbreviation is objlib. Do not specify this option if you also specify the link option. ObjectName=file-or-directory-name specifies the name of the file or directory to hold compiler and assembler output. The minimum acceptable abbreviation is objname. If you are compiling or assembling only one C source file or assembly-language file, you can use this option to specify the file where you want the compiler or assembler output. If you are compiling or assembling more than one file, you can use this option to specify a directory where you want the output, and sc uses the same filename as the source file but replaces the extension with .o. The directory name must end with a forward slash (/) or a colon (:). If you do not use the objectname option, sc uses the same filename with the extension of .o, but it places the files in the same directory as the source file. OldPreprocessor is provided for compatibility with pre-ANSI style preprocessors. The default value is nooldpreprocessor. The minimum acceptable abbreviation is oldpp. The oldpp option does the following: [] allows old-style token pasting using comments [] substitutes values for parameters specified as quoted strings in macro definitions. For example, suppose you have the following program: #define FOO ( bar ) "bar" void main(void) { printf ( "%s\n", FOO(test) ); } Using Compiler Options 107 If you compile this program with oldpp, the program prints test. If you compile this program with nooldpp, the program prints bar. To make this program work with the ANSI features and the nooldpp option, substitute the following for the #define: #define FOO(bar) #bar As an additional example, suppose you have the following program: #define FOO(bar) foo_/**/bar void main(void) { int foo_test; int foo_xxx; FOO(test) = 10; FOO(xxx) = 20; printf("%d %d\n", foo_test, foo_xxx); } If you compile this program with oldpp, the #define concatenates the text of the argument after the string foo_ and the program prints 10 20. If you compile this program with nooldpp, the program produces a compilation error. To make this program work with the ANSI features and the nooldpp option, substitute the following for the #define: #define FOO(bar) foo_##bar OnError=x tells sc what action to take if a C or assembly language source file generates an error. The minimum acceptable abbreviation is onerr. This option does not have a negative form. 108 Chapter 8 You can specify one of the following: stop or s tells sc not to process any more source files. The default value is stop. continue or c tells sc to process the next source file. If you specify the link option, but your program generates errors, your program is not linked even if you specify onerr=continue. Optimize enables the global optimizer (unless you specify nooptglobal) and peephole optimizer (unless you specify nooptpeep). The default value is nooptimize. The minimum acceptable abbreviation is opt. OptimizerAlias disables type-based aliasing assumptions in the optimizer. The default value is nooptimizeralias. The minimum acceptable abbreviation is optalias. If you specify optimizeralias, the global optimizer uses worst- case aliasing. Specifying optimizeralias can significantly reduce the amount of optimization that can be performed. This option is ignored if you do not specify the optimize and optglobal options. OptimizerComplexity=n defines the maximum complexity level of functions to be automatically inlined. The default value is 3. The minimum acceptable abbreviation is optcomp. The parameter n represents the relative complexity of the function to be inlined and is a count of the number of discrete operations in the function. Try different values for this number until you get the results you want. Specify a value of 3 or higher. The higher the number, the more functions you can inline, but the size of your code will grow significantly as well. If you specify nooptcomp, no complexity-based inlining occurs. This option is ignored if you do not specify the optimize, optglobal, and optimizerinline options. Using Compiler Options 109 OptimizerDepth=n defines the maximum nesting depth of automatically inlined functions. The default value is 3. The minimum acceptable abbreviation is optdep. Specify a value of 3 or higher. This option is ignored if you do not specify the optimize, optglobal, and optimizerinline options. OptimizerGlobal enables the global optimizer. The default value is optimizerglobal. The minimum abbreviation is optgo. This option is ignored if you do not specify the optimize option. OptimizerInline allows inlining of functions, including functions defined with the _ _ inline keyword. The default value is optimizerinline. The minimum acceptable abbreviation is optinl. This option is ignored if you do not specify the optglobal and opt imi z e options. If you do not specify this option, the optinlocal, optdepth, optcomplexity, and optrdepth options are ignored. OptimizerInLocal inlines single use static functions. The default value is nooptimizerinlocal. The minimum acceptable abbreviation is optinlocal. This option is ignored if you do not specify the optimize, optglobal, and optimizerinline options. OptimizerLoop enables loop optimizations. The default value is optimizerloop. The minimum acceptable abbreviation is optloop. This option is ignored if you do not specify the optimize and optglobal options. OptimizerPeephole enables the peephole optimizer. The default value is optimizerpeephole. The minimum acceptable abbreviation is optpeep. This option is ignored if you do not specify the optimize option. 110 Chapter 8 OptimizerRecurDepth=n defines the maximum depth of recursion of automatically inlined functions. The default value is 3. The minimum acceptable abbreviation is optrdep. Specify a value of 3 or higher. This option is ignored if you do not specify the optimize, optglobal, and optimizerinline options. OptimizerSize disables optimizations that may sacrifice code size to save time. The default value is nooptsize. The minimum acceptable abbreviation is optsize. This option is ignored if you do not specify the optimize and optglobal options. Do not specify both the optimizersize and optimizertime options. OptimizerTime disables optimizations that may sacrifice time to save space. The default value is nooptimizertime. The minimum acceptable abbreviation is opttime. This option is ignored if you do not specify the optimize and optglobal options. Do not specify both the optimizersize and optimizertime options. Parameters =method indicates how parameters should be passed. The minimum acceptable abbreviation is parm. This option does not have a negative form. You can specify one of the following: stack or s indicates parameters should be passed on the stack. The default value is stack. register or r indicates parameters should be passed in registers. both or b generates a combination prolog that allows parameters to be passed on the stack or in registers. If your program has prototypes for all routines, you should probably use parameters=register for increased efficiency. If you are placing code into a link library, specify parms=both so that your library functions accept registerized parameters and parameters that are passed on the stack. Using Compiler Options 111 If you write a function that has the same name as a library function, you need to add the __regargs keyword to your function or compile with the parms=both or parms=register option. For example, you may want to replace the SAS/C library function malloc with your own version of malloc. If you compile with the parms=stack option or define your version of malloc with the __stdargs keyword, then two versions of malloc are linked into your executable. If you use other SAS/C library functions that call malloc, these functions use the version of malloc in the SAS/C libraries. However, your functions that call malloc use your version of malloc. To make sure that all calls to malloc are using your version of malloc, define your version with __regargs or compile with the parms=both or parms=register option. For information about passing parameters between C language functions and assembly-language functions, refer to Chapter 11, "Using Assembly Language with C Language," in SAS/C Development System User's Guide, Volume 2. Precision=precision specifies the size of floating-point variables. You can specify double or mixed. The default value is mixed. The minimum acceptable abbreviation is prec. This option does not have a negative form. If you specify double, data declared as float are treated as if they were declared as double. If you specify mixed, data declared as float and data declared as double are different sizes. PreprocessorBuffer=n sets the maximum number of bytes to which a macro can be expanded by the preprocessor. The default value is 8192 unless set differently by the memorysize option. The minimum acceptable abbreviation is ppbuf. This option does not have a negative form. If a macro expands to greater than n bytes, the compiler issues an error message and aborts the compilation. See the description of the memorysize option for more information. PreprocessorOnly tells the compiler to run only the preprocessor on the C source files. The default value is nopreprocessoronly. The minimum acceptable abbreviation is pponly. 112 Chapter 8 If you specify a filename with the ob jectname option, the compiler writes the output to the file you specify. If you do not specify an output filename, the compiler writes the output to the same filename as the source file but with the extension . p. This option defines the preprocessor symbol _ PPONLY. ProgramName=output-module-name specifies the name of the executable module. The default value is the root name of the first source file specified in the sc command. The minimum acceptable abbreviation is pname. This option does not have a negative form. This option is ignored if you do not specify the 1 ink option. ResetOptions resets all options to their default values. The minimum acceptable abbreviation is resopt. This option does not have a negative form. If you specify this option as the first option in the sc command, it resets any option specified in the scoptions file. If you specify this option after other options or filenames in the sc command, it resets the options preceding it, including the filenames. Saveds generates code as if you had defined all functions in the source files with the __saveds keyword. The default value is nosaveds. The __saveds keyword restores the near data pointer in register A4 at each function entry point. You should specify this option if you are compiling code that is used as an interrupt routine, called with the AddTask function, used in a shared library, or called from another process. This option does not work if your code is linked with the cres.o or catchres.o startup modules. ShortIntegers enables 16-bit integers. The default value is noshortintegers. The minimum acceptable abbreviation is sint. If you specify shortintegers, types int and short are the same size. If you specify noshortintegers, types int and long are the same size. If you are running the assembler, this option defines the symbol shortint. This option also defines the preprocessor symbol _SHORTINT. Using Compiler Options 113 SmallCode tells the linker to merge all code hunks into a single hunk. The default value is nosmallcode. The minimum acceptable abbreviation is scode. This option is ignored if you do not specify the link option. See also the description of the smallcode linker option. SmallData tells the linker to merge all data and bss sections into a single hunk. The default value is nosmalldata. The minimum acceptable abbreviation is sdata. This option is ignored if you do not specify the link option. See also the description of the smalldata linker option. SourceIs=filename sets the name of the C source file in the object file and in debugging information to the specified value instead of the actual name of the C source file. The minimum acceptable abbreviation is srcis. You can use this option if you plan to rename or move the source file before using the debugger to debug your program. If you are compiling or assembling exactly one source file, sourceis can specify the name of the file to be placed into the debug information. If you are compiling or assembling multiple files, sourceis should specify a directory name (ending with a forward slash or colon). StackCheck generates stack overflow checking code at each function entry. The default value is stackcheck. The minimum acceptable abbreviation is stkchk. When a program is about to run out of stack space, the program displays a requestor and terminates gracefully. For a complete description of the stackcheck option, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." StackExtend generates stack extension code at each function entry. The default value is nostackext. The minimum acceptable abbreviation is stkext. When a program runs out of space in the current stack, a new stack is allocated, and your program continues to run. For a complete description of the stackext option, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." 114 Chapter 8 StandardIO specifies the use of __main instead of __tinymain. The default value is standardio. The minimum acceptable abbreviation is stdio. To use __tinymain, specify nostdio. Using __tinymain makes your program require less space, but you cannot read from or send output to stdin, stdout, and stderr. This option is ignored if you do not specify the link option. StartUp=module-name specifies which startup module to use. The default value is c (for c.o). The minimum acceptable abbreviation is strt. If the module name that you specify does not contain a colon (:), forward slash (/), or period (.), the compiler adds lib: to the beginning and . o to the end of the name you specify. If you do not want to compile with a startup module, specify nostartup. This option is ignored if you do not specify the link option. Strict enables a large number of diagnostics dealing with portability and questionable situations in your code. The default value is nostrict. Specifying strict may produce warning messages for situations that are not a problem. For more information on improving the portability of your code, see Chapter 13, "Writing Portable Code." StringsConst tells the compiler to consider all string constants to be of type const char *. The default value is nostringsconst. The minimum acceptable abbreviation is strcons . If you do not specify stringsconst, the compiler considers string constants to be of type char *. If you specify stringsconst, passing a string constant to a function that expects the type char * generates a warning message indicating that the function may modify the string constant. StringMerge merges all identical string constants in the C source file and places all strings, all data declared static const, and all auto initializers in the code section instead of the data section. The default value is nostringmerge. The minimum acceptable abbreviation is strmer. Using Compiler Options 115 If you specify stringmerge, the compiler examines each string constant defined in the code and checks for duplicates. If the compiler finds a duplicate string constant, it forces both references to refer to the same memory location. If you specify stringmerge and you modify a string constant, the constant is modified in all locations. For example, suppose you have the following program: #include void modifyme(char *); void main(void) { modifyme("Hello, World! \n"); printf("Hello, World ! \n"); } void modifyme(char *msg) { strcpy(msg, "Foobar\n"); } If you compile the program with stringmerge, the program prints Foobar. If you compile the program with nostringmerge, the program prints Hello, World!. The stringmerge option has two useful side effects. Because some data are placed in the code section: [] Less data needs to be placed into the near data section. If you have more than 64k of data, you can use the stringmerge option to try to reduce the amount of data and allow your code to continue to use the near data model. [] The string constants are addressed relative to the PC (program counter) instead of the beginning of the near data section. Therefore, it is possible to generate programs with no near or far data. For more information on the code and near data sections, see Chapter 12, "How Does the Compiler Work?" 116 Chapter 8 StripDebug strips all debugging information from the final executable. The default value is nostripdebug. The minimum acceptable abbreviation is stripdbg. This option is ignored if you do not specify the link option. StructureEquivalence tells the compiler not to issue messages if a pointer to one structure type is passed to a function when the function expects a pointer to a different type, if the type passed is equivalent to the type expected. The default value is nostructureequivalence. The minimum acceptable abbreviation is streq. For information on using"equivalent structures, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." To =filename is included only for compatibility with the slink command. to is a synonym for the programname option. This option does not have a negative form. Trigraph specifies whether to use ANSI trigraphs. The default value is notrigraph. The minimum acceptable abbreviation is trig. Specifying trigraph slows down the compiler. Underscore adds underscores to the beginning of all external names defined in any assembler source files assembled. The default value is nounderscore. The minimum acceptable abbreviation is uscore. The underscores allow you to refer to these names in assembly language in the same way you do in C source files. This option is ignored if you do not specify any assembly-language files in the sc command. For more information, refer to Chapter 11, "Using Assembly Language with C Language," in SAS/C Development System User's Guide Volume 2. UnsignedChar makes the default type of char variables unsigned instead of signed. The default value is nounsignedchar. The minimum acceptable abbreviation is uchar. This option defines the preprocessor symbol _UNSCHAR. Using Compiler Options 117 UtilityLibrary generates inline calls to the AmigaDOS 2.0 ROM-resident library utility. library to do integer multiplication and division instead of calling SAS/C library functions to do these operations. The default value is noutilitylibrary. The minimum acceptable abbreviation is utillib. Specifying utilitylibrary makes your executable smaller and faster by taking advantage of 68020 instructions if they are available, but your program runs only under AmigaDOS 2.0. If you link using the sc command and the utilitylibrary and link options, sc defines all the SAS/C library integer conversion stub routines to stubs that call utility. library. This action prevents the SAS/C library routines that use integer conversion routines from using the SAS/C versions of the routines. If you link using the slink command, you need to specify the following def ine linker options: define __CXM33=__UCXM33 define __CXD33=__UCXD33 define __CXM22=__UCXM22 define __CXD22=__UCXD22 These define options are in the file LIB:utillib.with, so you can link with the following command: slink with LIB:utillib.with options Verbose displays messages about each stage of compiling and linking. The default value is noverbose. Version prints a banner containing the compiler version number and a copyright message. The default value is version. The minimum acceptable abbreviation is ver. Warn=n enables the specified compiler warning message. The minimum acceptable abbreviation is wrn. This option does not have a negative form. You can specify a 11 or a to enable all warning messages, or you can specify one or more message numbers to enable only those 118 Chapter 8 messages. To specify several message numbers, separate each number with a plus (+) sign or a comma (,). You can specify the warn option as many times as necessary. See also the description of the error and ignore options. WarnVoidReturn issues a warning message if a function declared as returning an integer actually returns no value. The default value is warnvoidreturn. The minimum acceptable abbreviation is wvret. The nowarnvoidreturn option suppresses the return value mismatch warning message for functions declared as returning an integer, but that do not contain a return statement or that do not include an expression in the return statement. With=filename specifies the name of a file containing additional options. The additional options are read immediately, as if they were specified in the sc command at the position occupied by the with option. Options specified after the with option may override options specified in the with file. This option does not have a negative form. You can specify the with option as many times as necessary. Note: Do not confuse this option with the with linker option. XREF is a synonym for the xreference option. XReference produces a cross-reference. The default value is noxreference. The minimum acceptable abbreviation is xref. The compiler writes the output to the filename you specify with the listfile option. If you do not specify an output filename, the compiler uses the name of the first source file you specify but with the extension.lst. XReferenceHeaders generates a cross-reference of user header files. The default value is xreferenceheaders. The minimum acceptable abbreviation is xhead. This option is ignored if you do not specify the xre f erence option. Using Compiler Options 119 XReferenceSystem includes symbols defined in system header files in the cross-reference. The default value is xreferencesystem. The minimum acceptable abbreviation is xsys. This option is ignored if you do not specify the xreference option. Using The compiler automatically defines certain preprocessor symbols each Preprocessor time you run the compiler, and it defines other symbols only when you Symbols Defined use specific compiler options. by the Compiler Table 8.2 lists each of the symbols that the compiler automatically defines each time you run the compiler. Table 8.2 Preprocessor Symbols Symbol Value Defined by the _AMIGA 1 Compiler _M68000 1 __SASC 1 __SASC_60 1 __VERSION__ 6 __REVISION__ 0 __STDC__ 1 __ FILE __ current filename __ LINE __ current line number __ FUNC __ current function __ DATE __ current date __ TIME __ current time Table 8.3 lists each of these preprocessor symbols defined when you use specific compiler options and the options that #def ine these symbols. These symbols are defined to 1 when you specify the corresponding option. For example, if you specify the noansi option, the AMIGA symbol is defined as follows: #define AMIGA 1 120 Chapter 8 Table 8.3 Preprocessor Symbols Symbol Compiler Options Defined by Compiler AMIGA noansi Options LPTR noansi and noshortint SPTR noansi and shortint LATTICE noansi LATTICE_50 noansi _M68010 cpu=68010|68020|68030|68040 _M68020 cpu=68020|68030|68040 _M68030 cpu=68030|68040 _M68040 cpu=68040 _M68881 math=68881 _FFP math=FFP _IEEE math=IEEE _SHORTINT shortint _UNSCHAR unschar _PPONLY pponly _GENPROTO genproto _MGST makegst _GST gst Linking Your Program As described in Chapter 2, "Using Your SAS/C Development System," you can link your program from the Shell by specifying the link option in the sc command or from the Workbench screen by specifying the link option in your scoptions file and double-clicking on the Build icon. You can also compile and link your program in separate steps. If you do not specify the link option on the sc command line, you need to call the linker, slink, to link your program. Use the slink command only if you are limited by the s c command. For the majority of programs, linking with the sc command is much simpler and easier than linking with the slink command. If you link using the sc command, you can specify linker options with the linkeropt compiler option. Using Compiler Options 121 Entering The After you have compiled your program, you can enter the slink slink Command command as follows: slink object-files [options] You must specify at least one object file. You probably also need to specify a startup module and one or more libraries. Specifying Linker The slink command accepts the following options: Options addsym generates hunk_symbol records for all externally-visible symbols in each object file and library module whether or not the object file was compiled with the debug compiler option. This option gives CodeProbe the location, but not the size or type, of any externally visible symbols in your program. batch sets the value of all undefined data symbols to 0 and all undefined code symbols to _ _ _ stub. Normally, slink asks you to enter a value for each undefined symbol. However, if you specify batch, slink does not prompt you to enter values for undefined symbols. If an undefined function is called, the library function _ _ stub (_ _ _stub to the linker) is called instead. The library's version of _ _ stub displays a requester telling you that an undefined routine was called and allows you to choose whether to abort or continue. bufsize n sets the I/O buffer size for slink. By default, slink buffers all object modules. Buffering requires more memory but reduces the time required to link your program. If you run out of memory while linking, try linking with bufsize 4096. This specification tells slink to buffer only one file at a time and to use a buffer size of 4096 bytes. chip specifies that all hunks are to be placed in chip memory regardless of the input object hunk specifications. However, if you specify f a st or chip for the datamem, codemem, or bssmem compiler options, that value overrides this option. The chip option is provided for compatibility with previous versions of the linker. It is recommended that you use the datamem, codemem, and bssmem compiler options instead. define symbol[=value] defines a symbol to be used in the linking process. You can use this option with the prelink option to force specific routines from the 122 Chapter 8 libraries to be linked into your program even though your program does not contain any references to the routines. Remember that linker symbols have an extra underscore added to the beginning of the symbol name. To refer to a function f oo using the define option, you must specify _foo. To refer to registerized functions, add an at (@) sign to the beginning of the symbol name, as in @foo. Note: Do not confuse this option with the define compiler option. fancy enters control characters to highlight and bold headings in the map file. The option is on by default. To disable the use of these control characters, specify the plain option. fancy is ignored if you do not specify the map option. fast specifies that all hunks are to be placed in fast or expansion memory regardless of the input object hunk specifications. However, if you specify fast or chip for the datamem, codemem, or bssmem compiler options, that value overrides this option. The fast option is provided for compatibility with previous versions of the linker. It is recommended that you use the datamem, codemem, and bssmem compiler options instead. faster is included only for compatibility with the Commodore linker, alink. from object-filename(s) identifies the object files that are the primary input to the linker. You can specify the from option as many times as necessary in the slink command. If you specify the object files as the first items in the slink command, you do not need to use the from option. The root option is a synonym for this option. The object files are copied to the root of the object module. You must specify at least one object file in the slink command. fwidth n specifies the filename width, in columns, in the map file. The default value is 16. This option is ignored if you do not specify the map option. height n specifies the total number of lines on a page in a map file. If you specify 0, the linker does not add form feed characters to the file. The default value is 55. This option is ignored if you do not specify the map option. Specifying Linker Options 123 hwidth n specifies the hunk name field width, in columns, in the map file. The default value is 8. This option is ignored if you do not specify the map option. indent n specifies the number of columns to indent on a line in the map file. The map file is indented n columns from the value specified by the width option. The default value is 0. This option is ignored if you do not specify the map option. libfd filename specifies the name of a function description ( . fd) file. Use this option only if you are building a shared library. For information on creating shared libraries, refer to SAS/C Development System Library Reference. libprefix prefix specifies the prefix you want added to the functions listed in the function description ( .fd) file. The default prefix is an underscore ( _ ). Use this option only if you are building a shared library. The libpref ix option allows the library to call entry points within itself, without using the library base. Make sure that the function declarations in your source code match the full name, including any specified prefix. For example, suppose your library has a function called myfunc. Your . fd file contains the following line: myfunc(a)(dO) If you specify a prefix of _ LIB, you should declare the function in your source code as LIBmyfunc, as shown in the following example: #pragma mylibbase myfunc 1e OOl __asm LIBmyfunc(register __d int a) { return a+l; } void test(void) { LIBmyfunc(l); /* Call myfunc directly. */ myfunc(2); /* Call myfunc through the library base. */ } 124 Chapter 8 For information on creating shared libraries, refer to SAS/C Development System Library Reference. library link-library-filename(s) specifies the library files that you want the linker to search for modules referenced in your code. Only referenced modules from library files are included in the final executable module. You can abbreviate this option as lib. librevision n specifies a minor revision number of the library you are creating. If you do not specify a revision number, it defaults to 0. Use this option only if you are building a shared library. For information on creating shared libraries, refer to SAS/C Development System Library Reference. libversion n sets the version number of the library you are creating. You can set the version number to any number from 0 to 255. The default is 1. Use this option only if you are building a shared library. For information on creating shared libraries, refer to SAS/C Development System Library Reference. map [mapfile [map-option[,]map-optlon...]] tells slink to create a map file. The map file contains information on the size and location of all hunks and the value of all symbols. If you do not specify a mapfile, the linker writes the map information to the file executable.map. If you specify a mapfile, you can also specify the following map file options: f lists the hunks in each file h lists hunks by size and originating function l lists hunks by library function o lists hunks in each overlay s lists where symbols are defined x creates a symbol cross-reference that lists where the symbols are defined and their definition. maxhunk n limits to n bytes the size of the hunks that slink creates when merging hunks. By default, there is no limit on hunk size. noalvs issues warning messages if slink generates an automatic link vector (ALV) instruction to resolve 16-bit program counter-relative references. Using this option stops slink from creating a non- relocatable module from what was intended to be relocatable code. Specifying Linker Options 125 nodebug is included for compatibility with previous release of the linker. Use the stripdebug option instead. You can abbreviate this option as nd. onedata tells the linker to merge all data, bss, and chip sections. Merging hunks may decrease the time required to load your program but may produce larger hunks that are difficult to scatter load. overlay identifies the start of an overlay tree. You should enter the overlay option and the list of files in each overlay in a with file, as follows: overlay overlay-1-filename(s) *overlay-2-filename(s) . . . # You must terminate the overlay tree with a line consisting of a single pound (#) sign. For more information, see " Using Overlays," later in this chapter. See also the description of the with option. ovlymgr filename tells slink to use the filename you specify as the overlay manager instead of the default filename, ovs .o, which is contained in the libraries. The file you specify should consist of a single code hunk named NTRYHUNK and define the global symbol _ ovlyMgr. prelink tells slink to produce an object module with symbol references and definitions still intact. You can then link with this object module to produce an executable module. This option is useful if you are developing a large application and changing only a single source module. Do not specify this option if you are using overlays. plain turns off the fancy option. This option tells the linker not to enter control characters for highlighting and bold in the map file. This option is ignored if you do not specify the map option. pwidth n specifies the width of program unit name field in the map file. The default value is 8. This option is ignored if you do not specify the map option. 126 Chapter 8 quiet suppresses all linker messages except error messages. root object-filename(s) specifies the object files that are the primary input to the linker. These object files are always copied to the root of the object module. You must specify at least one object file for the root. If the primary input files appear as the first option to slink, then the root keyword is optional and may be omitted. The from option is a synonym for root. You can specify the root option more than once. The files you specify with root are added to the list of files to be linked. swidth n specifies the width of the symbol names field in the map file. Default value is 8. This option is ignored if you do not specify the map option. smallcode tells the linker to merge all code hunks. You can abbreviate this option as sc. smalldata tells the linker to merge all data and bss sections. Merging hunks may decrease the time required to load your program, but may produce larger hunks that are difficult to scatter load. You can abbreviate this option as sd. The smalldata option does not merge chip data with non-chip data. To merge chip data also, specify the onedata option instead. stripdebug suppresses any H_DEBUG and H_SYMBOL debug information in the final executable file. to filename specifies the name of the final executable module. If you do not specify a to filename, the linker uses the filename of the second object module listed with the from option but drops any file extension. The first module is assumed to be startup code. verbose prints the names of each file as the file is processed. verify filename specifies a file to which you want the linker to write all messages. If you do not specify the verify option, the linker writes all messages to stdout. You can abbreviate this option as ver. width n sets the maximum line length for the map and cross reference listing files. The default value is 80. This option is ignored if you do not specify the map option. Specifying Linker Options 127 with filename specifies a file containing slink options. The linker processes the contents of with files as if you had specified the option in the slink command. You can specify the with option as many times as necessary. Also, you can enter with options in a with file. The following is an example with file. from lib:c.o vtl00.o init.o window.o xmodem.o remote.o kermit.o script.o library lib:sc.lib lib:amiga.lib verbose smallcode smalldata to vtl00 Note: Do not confuse this option with the with compiler option. xref filename specifies a file to which you want the linker to write cross reference information. If you do not specify xref, but you specify the map option, the linker writes the cross reference information in the map file. Note: Do not confuse this option with the xref compiler option. Using Overlays Overlays are intended primarily for large applications (l00k or more) that must run in a small amount of memory and leave more room for data. Overlays are groups of functions (and the data they require) that reside in memory only while in use. When the group in memory is no longer needed, the overlay manager reclaims the memory used by this group and loads in the next group of functions (and data). Before deciding to use overlays, consider using multiple shared libraries instead. If memory is tight, the AmigaDOS system removes unused shared libraries, thereby giving you some of the benefits of overlays. On systems with more memory, the AmigaDOS system allows shared libraries to remain resident, which improves performance. Use overlays only in very tight memory situations. The overlays are organized into an overlay tree. The overlay tree consists of a root node, which is always resident in memory, and one or more overlays. Figure 8.1 shows an example overlay tree. 128 Chapter 8 Figure 8.1 root An Example Overlay .-------|---------------. Tree | | overlay1 overlay2 | .-----------|-----------. | | overlay3 overlay4 | overlay5 Overlays at the same level in the tree are mutually exclusive. In this example tree, the functions in overlays 1 and 2 are mutually exclusive, and the functions in overlays 3 and 4 are mutually exclusive. If any function in overlay 1 is running, overlay 2 cannot be loaded. However, if your program calls a function that is in overlay 2, the overlay manager reclaims the memory occupied by overlay 1 and loads overlay 2. Then, if your program calls a function in overlay 3, the overlay manager loads overlay 3. If overlay 3 is loaded, overlay 5 can be loaded if necessary, but overlay 4 cannot be loaded. A function in an overlay can call functions in only certain other overlays. For example, a function in overlay 3 can call a function in overlays 5 and 2 and in the root node. The following list shows which functions the functions in each overlay of the example tree can call. Functions in.........Can call functions in root can call functions in overlays 1 and 2 1 can call functions in the root node 2 can call functions in the root node and overlays 3 and 4 3 can call functions in the root node and overlays 2 and 5 4 can call functions in the root node and overlay 2 5 can call functions in the root node and overlays 2 and 3. As you can see, applications best suited to overlays are those that are modular and have a definite calling hierarchy among the functions. You must determine which functions should be in each overlay. Decide which functions can operate independently of others. The root node must Compiling and Linking Your Program 129 contain your main program and should contain any functions that are called frequently or by many other functions in the program. The root node usually contains the libraries also. In general, the more frequently you call a function, the closer it should be to the root node. You can have up to 50 overlays. Your tree could have all overlays hanging from the root node, or your tree could be organized as one long chain of overlays. Organize the overlays of your tree efflciently; that is, according to the calling hierarchy of your program. If you create an inefficient tree, your program may not run efficiently because the overlays will have to be swapped more often. If you create an incorrect tree, slink issues a warning message. To use overlays, you should enter the overlay option and the overlay filenames in a with file, as follows: overlay overlay-1-filenames *overlay-2-filenames List the filenames for each overlay on a separate line, and separate the filenames with plus ( + ) signs. If you cannot fit all of the filenames on one line, end the line with a plus sign, and enter the remaining filenames on the next line. Indicate the depth in the tree of the overlay by entering the appropriate number of asterisks at the beginning of the line. The overlays immediately beneath the root node are at depth 1, but you should not list them with asterisks. For overlays at depth 2, begin the line(s) with one asterisk; for overlays at depth 3, begin the line(s) with two asterisks, and so on. Enter an overlay immediately after the overlay to which it is subordinate. Terminate the overlay tree with a line consisting of a single pound (#) sign. For example, Figure 8.2 shows the same overlay tree as in Figure 8.1, but figure 8.2 shows which object files comprise each overlay. 130 Chapter 8 Figure 8.2 root node __________ Example Overlay Tree | | with Filenames | main | \________/ | _____/\______ / \ _____|____ ____|_____ overlay1 | | | | overlay2 |beech.o | | ash.o | |maple.o | \________/ \________/ | _____________/\____ / \ _______|____ ________|_________ overlay3 | | | | overlay4 | fir.o | | sweetgum.o | | pine.o | | pecan.o | \__________/ \______________/ ______|_____ overlay5 | | | birch.o | \__________/ The with file for the example in Figure 8.2 looks like this: overlay beech.o+maple.o ash.o *fir.o+pine.o **birch.o *sweetgum.o+pecan.o # Suppose you have three files: hw.c, hello.c, and world.c. The file hw.c contains the following functions: #include int main(void) { Hello(void); World(void); return(O); } Compiling and Linking Your Program 131 void SayWord ( s ) char *s; { printf ("%s", s); } The file hello.c contains only one function: void Hello ( void ) { SayWord("\nHello, " ); } world.c also contains only one function: void World ( void ) { SayWord("World! \n"); } After you compiled these three files, you have the three object files hw.o, hello.o, and world.o. To link this application, you can create a with file that contains all of the link options you need, including overlay specifications. from lib:c.o hw.o overlay hello . o world . o # library lib:sc.lib lib:amiga.lib map fhlosx to hw slink evaluates the with file, creates an executable module named hw, and creates a map file named hw.map. The executable module consists of a root node and two overlays. The root node contains all of the code and data for c.o, hw.o, sc.lib, and amiga.lib. One overlay contains the code and data for hello.o, and the other overlay contains the code and data for world.o. Figure 8.3 shows the overlay tree for this application. 132 Chapter 8 Figure 8.3 ____________ Overlay Tree for hw | c.o | | hw.o | | sc.lib | | amiga.lib | \__________/ ________|___________ _____|____ ______|____ | hello.c | | world.c | |__________| |___________| You can run this application in the same way you run an application that does not use overlays. The overlay manager loads overlays as necessary. Specifying Using overlays modifies the behavior of some compiler options. The Compiler Options following list describes each of the options affected by overlays. with Overlays data=near places all data not declared with __ far or __ chip in the near data section. If you are using overlays, the near data segments of all files compiled with data=near are moved to the root node. Therefore, you cannot statically initialize near data items into code hunks that are not in the root node. For example, you cannot initialize a character pointer to a constant string in an overlay node if you specify the stringmerge option. smallcode merges all code hunks into a single hunk. If you are using overlays and you specify smallcode, slink merges as much of the code as possible without crossing overlay boundaries. The linker does not move code out of the overlay in which it was defined. smalldata merges all data and bss hunks into a single hunk. The near data section is always placed in the root node. However, sl i nk does not merge hunks that are in overlays that are not named __MERGED into the near data section. stringmerge places string constants into the code section, and the strings themselves are overlaid if the module they are used in is overlaid. Therefore, the value of the string constant may change as its overlay node is swapped out. For example, a function may return a string Compiling and Linking Your Program 133 constant or assign it to an external variable. It is recommended that you do not compile with stringmerge if you are using overlays. Customizing the For some applications, you may want to replace the overlay manager with Overlay Manager a custom overlay manager. For example, you can write an overlay manager to support function calls across mutually exclusive overlays. This section describes the necessary attributes of an overlay manager. The overlay manager must contain one code hunk named NTRYHUNK and define the global symbol _ ovlyMgr. section NTRYHUNK,code xdef ovlyMgr First: bra FirstModule ovlyMqr: ;Overlay manager code goes here. FirstModule: lea First(PC),a3 ; pointer to start of module move.l -4(a3),d7 ; BPTR to next seglist entry asl.l t4,d7 ; make into APTR move.l d7,a3 jmp 4(a3) ; jump to code in next hunk Assemble this code with the -u assembler option so that the assembler adds the necessary underscores to all global symbols. The linker makes NTRYHUNK the first hunk in the executable and does not merge this hunk with any other hunks. Therefore, NTRYHUNK must also contain a valid entry point to the program and properly transfer control to the rest of the program. The first instruction in the preceding code branches to the symbol FirstModule, where the seglist is decoded, and a jump instruction transfers control to the next hunk in the segment list. For more information, examine the file ovs.a in the source directory. This file contains the source to the default overlay manager. 134 135 9 Running Your Program from the Workbench Screen 135 Introductlon 135 Working with argc and argv 135 Running From the Shell 136 Running From the Workbench Screen 137 Managing the Standard I/O Window 137 Eliminating the Window 137 Changing the Window Attributes Introduction If you run your program by double-clicking its icon from the Workbench screen, your program runs under a different environment than programs that are run from the Shell. Specifically: [] If not handled correctly, the command line arguments argc and argv receive different values that may cause unwary programs to crash. [] If your program uses stdin, stdout, or stderr, the library routine __main opens a console window to which your program writes output and from which it reads input. The following sections describe how to manage these unusual situations. Working with argc and argv Programs that run from the Workbench screen receive a different environment than those run from the Shell. The following sections describe the different environments. Running From the If you run your program from the Shell, your program receives two Shell arguments, argc and argv. argc is an integer guaranteed to have a value of at least 1. Unless you modify __main as described in Chapter 10, "Using Startup Modules, Autoinitialization, and 136 Chapter 9 Autotermination Functions," argv is an array of 32 character pointers that point to the different items on the command line: argv[0] is a pointer to the name of the command that was executed. argv[1] to argv[nl are pointers to the arguments entered after the command. The number n represents the number of arguments specified. The maximum number of arguments is 30. argv[n+1] to argv[31] are NULL. Running From the If you run your program from the Workbench screen, the startup code Workbench sets up argv and argc in a different way than if your program is run Screen from the Shell. argc is set to O (zero) to give you a quick way to check in your program if you are running from the Workbench screen, and argv is a pointer to a struct WBStartup instead of an array of character pointers. The definition of struct WBStartup is in the header file workbench/startup.h. To eliminate any problems caused by running your program from the Workbench environment, structure your program as follows: int main(int argc, char *argv[1]) { struct WBStartup *startup; if(argc == O) { /* The program was started from the Workbench. */ /* Use the WBStartup message instead of argc and argv. */ startup = (struct WBStartup *)argv; ... } else { /* The program was started from the Shell. */ /* Use argc and argv as usual. */ ... } } For more information on main, refer to SAS/C Development System Library Reference, Version 6.0. Running Your Program from the Workbench 137 Managing the Standard I/O Window When you run a program from the Workbench screen, the compiler opens a standard I/O window in which your program can read from and write to stdin, stdout, and stderr. You can delete the window, change its size, or add a title. The window is opened by the library routine __main, which is automatically run before your main routine if you link with a startup module. Eliminating the If your application does not use stdin, stdout, or stderr, you can Window use an alternate routine that does not open the window: [] You can use the alternate routine __tinymain. If you link your program using the link compiler option, specify the nostdio option to delete the window. If you run the linker by specifying the slink command, specify the define linker option as follows: define ___main=___tinymain Use this define option regardless of any other compiler options you are using. This option works even if you are using registerized parameters. [] You can write your own routine. You can copy main.c from the sc: source directory and modify it for your application. >> Caution Your program may crash. If you attempt to use any function that refers to stdin, stdout, or stderr in a program run from the Workbench screen after deleting the standard I/O window, your program will crash. Such functions include printf and scanf (but not fprintf or fscanf). Changing the To keep the window but change its attributes you need to declare the Window external variable __ stdiowin in your program. Normally, __main Attributes gets the definition of __ stdiowin from the library with which you link your program. However, if you declare __ stdiowin in your program, __main uses the definition in your program. This variable is declared in the SAS/C Libraries as follows: char __stdiowin[]= "CON:10/10/320/80/"; 138 Chapter 9 This specification opens a console window starting at location (10,10) that is 320 pixels wide and 80 pixels high. For more information on console specifications, refer to The AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991). To change the window attributes, include a line similar to the previous line in any C source file in your project. Declare this variable external to any function, and be sure to statically initialize the variable. (Any changes made to this external variable after your program starts do not affect the window.) For example, to make the initial window 600 pixels wide and 100 pixels tall and add a window title of "My Window," you would enter the following line: char __stdiowin[]= "CON:10/10/600/100/My Window"; If you are running under AmigaDOS 2.0, __main appends the contents of the array __stdiov37 to the __stdiowin variable before opening the window. This array contains keywords that control other aspects of the window and is defined in the SAS/C Libraries as follows: char __stdiov37[]= "/AUTO/CLOSE/WAIT"; These keywords do the following to your startup window: /AUTO indicates that you do not want the window to open unless output is written to or input is read from the window. /CLOSE adds a Close gadget to the window. /WAIT specifies that you do not want the window to close until the user clicks on the Close gadget or presses Ctrl-\ (End-of-File). For more information on CON: keywords, refer to The AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991). To change these keywords or add additional AmigaDOS 2.0 keywords, include a line similar to the previous line in any C source file in your project. Declare this variable external to any function, and be sure to statically initialize the variable. (Any changes made to this external variable after your program starts do not affect the window.) The keywords you specify are appended to __stdiowin only if your program is running under AmigaDOS 2.0. If your program is run under earlier versions of the AmigaDOS operating system, you get a normal console window. Note: You must declare _ _ stdiowin and _ _ stdiov37 as external variables exactly as shown. Do not declare them as follows: char *__stdiowin = "specification"; /* WRONG! */ 139 10 Using Startup Modules, Autoinitialization, and Autotermination Functions 139 Introduction 140 Understanding Startup Modules 140 Modifying__main 141 Linking with a Startup Module 142 Creating Standard Programs 142 Creating Detachable (Load and Stay Resident) Programs 143 Creating Residentable Programs 144 Creating Shared Libraries 145 Writing Applications without a Startup Module 145 Using Autoinitialization and Autotermination Functions 147 Initializing System Library Bases Introduction This chapter describes how to use startup modules, autoinitialization functions, and autotermination functions. Specifically, it describes the following: [] the function of a startup module [] how to link your program with a startup module [] how to use the startup modules distributed with the SAS/C Development System [] how to write a program that does not use a startup module [] how to specify autoinitialization and autotermination functions. 140 Chapter 10 Understanding Startup Modules A startup module initializes the environment in which your program runs and performs certain cleanup tasks after your program has finished running. The SAS/C Development System provides six startup modules: c.o is for use with standard programs. cres.o is for use with residentable programs. cback.o is for use with detachable programs. catch.o is for use when you are debugging standard programs. catchres.o is for use when you are debugging residentable programs. The specific things that the startup module does depends on the startup module with which you link your program and on whether you run your program from the Shell or the Workbench screen. However, all startup modules perform some of the same tasks. For example, each startup module does the following: [] initializes the near BSS section. [] gets startup information from the Workbench screen (if invoked from the Workbench screen). [] initializes DOSBase and SysBase. [] marks the bottom of the stack. [] calls __fpinit, which looks for autoinitialization functions. [] calls __main, which calls your program. If your program requires more than 30 command line arguments, you need to modify the default __main function as described under "Modifying __main." calls __fpterm, which also looks for autotermination functions. Modifying __main The default __main function must convert the incoming command line to the (argc, argv) format required by the ANSI Standard. __main performs this conversion by using a local array with 32 elements to represent argv. One element is used for the program name, and the ANSI Standard requires at least one NULL element at the end. Therefore, you are limited to 30 arguments on the command line of your program. If you need more arguments on the command line, you have two choices: [] If you only want to raise the argument limit, copy sc: source/ _main.c to your project directory. Change the #define statement for the symbol MAXARG to the new maximum number of arguments. Then, recompile _main.c and link it into your program. Using Startup Modules 141 [] If you need an unlimited number of arguments, copy sc:source/_main.c to your project directory. Modify the source code to allocate an array of pointers to use for argv. Make sure you use the malloc or calloc function to allocate the memory. These functions will free the memory correctly when your program exits. Linking with a Startup Module To use a startup module, you must link your program with it. You can link your program by using the link option on the sc command or by entering the slink command. You can specify the link and, if necessary, the startup option on the sc command line. If you specify only the link option, sc tells the linker to link your program with c.o. If you want to link with another startup module, specify the module name with the startup option. If the module name that you specify does not contain a colon (:), forward slash (/), or period (.), sc adds the LIB: prefix and .o extension to the filename that you specify. For example, to link with cres.o, you can enter the sc command as follows: sc startup=cres link C-source-file To specify a startup module with the slink command, enter the slink command in the following format: slink startup-module+obj-module to executable lib library-files To use some startup modules, you need to declare certain variables in your program. The following sections describe how to use startup modules for the type of program you want to run. Programs linked with any startup module except cback.o run under the process in which they were invoked. When you enter the name of an executable module at the Shell prompt, that program runs in that Shell's process and uses the Shell's process number and stack (unless you specify a value for __stack and the Shell's stack is smaller than the specified value). Therefore, you cannot enter commands into or close the Shell from which the program was invoked until the program finishes running. Note: Even if you use the run command to run the program, you cannot close the window from which the program is run unless you redirect the input and output as in the following example: run >nil: > Caution Creating this snapshot file may corrupt your hard drive. Do not ship commercial products linked with catch.o. You can use the tb utility to process this snapshot file and display the traceback information. For more information about processing snapshot files, refer to the description of the tb utility in SAS/C Development System User's Guide, Volume 2: Debugger, Utilities, Assembler, Version 6.0. Creating A detachable program is a program that runs in the background. It does Detachable (Load not run as part of the originating Shell's process. You can continue to and Stay enter commands into, or even close, the Shell from which the program Resident) was started without affecting the program. Programs You can use the startup module cback.o to create detachable programs. When you link with cback.o, your program allocates a new stack and launches itself as a new process. For an example of a program that links with cback.o, see the directory sc:examples/cback. You should use cback.o for any program that: [] does not send output to the Shell from which it was invoked (except an initial banner) [] needs to be memory resident. To use cback.o, you add the following external definitions to your main program if your program requires values other than the defaults: long __stack = amount; allocates stack space for the created task. Many detachable programs only need a stack size of 4000 bytes (the default). However, you can change this figure to suit your application. char *__procname ="program-name"; specifies the name of the process to be created. The default value is Background_Process. long __priority = priority; sets the priority of the process to be created. For most programs, you should set the task priority to 0, which is the default. However, you can change this figure to suit your application. Using Startup Modules 143 long __BackGroundIO = value; indicates whether output will be sent to the Shell from which the program was invoked. The default value is 0, which tells cback.o that no output is sent to the originating Shell. Setting this value to 1 tells cback.o to set _ Backstdout to point to the Shell. extern BPTR _Backstdout; contains the file handle of the originating Shell (if __ BackGroundIO was set to 1). _ Backstdout is an AmigaDOS file handle and, therefore, you must use the AmigaDOS function Write instead of the SAS/C functions such as write or fprintf to write to this file. You must close this file with the AmigaDOS Close function when you have finished writing to the Shell window. If you do not close _ Backstdout, the originating Shell cannot close. If your program creates a resident task that needs to print messages in the Shell, your program should pass _ Backstdout to this task. If the _ Backstdout file handle is NULL, your program cannot send output to the window. The handle may be NULL if the program was invoked from the Workbench screen or from another program that did not have a Shell open. If you want to make sure that only one copy of your program is running in the background, have your program create a global message port with an unique name. Subsequent invocations of your program should use the exec function FindPort to see if the port exists and, if the port exists, pass any commands to the running program through the message port and exit immediately. See the directory sc:examples/cback for sample code. Programs linked with cback.o cannot be made resident with the AmigaDOS resident command. Creating A resident program is a program that remains loaded in RAM. You do not Residentable have to reload a resident program each time you want to run it. Programs To create a resident program, follow these rules: [] Compile with the data=near option (the default). [] Make sure that all external data declared with the __far or __chip keywords are read-only. [] Use #pragma statements instead of the linker stubs in amiga . lib when possible because amiga.lib uses absolute addressing. If required, you can link with amiga . lib if the linker does not generate any warnings about references to absolute data. [] Link your program with cres.o instead of c.o. [] Use the AmigaDOS resident command to add the program to the resident list maintained by the Shell. 144 Chapter 10 A resident program must be re entrant and re-executable, and it cannot write to far data. For each invocation of a resident program, cres.o copies the near data section, so the program can read and write to near data. If you link your program with cres.o and your program refers to f ar or chip data, the linker issues warnings. If your program reads this data only, you can ignore the warnings. You cannot use the __saveds keyword or compile with the saveds option if you link with cres.o. Each time the program is run, a new near data segment is created, initialized data are copied into the new segment, and relocations are performed inside the segment. When the program finishes, the segment is released. slink creates the following symbols when you link your program: _LinkerDB points to the near data section. RESBASE specifies the offset of _ LinkerDB in the near data section (0 or 0x8000). RESLEN specifies the total number of bytes of initialized and BSS data. NEWDATAL specifies the number of longwords of initialized data. For more information about resident programs, refer to the description of the AmigaDOS resident command in Using the System Software (Commodore-Amiga, Inc. 1990) or see the example in sc:examples/cres. If you are debugging a residentable program, you can use the catchres.o startup module to capture information if your program terminates abnormally. If you link with catchres.o and your program terminates abnormally, catchres.o asks you if you want to create a snapshot file. A snapshot file contains traceback information for your program such as register values, symbol cross references, and stack information. >> Caution Creating this snapshot file may corrupt your hard drive. Do not ship commercial products linked with catchres.o. You can use the tb utility to process this snapshot file and display the traceback information. For more information about processing snapshot files, refer to the description of the tb utility in SAS/C Development System User's Guide, Volume 2. Creating Shared You can use the modules libent.o, libinit.o, and libinitr.o to Libraries create shared libraries. For information on creating shared libraries, refer to SAS/C Development System Library Reference, Version 6.0. Using Startup Modules 145 Writing Applications without a Startup Module If you do not want to link your program with a startup module, follow these guidelines when writing and compiling your program: [] Your program must initialize DOSBase and SysBase, if your program makes any calls to dos.library and exec.library, respectively. For additional information, see "Initializing System Library Bases," later in this chapter. [] Do not use any SAS/C I/O functions such as fopen, read, printf, and so on. [] Add the _ _ saveds keyword to the first function in the first object module in your program. [] Compile your program with the nostackcheck option. [] Be aware that the uninitialized near data are not initialized to 0. [] Register A0 points to the command line entered by the user. You can parse the arguments from A0 or, under AmigaDOS 2.0, call ReadArgs to get the arguments. [] Your program will start executing at the first function in the first module specified on your slink or sc command line. This function should be declared with the _ _ saveds keyword. [] Unless you write code to reply to the Workbench startup message, your program will not run from the Workbench screen without crashing the machine. For an example, see sc:examples/nostartup. Using Autoinitialization and Autotermination Functions If you link with one of the startup modules provided by the SAS/C Development System, you can designate functions to be called before your program starts (autoinitialization functions) and after it terminates (autotermination functions). To designate an autoinitialization function, begin the function name with _ STI. To designate an autotermination function, begin the function name with _ STD. The linker searches the functions defined in your program for functions whose names start with the _ STI or _ STD. All functions starting with _ STI are assumed to be autoinitialization functions and are called from the startup code before _ _ main is called. All functions starting with _ STD are assumed to be autotermination functions and are called after your program exits. 146 Chapter 10 Autoinitialization and autotermination functions take no parameters and return no values, as shown in the following example: void _STImyinit(void) { . /* your code here */ . } void _STDmyterm(void) { . /* your code here */ . } If the linker finds at least one autoinitialization function, it creates an array of function pointers containing one pointer for each autoinitialization function. The array is named _ _ ctors (for "constructors"), and its last entry is always NULL. The __ fpinit function looks through this array and calls each autoinitialization function before calling _ _ main. Similarly, if the linker finds at least one autotermination function, it creates an array of function pointers called__ dtors (for "destructors") containing one pointer for each autotermination function. The array's last entry is always NULL. The _ _ fpterm function looks through this array and calls each autotermination function after your program exits. The following figure shows the order in which modules are called when you run your program. Using Startup Modules 147 Figure 10.1 Startup module Startup Modules, ____________________ Autoinitialization | | __________________________________________ Functions, and | Call __fpinit ----|-->| Set up for floating-point operations | Autotermination | | | Call the funtion in __ctors | Functions | | |__________________________________________| | | __________________________________________ | Call __main ------|-->| Initialize file I/O | | | | Call main (your program) | | | | Cleanup file I/O | | | |__________________________________________| | | __________________________________________ | Call __fpterm ----|-->| Cleanup from floating point operations | | | | Call the functions in __dtors | | | |__________________________________________| | | __________________________________________ | Call _MemCleanup --|-->| Free heap memory | |____________________| |__________________________________________| If slink does not find any autoinitialization or autotermination functions, it substitutes a longword zero for any references to __ctors or __dtors. If you write your own startup module, check that __ctors and __dtors are not NULL before accessing the array. Do not use level 1 or 2 I/O functions (such as fopen and open) in your autoinitialization functions because they have not yet been initialized. However, you can use AmigaDOS I/O functions (such as Open). Similarly, you cannot use level 1 and 2 I/O functions in your autotermination functions because all level 1 and 2 files have already been closed. You can use the ANSI standard memory allocation routines (such as malloc, free, and calloc) in autoinitialization and autotermination functions. All memory allocated with these routines and not yet freed in your program is still valid in your autotermination functions. Initializing System Library Bases If you declare but do not define a system library base in your own code, the library base is automatically initialized. The autoinitialization code calls OpenLibrary to initialize the library base, and the 148 Chapter 10 autotermination code calls CloseLibrary to close the library. In the following example, IntuitionBase is automatically initialized. #include /* The following line declares Intuition8ase but does */ /* not define it. This line is not required, because */ /* proto/intuition.h also declares IntuitionBase. In */ /* this program, IntuitionBase is automatically */ /* initialized. */ extern struct IntuitionBase *IntuitionBase; int main(void) { struct Window *w; w = OpenWindow(...); ... } The following table lists the system libraries whose bases are automatically initialized by the autoinitialization code. Table 10.1 Library Bases for Name Base .library Files asl.library (2.0) AslBase commodities.library (2.0) CxBase diskfont.library DiskfontBase expansion.library ExpansionBase gadtools.library (2.0) GadToolsBase graphics.library GfxBase icon.library IconBase iffparse.library IFFParseBase intuition.library IntuitionBase ( continued) Using Startup Modules 149 Table 10.1 (continued) Name Base keymap.library KeymapBase layers.library LayersBase mathffp.library MathBase mathieeedoubbas.library MathIeeeDoubBasBase mathieeedoubtrans.library MathIeeeDoubTransBase mathieeesingbas.library MathIeeeSingBasBase mathieeesingtrans.library MathIeeeSingTransBase mathtrans.library MathTransBase translator.library TranslatorBase utility.library UtilityBase workbench.library WorkbenchBase . Note: DOSBase and SysBase are initialized by the startup code even if you define them. As stated before, a system library base is not initialized if you define the library base in your code (except DOSBase and SysBase). For example, the following code defines the library base and, therefore, the base is not automatically initialized. #include /* The following line defines IntuitionBase, so */ /* it is not automatically initialized. */ struct IntuitionBase *Intuition8ase; 150 Chapter 10 int main(void) { struct Window *w; w = OpenWindow( . . . ); /* Crash! IntuitionBase in NULL */ ... } For more information on defining library bases, refer to SAS/C Development System Library Reference. The autoinitialization functions pass the value of the external long integer _ _ OSlibversion to OpenLibrary. If your program runs only under a specific version of the operating system, declare this variable in your code and initialize it as necessary. For example, if your program requires the AmigaDOS operating system, Version 2.0 (which is library revision 37), you can enter the following line in your program external to any function: long_ _ OSlibversion = 37; The following table lists the library revision numbers for each version of the operating system. OS Library Version Revision 1.2 33 1.3 34 2.0 36 (Preliminary 2.0) 2.04 37 If the autoinitialized libraries cannot be opened, the library function __autoopenfail is called. The version of __autoopenfail in the libraries prints a message indicating which library could not be opened and then terminates your program. You can replace this function by declaring it in your code as follows: void __autoopenfail(char *lib) { Using Startup Modules 151 /* your code here */ } The lib parameter is the name of the library that failed to open. If you want your program to terminate after the call to __autoopenfail, the last action of __autoopenfail should be to call _XCEXIT. If __autoopenfail returns without calling _XCEXIT, the startup proceeds normally. The source code to the default __autoopenfail function is in sc:source/autoopenfail.c. As an additional example, sc:source/intuitlib.c contains the autoinitialization and autotermination code for intuition. library. 152 153 11 Using Amiga Specific Features of the SAS/C Language 153 Introduction 154 Using Special Keywords 155 Using__aligned 156 Using__chip, __far, and__near 157 Using __interrupt 157 Using __asm, __regargs, And __stdargs 158 Using__saveds 159 Using__inline 160 Managing Stack Space 161 Using #pragma Statements 163 Using Unnamed Unions 164 Using Implicit Structure References 164 Using Equivalent Structures 166 Using Zero-Length Arrays 167 Specifying the Size of Enumerated Types 168 Using the sizeof and Comma Operators in Preprocessor Directives 168 Using C++ Style and Nested Comments 168 Using National Characters in Variable Names 168 Using Common Model External Data Introduction This chapter describes features of the SAS/C Compiler that are not defined by the ANSI Standard. Specifically, the compiler allows you to do the following: [] use special keywords such as __ aligned and __ saveds [] use #pragma statements [] declare and refer to structure members in special ways [] change the size of enumerated types [] use the sizeof and comma (,) operators in #if directives [] use C+ + style and nested comments [] use national characters in variable names [] use the common model or the strict reference-definition model for external data. 154 Chapter 11 Using Special Keywords The SAS/C Compiler allows the following keywords: __aligned forces an item to be aligned on a four-byte (longword) boundary or forces the declared function to align its stack in the prolog. __chip places the declared static or extern data into chip memory. __far places the declared static or extern data into the far data section or forces calls to the declared function to be made with 32-bit references. __near places the declared static or extern data into the near data section or forces calls to the declared function to be made with 16-bit references. __interrupt indicates that a function may be called as an interrupt routine. __asm allows you to specify which registers a function uses to receive parameters. __regargs forces a function to receive parameters in registers. __stdargs forces a function to receive parameters on the stack. __saveds loads the global data register at the entry to the function. The method used depends on the compiler options you specify. __inline indicates a function that can be inlined by the global optimizer. __stackext indicates a function that should allocate a new stack if the old one is too small. The following sections describe each of these keywords. The __stackext keyword is described under "Managing Stack Space." When used on functions, these keywords must be specified in the correct places, depending on whether the keyword affects the calling function (the caller) or the function being called (the callee). The following list summarizes these points. Using Amiga Specific Features of the SAS/C Language 155 [] Keywords that affect the function's definition (the callee) only may appear on prototypes, but they are optional. These keywords generate warnings if placed on function pointers or data items because they are unnecessary, but the compiler still generates correct code. Keywords in this category are __aligned, __interrupt, __saveds, and __stackext. [] Keywords that affect both the caller and the callee must appear both on the function definition and its prototype. You are required to have a prototype for the function and to add the keywords to the declaration of any function pointers. If you do not do this, incorrect code is generated to pass parameters. For example, if you assign a __regargs function to a function pointer and compile with the parms=stack option, parameters are passed to the __regargs function on the stack instead of in registers. Keywords in this category are __asm, __stdargs, and __regargs. [] Keywords that affect only the calling function are required on function prototypes only. The keywords are ignored if they appear on function definitions or function pointers. Keywords in this category are __near and __far. Be careful when specifying a keyword on a function pointer. The indirection operator (*) in a function definition resets all special keywords. To declare a pointer to a function that, for example, takes its arguments in registers, declare the pointer as follows: void (* __regargs func)(int x, char *p); If you declare the pointer as in the following example, the __ regargs keyword is attached to the function pointer itself rather than the function to which the pointer points: void __regargs (*func)(int x, char *p); Using __aligned The __aligned keyword on a declaration forces the variable being declared to be aligned on a four-byte data boundary relative to the start of the data area in which it is being declared. For structure members, the data area is the start of the structure. For automatic variables, the data area is the beginning of the stack frame for the function in which they are declared. For static and extern variables, the data area is the base of the chip, near, or far data section, depending on the section in which the variable is being allocated. 156 Chapter 11 The __aligned keyword is valid on both functions and data items. For example, the following code declares the structure f ib and the function func: __aligned struct FileInfoBlock fib; int __aligned func(int x) { /* your code here */ } The SAS/C Compiler normally makes sure that the stack is aligned at the beginning of your program and remains aligned for the duration of the program. However, if your code is called from code not compiled with the SAS/C Compiler, you cannot be sure that the stack is correctly aligned at the start of your program. In that case, the __aligned keyword may not work for automatic variables. For example, your code may be: [] called from assembly-language code [] an interrupt routine [] a callback function [] in a shared library. To make sure that the stack is aligned at the beginning of a function, declare the function itself with the __aligned keyword. This action forces the code generated for the function to align the stack on entry. However, the compiler devotes an address register to pointing to the old stack, thereby reducing the number of address registers available for register variables. Using __chip, The __near, __far, and __chip keywords on data items allow you __far, and to specify the section in which you want the compiler to place the item. __near On functions, the __near and __far keywords are required on the function prototype only. By default, the compiler puts all declared static or external data into the near data section. Register A4 points to the start of this section. The compiler generates 16-bit references relative to A4 for external or static items in the near data section. These references generate less code than full 32-bit references. For all items in the far data section, the compiler generates 32-bit references. When the system loader loads your program, it changes these 32-bit references to the actual address of the data item. Using Amiga Specific Features of the SAS/C Language 157 The compiler also generates 32-bit references to items placed in chip memory. Chip memory is the lowest 512K to 2M of system memory, depending on the version of the hardware that you are running. This memory is the memory on your machine that is usable by the custom graphics and sound chips to store bitmaps, sound samples, and so on. You can use the data compiler option to change the default data section for external and static data. You can also override the default for individual data items by declaring the item with the __near, __far, or __chip keyword, as in the following example: __near char a[10]; /* Allocate a 10-byte array in the near sec*/ __far char b[10]; /* Allocate a 10-byte array in the far sec */ __chip char c[10l; /* Allocate a 10-byte array in the chip sec*/ For compatibility with previous releases, the compiler accepts the near, far, and chip keywords without the leading underscores. However, these forms of the keywords violate the ANSI Standard and are not allowed if you specify the ansi compiler option. On function declarations, the __chip keyword is meaningless. However, functions declared with the __near keyword are always called with a 16-bit relative branch even if you compile with the code= far option. Functions declared with the __far keyword are always called with a 32-bit branch even if you compile with the code=near option. For example, the following function is called with a 32-bit branch: __far int func(int x); Using You can declare a function with the __interrupt keyword to indicate __ interrupt that the function is called from an interrupt routine. Defining a function with the __ interrupt keyword turns off the stack checking and extension code for that function and sets condition codes on return. The __interrupt keyword is required on function definitions and tolerated on function prototypes. This keyword is meaningless on function pointers and other data items. Using __asm, Normally, C functions pass and receive parameters by placing them on __regargs, And the stack. To force a function to receive some or all parameters in __stdargs registers, you can declare the function with the __asm or __regargs keyword or compile the function with the parameters=register option. If you declare a function with the __asm keyword, you can specify the registers in which the function receives each parameter. For more 158 Chapter 11 information about the __asm keyword, refer to Chapter 11, "Using Assembly Language with the SAS/C Language," in SAS/C Development System User's Guide, Volume 2: Debugger, Utilities, Assembler, Version 6.0. If you declare a function with the __regargs keyword or if you compile the function with parameters=register, the function receives some of its arguments in registers instead of on the stack. Specifically, the first two pointer arguments are in registers A0 and A1, and the first two integral arguments are in D0 and D1. If you compiled with the math=68881 option, the first two doubles are in registers FPO and FP1. All other arguments are passed on the stack. The compiler identifies functions that expect arguments in registers to the linker by placing an at sign (@) in front of the function name. The at sign replaces the underscore that the compiler normally places at the beginning of function names. If you compile your application using parameters=register but you want one or more functions to receive parameters on the stack, declare those functions with the __stdargs keyword. The __stdargs keyword forces a function to receive parameters on the stack. If you write a function that has the same name as a library function, you need to add the __regargs keyword to your function or compile with the parms=both or parms=register option. For example, you may want to replace the SAS/C library function malloc with your own version of malloc. If you compile with the parms=stack option or define your version of malloc with the __stdargs keyword, then two versions of malloc are linked into your executable. If you use other SAS/C library functions that call malloc, these functions use the version of malloc in the SAS/C libraries. However, your functions that call malloc use your version of malloc. To make sure that all calls to malloc are using your version of malloc, define your version with __regargs or compile with the parms=both or parms=register option. The __asm, __regargs, and __stdargs keywords are important on function definitions and prototypes, and function pointers. Using __saveds If you define a function with the __saveds keyword, the compiler generates extra code at the beginning of the function that loads the address of the near data section into register A4. Defining a function with the __saveds keyword is equivalent to compiling that function with the saveds compiler option. Loading A4 with the address of the near data section is useful if the function in question is called from outside your program. For example, your function may be a callback function or may be a function in a shared library. Using Amiga Specific Features of the SAS/C Language 159 If you do not compile your function with the libcode option, register A4 is initialized with the contents of the absolute symbol _LinkerDB, as follows: LEA _LinkerDB,A4 If you compile your program with the libcode option, the linker treats _LinkerDB as an offset relative to register A6 (the library base) instead of an absolute symbol. Register A6 points to the library base at all entry points to the library. In this case, the instruction generated to load A4 is as follows: LEA _LinkerDB(A6),A4 _LinkerDB is initialized by the linker to point to the near data section. Programs that are residentable cannot refer to absolute symbols. Therefore, you cannot use the __saveds keyword or saveds compiler option if you intend to link your program with the cres.o or catchres.o startup modules. Defining your function with the __saveds keyword is equivalent to calling the function geta4 as the first executable statement of your function. geta4 is provided for compatibility with previous versions of the SAS/C Compiler and with other Amiga compilers. The __saveds keyword is important in function definitions and is tolerated but not required in function prototypes. If you include the __saveds keyword on the prototype for a function, an error message is issued if the keyword is missing from the function definition. This keyword is meaningless on function pointers and other data items. Using __inline If you define a function with the __inline keyword, the global optimizer generates code for the specified function at the point the function is called, instead of generating an actual call to the function. Using the __inline keyword can increase code size, but it can make your code run faster. It also allows the global optimizer to perform more optimizations. If you do not compile with the optimize option, the __inline keyword is ignored, and code is generated to call the function normally. The __inline keyword is required on both function prototypes and function definitions. This keyword is meaningless on function pointers. 160 Chapter 11 Managing Stack Space The stack is a writeable memory area whose size is set by the AmigaDOS stack command or by the external long integer __stack . The default stack size is four kilobytes. This stack is used during function calls for saving registers and passing arguments. Within a function, automatic variables are allocated from the stack. For many C programs, a four- kilobyte stack is adequate. If you compile your program with the stackcheck option (the default) and your program overflows its assigned stack area, the stack overflow routine __CXOVF is called. The __CXOVF routine provided with the SAS/C libraries displays a requester and aborts the program. However, you can replace the version of __CXOVF supplied by the SAS/C libraries with your own version. If you do not want your program to abort because of a lack of stack space, you can allocate additional stack space in one of four ways: [] Increase the value of the external long integer __stack. __stack specifies the minimum stack size needed for your program to run. If the default stack is smaller than __stack, the startup code allocates a new stack of __stack bytes. If you do not compile with stackext, the stack space is allocated once by the startup code, so your program does not take longer to run. Changes made to __stack after your program starts take effect only if new stack extents are allocated because of code compiled with the __stackext keyword or the stackext compiler option. [] Declare functions that require a large amount of stack space with the __stackext keyword. This keyword generates extra code at the start of the function. This extra code compares the amount of stack available with the amount specified in the external long integer __STKNEED. __STKNEED specifies the minimum amount of stack needed by each function in your program. If enough stack is not available, the function allocates a new stack extent whose size is specified in the external long integer __stack. If there is not enough memory to allocate the new stack, the stack overflow routine __CXOVF is called, just as if normal stack-checking code was active instead of the stack extension code. When the function returns, the old stack is restored and the extra stack is freed. Declaring a function with the __stackext keyword is equivalent to compiling the funcvion with the stackext compiler option. [] Compile your program with the stackext option. Compiling with the stackext option is equivalent to defining all functions in your program with the __stackext keyword. If you have specific functions that use a lot of stack space or are recursive, you may want Using Amiga Specific Features of the SAS/C Language 161 to define those functions with the __stackext keyword instead of compiling your entire program with the stackext option. [] Increase the value of the external long integer __STKNEED and compile your program with the stackext option. You should never set __STKNEED to less than 400 bytes (which is the default value). Note: __stack specifies the total number of bytes needed during the entire duration of your program. __STKNEED gives the minimum free stack required by each function. Note: Using the stack extension feature adds overhead to each function entry point and requires the use of an additional address register. Therefore, your program will run slower. The __stackext keyword is important only on function definitions. This keyword is meaningless on function pointers and tolerated on function prototypes, but not required. If you include the __stackext keyword on the prototype for a function, an error message is issued if the keyword is missing from the function definition. Even if you compile your program with stackext, your program may still run out of stack space if it calls a function not compiled with stackext. If you call shared libraries or code compiled with other languages, your program may run out of stack space. Also, the SAS/C library routines are not compiled with stackext, but they use little stack space. The stack extension code allows some extra space for the library routines. In the same application, you can use functions compiled with stackcheck, functions compiled with stackext, functions compiled with neither option, and functions defined with the __stackext keyword. If you compile a function with both stackext and stackcheck, the compiler ignores the stackcheck option. For more information on the __ stack integer, refer to SAS/C Development System Library Reference, Version 6.0. Using #pragma Statements The SAS/C Development System supports five types of #pragma statements: [] flibcall [] libcall [] syscall [] tagcall [] msg. The libcall, syscall, and tagcall #pragma statements allow you to call various library routines directly. These #pragma statements are 162 Chapter 11 described in SAS/C Development System Library Reference. The flibcall #pragma statement also allows you to call various library routines directly. The flibcall statement is similar to libcall, except that each byte instead of each nibble is interpreted as a register. #pragma flibcall allows you to use floating-point registers. However, you can only pass 6 parameters instead of fourteen. Currently, the AmigaDOS system libraries do not accept parameters in floating-point registers. However, if you create your own libraries that accept parameters in floating-point registers, you should use #pragma flibcall. The SAS/C Compiler also supports #pragma msg statements. #pragma msg statements allow you to specify whether a message should be ignored, treated as an error, or treated as a warning message. For example, if you know that your code produces a specified warning on a certain line, you can use a #pragma msg statement to suppress the warning on that line. Note: You cannot turn a message that is by default an error into a warning. How a specific message is treated is referred to as its state. Using #pragma msg statements, you can save the state of a message, change its state, or restore a message's previous state. The msg statement can take one of the following forms: #pragma msg num [error | warn | ignore] [push] #pragma msg num pop where num identifies the number of the message. error indicates that the message should be treated as an error. You can abbreviate this keyword as err. warn indicates that the message should be treated as a warning, if possible. You can abbreviate this keyword as wrn. ignore indicates that the message should be ignored, if possible. You can abbreviate this keyword as ign. push saves the message's state (before changing it). If you specify push, this keyword must appear after the error, warn, or ignore keyword. pop restores the message's previous state. With the push and pop keywords, you can turn a message on or off for a specific line, series of lines, or header file, then restore the message to the value the user specified on the command line. Using Amiga Specific Features of the SAS/C Language 163 For example, the following code produces message number 85 because it returns an int but no return value is specified. However, the code is correct because the exit function never returns. The first #pragma statement tells the compiler not to produce a warning on that line. The second #pragma tells the compiler to generate a message for the remaining functions in the file, if necessary. int func(void) { . . . exit(O); /* Never returns */ #pragma msg 85 ignore /* Turn off warning 85 */ } #pragma msg 85 warning /* Turn on warning 85 */ int func2(void) { . . . } /* A warning here is VALID and is produced due to the */ /* second #pragma statement above. */ Using Unnamed Unions The SAS/C Compiler supports unnamed unions as structure members. For example, you could define the following structure: struct FOO { union { int x; double d; }; long l; } foo; The union in this structure does not have a name. The union members are treated as if they are members of the structure, except that the union 164 Chapter 11 members start at the same offset relative to the base of the structure. In this example, you can refer to member x as foo.x. Using Implicit Structure References If you declare a substructure in your program, and the names of the members in the substructure are unique, you can refer to the members using only the structure name and member name. You do not need to include the substructure name in the reference. For example, you could declare the structure BAR and the substructure FOO as follows: struct FOO { int x; double d; }; struct BAR { struct FOO foo; int l; } bar; You can refer to members x and d in the substructure as follows: bar.x = 10; bar.d = 10.0; Referring to substructure members as shown generates warning message 193. If your program refers to substructure members in this way, suppress warning 193 by compiling your program with the ignore 193 compiler option. If two or more substructures contain a member with the same name and you do not specify the substructure name when you refer to the member, the compiler generates error message 123. The compiler cannot determine which substructure member you are trying to reference. Using Equivalent Structures If you compile your program with the StructureEquivalence option, the compiler does not issue messages if a pointer to one structure type is passed to a function when the function expects a pointer to a different type, if the type passed is equivalent to the type expected. Using Amiga Specific Features of the SAS/C Language 165 A structure is defined to be equivalent if it maps the same base data types in the same order as the desired structure type. If one structure is longer than another, but it is identical through the length of the shorter one, then the longer structure is an acceptable substitute for the shorter, but the shorter structure is not an acceptable substitute for the longer structure. The function receiving the pointer may try to write to one of the fields that does not exist in the shorter structure. Therefore, you can pass an IntuiMessage structure to the exec function PutMsg without getting a warning, but the compiler issues a warning if you assign the result of a call to GetMsg to an IntuiMessage pointer. For example, you could define the following structures: struct FOO { int x; int y; }; struct 8AR { int x, y, z; }; The structure BAR is equivalent to the structure FOO. If you specify structureequivalence, the compiler does not issue a warning for passing a pointer of type BAR to a function whose prototype specifies a structure of type FOO. However, the structure FOO is not equivalent to BAR because FOO is not long enough. If you tried to pass a pointer to a structure of type FOO to a function whose prototype specified a pointer to a structure of type BAR, you would get a compiler warning. BAR is also equivalent to FOO if you define them as follows: struct FOO { int x, y; }; struct BAR { struct FOO foo; int z; }; 166 Chapter 11 Similarly, you can pass a struct IntuiMessage * to a function that requires a struct Message *, since a struct Message is the first element of a struct IntuiMessage. (struct IntuiMessage is defined in the system header file intuition/intuition.h.) This option also allows you to pass a pointer to an IOExtSer structure to a routine that wants a pointer to an IoRequest structure, such as the routine DoIO. IOExtSer is identical to IoRequest for the length of the IoRequest structure. The following example is more complicated, but BAR is still equivalent to FOO: struct FOO { int x, y, z; }; struct BAR { struct { int a; } x; struct { int b, c; } y; int z; }; The structure type FOO defines memory as three consecutive integers. BAR also defines memory as three consecutive integers, although it does so through the use of two different substructures. The substructures are not considered when determining equivalence. Using Zero-Length Arrays You can use zero-length arrays as the last element of a structure. For example, you can declare structure FOO as follows: struct FOO { long maxalloc; long curalloc; Using Amiga Specific Features of the SAS/C Language 167 long mem[0]; }; This structure is 8 bytes in length as reported by sizeof. Using zero- length arrays is most useful when you need to allocate variable-sized data items. For example, if you need 100 elements in the above array at run- time, you can do the following: struct FOO *foo; foo = malloc(sizeof(struct FOO) + lOO*sizeof(long)); foo->mem[50] = 10; foo->mem[56] = ..... Specifying the Size of Enumerated Types By default, enumerated types are integers and integers are 4 bytes long. For example, each of the identifiers of type cats is 4 bytes long. enum cats [bombay, ocicat, somali]; If you compile this line with the shortintegers option, the identifiers are 2 bytes long. The SAS/C Compiler also allows you to control the size of enumerated types by declaring them with the char, short, or long keywords, as in the following examples: char enum flintstones (Fred, Barney, Wilma]; short enum colors (red, green, blue, black, white); long enum seasons (spring, summer, fall, winter); The identifiers of type flintstones are 1 byte long; the colors are 2 bytes long, and the seasons are 4 bytes long. When you declare a variable of a specific enum type, you must include the extra keyword on the variable's declaration: char enum flintstones var1; 168 Chapter 11 Using the sizeof and Comma Operators in Preprocessor Directives The SAS/C Compiler allows you to use the sizeof and comma (,) operators in preprocessor #if directives, as in the following example: #if (sizeof(int) == 2) #error short integers #endif However, the ANSI Standard does not allow these operators in preprocessor directives. Therefore, the compiler produces a warning message if you compile with your program with the ansi or strict option. Using C++ Style and Nested Comments In C++ programs, two consecutive slashes (//) define a comment block that extends to the end of the current line. You can use two slashes to designate comments in your SAS/C programs. However, if you compile with the ansi or strict options, the compiler generates a warning message for these comments. The ANSI Standard states that a C program cannot have nested comments. Therefore, if you enter the comment start sequence (/*) inside of a comment, the sequence is not recognized as the beginning of a second, or nested, comment. The first comment end sequence (*/) terminates comment mode. However, if you specify the commentnest compiler option, as described in Chapter 8, "Compiling and Linking Your Program," the compiler allows nested comments. Using National Characters in Variable Names If you do not compile your program with the ansi option, you can use accented characters in variable names. Using Common Model External Data The ANSI Standard does not define how external data should be handled. Typical UNIX compilers allow you to declare external variables in multiple places, as long as you do not initialize the variable in more Using Amiga Specific Features of the SAS/C Language 169 than one of those declarations. For example, you could define the following variable in a header file: int i; If this header file is included by all files in a project, each file defines a variable i. The linker merges all these independent definitions into one, creating a common model for external data. Most microcomputer compilers use what is called the strict reference- definition model (or strict ref-def) for external data. This model requires that one and only one source file in a project define the external variable. The remaining files in a project can only declare the external variable. To change the definition of variable i to a declaration, use the extern keyword as follows: extern int i; The SAS/C Compiler supports both the common model and the strict reference definition model. The default model is strict reference-definition. If you want to use the common model, compile your program with the common compiler option. 171 170 12 How Does the Compiler Work? 171 Introduction 171 Compiling Your Program 173 Linking Your Program 174 Running Your Program 174 Stack Area 175 Heap Area 175 Changing Hunk Names 176 Addressing Data 177 Understanding Data Types and Sizes 179 Storing Data Introduction Programming with the SAS/C Compiler is not much different than programming in C on other compilers. Most of the books about the C language that are at your local bookstore are applicable to the SAS/C Compiler. If you confine your programming to the features that these books describe, you do not need much specific information about how the SAS/C Compiler works. However, if you want to perform special tasks such as linking with assembly language functions, writing I/O drivers in C, or using overlays, you may need to know how your C program is translated into executable code. This chapter describes how your program is translated into executable code. This chapter assumes a basic knowledge of object file format as described in The AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991). Compiling Your Program The compiler produces an object module (a .o file) for each assembler or C source file. Each object module is organized into hunks. In general, a hunk contains the following information: [] program code or data. The program code is written into the code hunk. The data for your program are written into one of several hunks, depending on how the data are declared. For example, data declared with the __chip keyword are placed in the chip hunk. 172 Chapter 12 [] external symbol information, including subroutine entry points and global data. This information is also referred to as global symbols or XDEFs. [] relocation records. The linker uses these records to produce a load file. A load file is also called an executable module. Your program code and data are organized into the following hunks: Code hunk contains the machine instructions for your program, any string constants (if you compile with stringmerge), and anything else that the compiler decides is definitely read-only. By default, this hunk is named text, but you change this name with the codename option. See the section "Changing Hunk Names," later in this chapter, for more information. Near data hunk contains all initialized near data, including constants and string constants (if you do not compile with the stringmerge option). Near data are data that are declared with the __ near keyword or are defined in modules compiled with the data=near option. data=near is the default setting, so unless you specify otherwise, all of your initialized data are placed in the near data hunk. Near data can be accessed by resident programs and libraries. This hunk is named __MERGED. Near BSS hunk specifies the amount of memory to allocate for all uninitialized near data. The startup code initializes the near BSS hunk to 0. This hunk is also named __MERGED. Chip hunk contains all data that are declared with the __chip keyword or compiled with the datamem=chip option. This hunk is named chip. Far data hunk contains all initialized far data. Far data are data that are declared with the __far keyword or are defined in modules compiled with the data=far or data=faronly options. By default, this hunk is named data, but you can change the name with the dataname option. See the section "Changing Hunk Names," later in this chapter, for more information. Far BSS hunk specifies the amount of memory to allocate for all uninitialized far data. The system loader allocates this memory and sets it to zero. By default, this hunk is named udata, but you can change the name with How Does the Compiler Work? 173 the bssname option. See the section "Changing Hunk Names," later in this chapter, for more information. When you compile your program with the verbose option, the compiler produces a message in the following format: Module size P=00000000 D=00000000 U=00000000 C=00000000 F=00000000 UF=00000000 The letters indicate which hunks were produced for your program: P code hunk (your program) D near data hunk U near BSS (uninitialized data) hunk C chip hunk F far data hunk UF far BSS (uninitialized data) hunk The numbers give the size in bytes, using hexadecimal notation, of each hunk. If the compiler does not create certain hunks, then the compiler either displays zeroes or does not display any numbers for these hunks. If you compile your program using a debug option, the compiler generates debugging information and writes this information into two types of hunks that hold debugging information: H_DEBUG contains line numbers, and information about variables, typedefs, and structures. H_DEBUG hunks are generated by the compiler or the assembler. H_SYMBOL contains absolute addresses of global symbols. H_SYMBOL hunks are generated by the compiler or the linker. Linking Your Program The linker combines the object modules to produce a single executable module or shared library. To produce an executable module, the linker does the following: [] reads each of the object modules. [] reads each of the link libraries, if necessary. [] writes the contents of the object modules to the executable module. In the process, the linker resolves all intra-hunk and near data relocations 174 Chapter 12 and generates relocation records for relocations that span hunks. The linker also combines any hunks in the object module that have the same name. For example, the linker merges all near BSS hunks and appends them to the __MERGED data hunk. [] generates overlay nodes, if required. [] copies segments of the library files that are referenced by the program to the executable module. If those segments reference any symbols, then the library segments that define those symbols are also copied to the executable module. This process is repeated until all symbols are resolved. [] produces data for the overlay supervisor, if required. [] produces a map file and cross-reference tables, if requested. If you are not using overlays, all of the hunks in the executable module are contained in one primary node (also called the root node). If you are using overlays, the executable module also contains a node for each overlay. Running Your Program When you run your program, the AmigaDOS system loader copies the executable module into memory. As it copies the executable module, the loader: [] resolves the remaining relocations. [] allocates and zeroes the memory required for uninitialized far data (the far BSS hunks). There are two other program components, the stack and the heap, that are not part of the executable file but that form an important part of the final executing program. Stack Area The stack is a writeable memory area whose size is set by the AmigaDOS stack command or by the external long integer __stack. The default stack size is four kilobytes. This stack is used during function calls for saving registers and passing arguments. Within a function, automatic variables are allocated from the stack. For many C programs, a four-kilobyte stack is adequate. If your program requires more stack space, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language," for information on allocating additional stack space. How Does the Compiler Work? 175 Heap Area The heap is a writeable memory area whose size is determined by the following: [] the dynamic memory needs of the program [] the amount of memory installed on the system [] the amount of memory that is currently being used. All memory allocation routines such as malloc return memory from the heap. If the heap is not large enough to handle a request, the library function calls on the AmigaDOS system to provide more memory. Changing Hunk Names If you change the names of any of the hunks produced by the compiler, keep in mind the following: [] All hunks with the same name are merged by the linker. [] Hunks with different names are loaded separately by the system loader. [] The system loader may have trouble finding enough contiguous memory to load very large hunks. The following hunk section names are reserved: NTRYHUNK Your load file may contain only one NTRYHUNK hunk. The linker places this hunk first in the executable module. Usually, this name is used only as the name of overlay manager's code hunk. __MERGED This name is used for the near data section. All hunks with this name are merged and moved into the root node. The startup code initializes register A4 to point to this hunk. _NOMERGE Hunks with this name are never merged with other hunks, including other hunks named _ NOMERGE. They occupy a single, separate hunk in the load file. 176 Chapter 12 Addressing Data If you compile with the default options, your program code and data are referenced with one of three different types of addresses: [] 16-bit address relative to the program counter. Items in the code section are referenced with 16-bit PC-relative addresses. The 16-bit offset is a signed value that is added to the current 32-bit address in the program counter. Therefore, if a function is more than 32 kilobytes above or below the point at which it was called, the linker constructs an absolute branch instruction within the 32-kilobyte range and routes the call through that branch. [] 16-bit address relative to register A4. When you link your program, all data in the near data and near BSS hunks are merged into one near data section. When you run your program, the startup module loads the address of the near data section into register A4, and this section is referenced with 16-bit A4-relative addresses. Using 16-bit addresses produces code that is smaller and faster because each load or store instruction requires only four bytes. However, because near data are referenced with 16-bit addresses, you are limited to 64 kilobytes of near data. If you have a very large data structure or array, consider placing it into the far section. [] 32-bit absolute address. Items referenced with 32-bit addresses can be located anywhere in memory. Items in the far data and far BSS sections are referenced with 32-bit absolute addresses. Using 32-bit addresses produces code that requires more space and takes longer to run because each load or store instruction requires six bytes. However, because far data are referenced with 32-bit addresses, there is no limit on the amount of far data that you can declare in your program. chip data are always referenced with a 32-bit pointer and are therefore considered non-reentrant. However, most chip items are picture image structures that are referenced in a read-only mode. If your program uses chip data as read-only, your program is still re-entrant. Chip data can be accessed by the Amiga custom chips such as graphics chips and sound chips. Chip data are loaded into chip memory, which is the lowest 512K to 2M of system memory, depending on the version of the hardware that you are running. You can modify how your program code and data are accessed by: [] declaring individual data items with the appropriate keyword: __chip,__near, or__far How Does the Compiler Work? 177 [] compiling with the stringmerge option [] compiling with the abs funcpointer option [] compiling or linking with the smallcode and/or smalldata options [] compiling with the code and/or data options [] compiling with the datamem, codemem, and/or bssmem options [] linking with the chip or fast option. For more information on the __chip, __near, or __far keywords, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." For more information on the compiler and linker options, see Chapter 8, "Compiling and Linking Your Program." Understanding Data Types and Sizes The following sections describe how various data types are represented on Amiga hardware. By default, all arithmetic objects are signed, and therefore, they can take on values less than zero. However, if you specify the unsignedchar option, the compiler treats all char objects as unsigned. You can specify that an integral object (char, int, short or long) be signed or unsigned by declaring the object with the signed or unsigned keyword, as in the following example: unsigned long x; The following table lists the sizes, minimum values, and maximum values of each of the signed and unsigned data types. Type Bytes Minimum Maximum signed char 1 -128 +127 unsigned char 1 0 255 signed short 2 -32,768 +32,767 unsigned short 2 0 65,535 signed int 4 -2,147,483,648 +2,147,483,647 unsigned int 4 0 4,294,967,295 (continued) 178 Chapter 12 Type Bytes Minimum Maximum signed long 4 -2,147,483,648 +2,147,483,647 unsigned long 4 0 4,294,967,295 float (IEEE) 4 3.402E-37 3.402E+38 double (IEEE) 8 2.222E-308 1.797E+308 float (FFP) 4 5.421E-20 9.223E+18 double (FFP) 4 5.421E-20 9.223E+18 Note: In the AmigaDOS environment, pointers are always 4 bytes in length. Also, the values for signed int and unsigned int in this table are the values if you do not specify the shortint option. The default size of an int on Amiga hardware is four bytes. However, you can set the size of an int to two bytes by compiling your program with the shortint option. When the compiler is calculating the value of an expression using variables of different data types, the compiler performs some automatic type promotions and then does the calculation using the data type of the widest operand. The widest operand is the operand that can contain the largest positive number. For example, suppose you may have a calculation involving a variable of type char and a variable of type unsigned long. The char is automatically promoted to int, so the calculation now involves an int and an unsigned long. The int is then promoted to unsigned long under the wider type rule. These rules can dramatically affect your code. In the example calculation, the char is signed. If it holds a -1, for example, the -1 is promoted to int, yielding -1. The int is then promoted to unsigned long, yielding a very large positive number. These implicit conversions follow the conversions described in the ANSI Standard in Section 3.2.1.5, "Usual Arithmetic Conversions." The following table lists the type to which the various data types are converted. How Does the Compiler Work? 179 Operand Type Conversion Type char int unsigned char int short int unsigned short int int int unsigned int unsigned int long long unsigned long unsigned long float float double double Note: As previously stated, if you compile your program with the shortint option, integers are two bytes long. Then, if you cast the result of an expression involving two integers to another type, you do not get the results you might expect. For example, you could have the following code in your program: long l; int i=32000; int j=32000; l = (long)(i * j); If you compile this code with shortint, i and j are not promoted to long before the expression is evaluated. The result of the expression is too long to fit into a short integer. The overflow is cast to a long, which gives the wrong result. To correct the problem, explicitly cast i or j to a long, as in the following example: l = (long)i * j; Storing Data In the C Language, each data object is associated with a storage class that is either declared with a keyword (auto, extern, static, or 180 Chapter 12 register) or determined by the context in which the declaration occurs. An object's storage class determines the location where the object is stored and the scope of the object. Therefore, the storage class of the objects in your program can affect your program's size and performance. The following list describes where objects are stored, based on their storage class: External External objects are stored in a global data area (one of the near, near BSS, far, far BSS, or chip sections). Static Static objects are stored in a global data area (one of the near, near BSS, far, far BSS, or chip sections) unless you specify the stringmerge option. If you specify stringmerge, data declared static const are placed in the code section. Automatic Storage for automatic objects is allocated on the stack during the execution of the function in which the object is defined. Formal An object has the storage class formal if it is a parameter (or argument) to a function. Storage for formal objects is allocated on the stack during the execution of the function in which the object is defined. Register Register variables may be stored in registers, or they may be stored on the stack. If you run the global optimizer, the optimizer allocates all register variables and ignores the register keyword. If you do not run the optimizer and you specify the noautoreg option, only those variables you declare with the register keyword are stored in registers. If you compile with autoreg, the code generator decides which additional variables are stored in registers. 181 13 Writing Portable Code 181 Introduction 181 Compiling Your Program 182 Writing Your Program 183 Dealing with Data Type Sizes 183 Determining Structure Size and Padding 184 Writing Structures to a Disk File 187 Using Narrow Types in Pre-ANSI Function Declarations 188 Using Incomplete Structure Tags Introduction The C language has many characteristics of a portable language, but some features of the C language are dependent on the type of machine on which the program is running. However, you can write programs that run on many different machines if you follow some guidelines when compiling and writing your program. The following sections describe actions you can take to improve the portability of your programs. Compiling Your Program You can compile your program with the strict and/or ansi options. These options enable many warnings that identify possible problems in your code that may cause errors if you port your code to systems other than the Amiga system. For example, the following code generates message number 120: void func1(long); void func2(void) { short s=0; func1(s); } 182 Chapter 13 If you compile this code with the strict option, the compiler displays the following message: Warning 120: Integral type mismatch: possible portability problem Expecting "long", found "short" Writing Your Program If you use only library functions and language features that are defined in the ANSI Standard (American National Standard for Information Systems--Programming Language C), your program should compile without modification on any system that has an ANSI-compliant C compiler. However, there are many features of the C language that are implementation-defined. Even if your program compiles without generating errors, it may not run as you expect. See Appendix 3, "Implementation-Defined Behavior," for more information. To help you identify non-portable functions and macros in your program, you can define the _STRICT_ANSI preprocessor symbol. You can define this symbol by entering define _STRICT_ANSI= 1 in the sc command or by entering the following statement in your C source file before any header files are included: #define _STRICT_ANSI 1 If you define _STRICT_ANSI, the header files that are defined by the ANSI Standard (such as errno.h and stdio.h) do not define any prototypes or macros for functions not permitted by the ANSI Standard. If your program calls a non-ANSI function, the compiler issues a warning message because the function has no prototype. For more information on the _STRICT_ANSI symbol, refer to SAS/C Development System Library Reference, Version 6.0. In addition, if you follow a few additional guidelines, you can avoid most portability problems. The following list contains some guidelines that can help improve the portability of your program. [] Do not assume data type sizes are standard. [] Do not assume structure padding or size is standard. [] Be careful when writing structures to disk. [] Do not use narrow types in old-style definitions. [] Be careful about using incomplete structure tags. [] Do not write pointers to files. Pointers are useless outside of the invocation of the program that generates them. Writing Portable Code 183 [] Do not assume that you know whether char variables are signed. [] Do not assume that you know the placement of bitfields within structures. The following sections discuss these guidelines in more detail. Dealing with Do not assume that the int data type is always a particular length. The Data Type Sizes ANSI Standard specifies that the int type must be at least as long as the short type and that the short data type must be able to hold numbers in the range 32767 to -32768. Therefore, portable code should never store numbers larger than 32767 or smaller than -32768 in an int. Use long for larger numbers. The default size of an int on the Amiga system is four bytes. On other systems (such as the IBM PC), the size of an int is two bytes. The SAS/C Compiler treats the data types int and long as the same data type. However, you can set the size of an int to two bytes by compiling your program with the shortint option. If you compile with shortint, the compiler treats the data types int and short as the same data type. If you port your program to a system that uses two-byte integers and you do not compile with the shortint option, you may receive unexpected results. For example, when passing parameters on the Amiga system, short and char variables are silently promoted to ints. Therefore, any function declared as receiving a long does not produce a warning if you pass a short or char to the function. To receive an appropriate warning message, you can enable warning 120 by compiling with the warn= 120 or strict compiler options. Declaring an object as signed is usually redundant, because integral objects are signed by default. However, judicious use of the signed keyword can enhance your program's portability, because some compilers may make char declarations and bitfields unsigned by default. Determining Even though the Motorola 68000 processor uses byte addresses, it Structure Size requires that 16-bit and 32-bit data items be aligned on even addresses. and Padding That is, the lowest bit of the address must be zero. Because of this requirement, the SAS/C Compiler inserts dummy bytes (called padding) as necessary to align integers, floats, doubles, and pointers. For example, in the following structure, the SAS/C Compiler adds one byte between the structure members a and 1. struct misc { char a[3]; 184 Chapter 13 long l; }; If the dummy byte was not added, the long structure member would end up on an odd boundary and an addressing exception would result. On other systems, an ANSI compliant C compiler may add more or less padding as required. Many computers require that long integers fall on four-byte boundaries, so the compiler would add three bytes of padding instead of one. Because of these alignment requirements, data structures may be different sizes on different machines. Do not assume that you know the size of a structure based on the fields declared in it. Use the s i z eo f operator to determine the size, and do not depend on sizeof to return the same result on different machines. Using the previous example, the expression sizeof ( struct misc ) has a value of 8, and the following expression has a value of 7: sizeof(misc.a) + sizeof(misc.l) Writing If you try to write structures to a disk file on one system and read the file Structures to a on another system, you may get different values. This problem may be Disk File caused by differences in structure padding (as described under "Determining Structure Size and Padding") or by differences in the representations for characters, floating-point numbers, or integers. For example, the following program writes a structure to a file: linclude main() { FILE *fp; struct { char x; short y; } record; fp = fopen("testfile","wb"); record.x = 3; record.y = 4; fwrite(&record,sizeof(record),1,fp); fclose(fp); } Writing Portable Code 185 If you compile and run this program using the default compiler options, the file testfile contains four bytes in the following order: 03 00 00 04. However, if you compile and run this program under MS-DOS, which uses the Intel 8086 processor, the file contains 03 04 00. The reasons for the different values are as follows: [] The SAS/C Compiler inserts a padding byte so that integer y is correctly aligned. The Intel processor does not require this padding. [] The Motorola processor writes integers from the high byte to the low byte, and the Intel processor writes integers from the low byte to the high byte. The following paragraphs describe some simple rules that you can use to make your structures more portable between the Amiga computer and most other computers. These guidelines help you produce a structure that your program can write to disk and then read in a single operation. These guidelines are not guaranteed to work in all cases, but they do gain you limited ability to interchange files between various computers. The computer to which you are porting your program must do the following: [] Use the same floating-point format for doubles that you are using on the Amiga system (FFP if the math= ffp option is specified, IEEE for all other formats). [] Use the ASCII character set. [] Use the same sizes for data types: char 1 short 2 long 4 [] Store integers using the same bit pattern that the Amiga system does. The structure to be written must follow these rules: [] The structure can contain only the following data types: Type Length char 1 short 2 float 4 long 4 double 8 (or 4 if you compile with math=ffp) Do not use ints or any pointer types in the structure. [] Structures or unions may contain other structures or unions that follow these rules. [] Each field must be placed at an offset relative to the start of the structure that is an exact multiple of the field's size. 186 Chapter 13 [] A nested structure or union must be placed at an offset that is an exact multiple of the largest simple arithmetic type occurring in any of its fields, including the fields of any substructures or subunions. [] If the structure or any of its substructures contains a double, the structure must contain extra fields as needed to ensure that its total size is an exact multiple of the size of a double. If it does not contain a double, it must contain extra fields to ensure that its total size is an exact multiple of four. For example, you cannot port the following structure between systems: struct NOTDISKABLE /* Non-diskable structure */ { char a; double d; short s; long l; char name[27]; struct XXX { char a, b; } foo[11]; }; To make the previous structure portable between systems, you must declare the structure as follows: struct DISKABLE /* Diskable version of same structure */ { char a; char dummyl[7]; /* following double needs 8-byte offset */ double d; short s; short dummy2; /* following long needs 4-byte offset */ long l; char name[27]; char dummy2[5]; /* following structure needs 4-byte offset */ struct XXX { char a, b; char dummy3[2]; /* Pad to multiple of 4 bytes */ } foo[11]; char dummy4[4]; /* Pad to multiple of 8 bytes */ }; Writing Portable Code 187 Using Narrow The ANSI Standard states that function definitions should specify the data Types in type of each parameter, as in the following example: Pre-ANSI Function /* ANSI Standard prototype-style definition */ Declarations void newfunc(short s, float f) { . . . } Pre-ANSI C accepted function definitions in the following form: /* Pre-ANSI old-style definition */ void oldfunc(s, f) short s; float f; { . . . } The ANSI Standard default argument promotion rules (described in Section 3.3.2.2 of the ANSI Standard) differ for functions defined with prototype style definitions and functions defined with old-style definitions. You may get incorrect results on ANSI conforming compilers if you use ANSI standard prototypes and old-style function definitions for the same function. You can avoid this problem by not using narrow data types (char, short, and f loat) in function prototypes and definitions. The ANSI Standard says that functions defined with old-style definitions and no prototypes must receive all char and short parameters as if they were type int and receive all float parameters as type double. The incoming parameters are then converted to the appropriate shorter type. Functions defined with new-style definitions are free to receive narrow types as declared. Unfortunately, the caller of the function does not know whether the function is defined with a prototype-style definition or with an old-style definition. The ANSI Standard does not define what happens if you declare a function using an old-style definition but also include an ANSI standard prototype for the function. To make more programs work as expected, the SAS/C Compiler treats such definitions as if they were new-style definitions. 188 Chapter 13 If you do not port your program to a system other than the Amiga system, you should not encounter any problems with narrow types unless the following situation occurs: The caller has a prototype for a function that says float. The called function does not include the prototype and has an old- style definition that says f loat. The data types char and short do not cause problems on the Amiga system because they are passed as if they were type int for both old- style and prototype-style function definitions. To help identify problem situations, you can enable the following warnings: Warning Description 165 This message identifies narrow types that have been used in function prototypes. You can enable this warning with the warn=165 option. 176 This message identifies arguments that have been promoted using the default argument promotion rules and, as a result, conflict with the prototype given for the function. You can enable this warning with the strict, ansi, or warn=176 option. 179 This message identifies narrow types that have been used in an old-style function definition. You can enable this warning with the strict or warn=179 option. Using Incomplete An incomplete structure tag is a structure tag (or name) that has not yet Structure Tags been defined. The ANSI Standard allows you to refer to structures by name before they have been defined, as long as you only declare pointers to the structure and do not attempt to dereference these pointers. Incomplete structure tags can cause problems if they occur in a function prototype. The ANSI Standard allows incomplete structure tags in function prototypes but states that the incomplete tag goes out of scope at the closing parenthesis of the prototype. Any declaration of the structure later in the program is not associated with the incomplete tag used in the prototype and is considered to be a completely different structure. If you define the function later in the program, an ANSI-conforming compiler may issue an error message, and your program may not compile. Writing Portable Code 189 For example, many ANSI-compliant compilers generate an error message for the following code, claiming that the type of the parameter does not match the type declared in the prototype. void func(struct FOO *); /* Incomplete tag FOO */ struct FOO { int x, y, z; }; void func(struct FOO *parm) /* Error here! */ { } If you move the definition of struct FOO before the prototype, this code compiles without problems. To help you identify incomplete tags, you can enable the following warnings: Warning Options 148 This warning identifies any use of incomplete tags. You can enable this warning with the warn= 148 option. 149 This warning identifies incomplete tags that are used in function prototypes. You can enable this warning with the strict or warn=149 option. 191 190 Chapter 13 [] Part 4 Appendices Appendices 1 Solving Common Problems 2 Error and Warning Messages 3 Implementation-Defined Behavior 4 Converting From Aztec C Options to SAS/C Options 5 Converting from Version 5 to Version 6 192 193 Appendix 1 Solving Common Problems 193 Introduction 193 Resolving Undefined Symbols 195 Fixing Compilation Errors 197 Using CodeProbe 197 Using Formatted Print Functions 198 Using getchar 199 Getting Incorrect Results from Function Calls 200 Crashing the Machine 200 Using The asctime Function 201 Managing the Standard I/O Window 201 Linking Resident Programs or Creating Resident Libraries 202 Writing Replacement Functions for SAS/C Library Functions 202 Eliminating Informational Messages Introduction This appendix describes the solutions to some of the most common problems for which users call the Technical Support Division. This appendix also includes questions that the Technical Support Division anticipates will be generated by the conversion to Version 6. Before calling the Technical Support Division, read the read.me file on disk 1 carefully. (The read.me file is also copied to the directory into which you install the product if you installed the SAS/C Development System on a hard drive.) This file contains errata for the documentation and information about any feature that may have been added after the documentation went to press. Resolving Undefined Symbols When I compile and link, I get messages reporting Undef ined Symbol: _CXnnn and saying that the proper math library has not been included. In your program, you have accessed floating-point math routines, but you have not linked with the appropriate math library. Specify the appropriate math option for the library with which you want to link, such as math=standard. If you are using the link option to link your program, the compiler links with the correct math library. If you 194 Appendix 1 call the linker separately from the compiler, you must specify the correct math library in the slink command after the libs keyword. Refer to SAS/C Development System Library Reference, Version 6.0 for more information about math libraries. I am getting BLTN and/or CXERR errors, and I am using math libraries and header files. You may be including the math header files for one type of floating- point format and linking with libraries for another type of floating- point format. For example, you may be including m68881.h and linking with scmffp.lib. Different floating-point formats are incompatible and should not be mixed. Make sure that your included header files match the math library with which you are linking. If you find no problem with the compatibility between your header files and your math library, contact the Technical Support Division. When I link my project, I get undefined symbols. This code worked in Release 5.10. Some of the library symbol names have been changed to comply with the ANSI Standard for symbol names. The ANSI Standard states that any symbols that are not mandated by the Standard must begin with an underscore and a capital letter or two underscores. When you compile your program, the compiler adds an additional underscore to the beginning of any symbols defined in C code. Therefore, a C symbol with two underscores has three underscores when the linker finally sees the symbol. If your code refers to a symbol that has changed names from Version 5 to Version 6, the linker may produce an undef ined symbol message when you link your program. If you receive this message, first check the SAS/C Development System Library Reference for different versions of the symbols with different numbers of underscores. Remember, the linker reports one more underscore on the symbol than the SAS/C Development System Library Reference shows. Change your C code to refer to the new name for the symbol as described in the SAS/C Development System Library Reference. If this solution is not practical because of the number of references to the symbol, you can solve this problem in one of two other ways: [] Use the define option on the sc command or a #define statement in a header file to define the old name to the new name. [] Use the define option on the slink command to force all references to one of the names to refer to the other. If you define the item in your code (in other words, you declare it without the extern keyword), you should use the def ine option to defife the Solving Common Problems 195 new name (used by the library) to the old name (used by your code). If you declare the item with the extern keyword and, therefore, use the library definition for the item, use the define option to define the old name (used by your code) to the new name (used by the library). One very common technique used in Version 5 was to declare the main routine of your program as _main instead of main to bypass the overhead required to set up stdio and argument parsing. You should change this name to __main and add the keyword __stdargs to be compatible with Version 6. If you do not change this name, the linker issues a message saying that the symbol _ main is undefined. (Remember, the linker puts in an extra underscore, so the symbol it is really looking for is main). Fixing Compilation Errors I have installed my compiler correctly, but I keep getting the message se not found or sc not found whenever I try to do anything. Your s:user-startup may not be set up correctly. The installation program places three assign statements and the path statement at the end of your s:user-startup file. If you are invoking any programs that create a new Shell (such as PopCLI) in your s: user-startup file before the path sc: c add statement, sc: c may not be in new shells created by the program. To correct the problem, move the three assign statements and the path statement above any calls to programs that create a new Shell. If you are running under AmigaDOS Version 1.3, you may have a different problem. The installation program places the necessary assigns in a file named s :user-startup, which is called from s: startup-sequence. You may have to edit s: startup-sequence and make some changes. See Chapter 1, "Installing Your SAS/C Development System," for information on modifying your startup file. After switching to Version 6, my old programs will not compile, or they compile with a lot of warning messages. Why is this happening and how can I fix it? There are two solutions: [] In Version 6, the compiler assumes that your code will provide prototypes for all functions. (In Version 5, you had to specify the -cf option for the compiler to identify missing prototypes.) If your code does not define prototypes for all functions, the compiler may produce several warning 100, 154, and 161 messages. Specify 196 Appendix 1 ignore= 100+154+161 to suppress these warnings, or use the genprotos option to generate prototypes for your functions and #include the resulting header file. [] Unlike previous versions, the header files and libraries for Version 6 of the SAS/C Compiler are ANSI-compliant. The ANSI specifications affect both ANSI and non-ANSI functions and data names, so some non-ANSI functions and data names have also changed. Convert your program to use the new ANSI-compliant libraries and headers. For any functions mentioned in error messages, read the description of the function in the SAS/C Development System Library Reference. This reference manual describes the parameter list, return value, and necessary header files required by each function. Make sure that you are including the correct header for each of the SAS/C or AmigaDOS functions that you are calling. When I compile, the options I requested do not act as expected. When you compile your program, whether you compile from the Shell or the Workbench screen, the compiler looks for an scoptions file in your current directory. If it does not find one, it looks for the file ENV: sc/scoptions. If it finds either of these files, it uses any additional options specified in the file. You can run the scopts utility or edit the scoptions file to review the options specified in these files. If you want to prevent the compiler from reading the options specified in any scoptions file, specify the resetoptions option as the first option in the sc command. If your program then runs as expected, you have a problem with the options that you have specified. If you specify the verbose option, the compiler tells you the location of the scoptions file used. During compilation, I get the message semi-colon expected in a header file. Check for extra characters at the beginning of your file in front of your #include statements or in one of your header files. You may have accidentally pressed a key while starting the editor. I keep getting the message Error 25: Modifiable lvalue required, but I am declaring all my variables for a function just like it says in the library reference manual. Do not include the const keyword in your declarations. The SAS/C Development System Library Reference contains many variables defined with the const keyword, especially pointers to strings. This keyword is required by the ANSI Standard and indicates that these variables will not be modified in the library function to which they are passed. The const keyword is present in the parameter list of the prototype Solving Common Problems 197 that is found in the associated header file. This prototype, not the declaration you should include in your program, is what is described in the synopsis for each function in the SAS/C Development System Library Reference. Use the synopsis as a guideline for your declarations, but do not include the const keyword. Using CodeProbe I do not get all of the information I expect out of CodeProbe, or CodeProbe does not know about variables and functions it should know about. You may not be compiling with the correct debug option. If you are compiling with nodebug or debug=line, try compiling with debug=sf. For a complete description of each debug option, see Chapter 8, "Compiling and Linking Your Program." CodeProbe does not work if I double-click on the Debug icon from the WorkBench screen. To invoke CodeProbe from the WorkBench screen, click on the Debug icon. Then, hold down the Shift key and double-click on the icon for your program's executable module. Using Formatted Print Functions printf (or sprintf, fprintf, and so on) does not print the correct values. This problem can happen for the following reasons: [] You are asking printf to print a variable, but the variable conversion characters are incorrect. For example, you are trying to print a long integer using %d as the conversion character. A long variable requires a %ld if the shortint compiler option is active. Often, if you have one conversion character wrong, the rest of the line you are printing is also incorrect. Check your entire printf (or fprintf, etc.) format string carefully. [] You are trying to print a float or a double, but you have not linked with the proper math library. You must link with a floating point math library to perform any floating point operations. If you are linking with a floating point library, make sure that it is positioned in your slink command line before sc . lib so that the linker can find the correct version of printf. If you specify the link option in the sc command, the compiler links the libraries in the correct order. 198 Appendix 1 [] You are linking with amiga.lib before the math library and sc.lib. You should specify amiga.lib as the last library in the slink command. Using getchar getchar does not work as expected. Input and output on the Amiga system are buffered. On most other systems, getchar immediately gets a character from stdin (usually the keyboard). However, the CON: device on the Amiga system buffers its input, so your program does not actually read any characters until you do one of the following: [] fill up the console input buffer [] press Return [] enter the Amiga End-of-File character, Ctrl-\. The SAS/C Development System libraries include two functions that you can use to deal with this problem: getch gets a character from the console in RAW mode. The character is returned as soon as the user types it. rawcon turns RAW mode on and off. rawcon(1) sets the console into RAW mode. rawcon (0) restores the console to non- RAW mode. When the console is in RAW mode, any characters typed by the user are passed immediately to the application. getch returns a single character from stdin just like getchar, but getch gets the character in RAW mode. If your console is not in RAW mode, using getch is equivalent to the following sequence: rawcon(1); c = getchar(); rawcon(0); If your console is in RAW mode, getch is equivalent to getchar. For more information about getchar, refer to SAS/C Development System Library Reference. Solving Common Problems 199 Getting Incorrect Results from Function Calls My program compiles and links without errors, but I am getting the wrong results from some of my SAS/C function calls. You can get incorrect results from a function if you do not include the correct header files for the function you are calling. The header files contain prototypes for each of the SAS/C functions, as well as definitions for many common data structures required by these functions. By including the correct header file, you are providing the compiler with a prototype for the SAS/C functions you call. The ANSI Standard requires that the compiler assume that functions that are called without the previous inclusion of a prototype return an int. For example, this means that if you call atof, which returns a double, without including math . h, the compiler assumes that atof returns an int and allocates only 4 bytes for the return value. When atof is called and the correct 8-byte double value is returned in the 4-byte space allocated for it, the value appears to be incorrect. You may be including the incorrect header file for one of these reasons: [] In Version 6, the prototype is contained in a different header file than in Version 5. For example, in Release 5.10, the function atof was included in math.h. In Version 6, the atof prototype was moved to stdlib.h as required by the ANSI Standard. Check the SAS/C Development System Library Reference for the correct header file for the functions that you are using. [] You may be including the right header file from the wrong directory. For example, the include:dos directory contains many header files with the same names as those in the root level include: directory. However, these header files are AmigaDOS header files and not ANSI header files. The AmigaDOS header files do not contain the necessary prototypes and data declarations. For example, you may be including dos /stdio.h instead of stdio.h. Do not substitute header files from the include:dos directory for standard headers. [] You may be including header files from the proto directory instead of those in the root level include: directory. Although the files in the proto directory do contain prototypes for many of the SAS/C functions, these files are intended to be included in addition to the standard header files, not in place of them. Do not use header files in include: subdirectories as substitutes for the root level header files. 200 Appendix 1 Crashing the Machine My program compiled and linked without any errors, but when I run it, my machine crashes. What am I doing wrong? The following list contains some of the more common errors that crash programs. Most of these errors are caused when your program accesses memory that it is not supposed to access. [] You have declared a pointer to an array or structure for which you have not allocated memory. This mistake is especially easy to make when calling functions that fill the array or structure with information, such as the fstat, lstat, and stat functions. To correct this problem, call malloc or calloc to allocate the appropriate amount of memory for the array or structure. [] You have assigned an inappropriate value to a pointer, so the pointer no longer points to a valid memory space. This type of error can be quite difficult to track down. You may want to run the CodeProbe, the Enforcer, or the Mungwall program if you think these types of errors may occur. Enforcer and Mungwall are programs that detect memory errors. They are available from Commodore Applications and Technical Support (CATS) and are shipped with Version 6. [] You have specified the nostackcheck option and are overwriting your stack. Do not specify nostackcheck until your program is completely debugged. The stackcheck option is the default unless you are creating a shared library using the libcode option. Using The asctime Function I am using the asctime function to convert the time to Greenwich Mean Time (GMT) correctly, but the result is exactly an hour (or two or three...) off. Your machine is probably in the default time zone, Central Standard Time (CST), and has not been reset to your actual time zone. To correct the problem, reset your machine's time zone environment variable to your actual time zone with the following AmigaDOS command: setenv TZ=your-time-zone Solving Common Problems 201 For your-time-zone, enter your zone's standard three letter abbreviation followed by the number of hours difference between your time zone and Greenwich Mean Time. For example, for Eastern Standard Time, the command would be as follows: setenv TZ=EST5 You can also initialize the _ TZ variable as described in the SAS/C Development System Libra~y Reference. Initialize the _ TZ variable with the same time zone data as you would enter with the AmigaDOS command described above (for example, EST5). Note: The AmigaDOS environment variable does not have a leading underscore that the SAS/C data name has. Managing the Standard 1/0 Window An annoying window opens when I run my program from the Workbench screen. How do I get rid of this window? The SAS/C startup code opens the window to allow programs that are run from the Workbench screen to access stdin, stdout, and stderr. You can eliminate this window or change its attributes. For information on managing this window, see Chapter 9, "Running Your Program from the Workbench Screen." Linking Resident Programs or Creating Resident Libraries I get the message absolute reference to name from the linker. You are linking a resident program with the cres . o startup module, or you are creating a resident library, but the linker detected a reference to an absolute symbol. Make sure that the symbol being referenced is not being modified. If the item is not being modified, then you can ignore the warning message. 202 Appendix 1 Writing Replacement Functions for SAS/C Library Functions I wrote a replacement function for one of the SAS/C library routines, but the library routines don't seem to be using my replacement function. If you write a function that has the same name as a library function, you need to add the __regargs keyword to your function or compile with the parms=both or parms=register option. For example, you may want to replace the SAS/C library function malloc with your own version of malloc. If you compile with the parms=stack option or define your version of malloc with the __stdargs keyword, then two versions of malloc are linked into your executable. If you use other SAS/C library functions that call malloc, these functions use the version of malloc in the SAS/C libraries. However, your functions that call malloc use your version of malloc. To make sure that all calls to malloc are using your version of malloc, define your version with __regargs or compile with the parms=both or parms=register option. Eliminating Informational Messages How can I turn off all of the informational messages the compiler and linker produce every time I compile and link? You can specify the following options on the sc command line: sc nover link filename.c 203 Appendix 2 Error and Warning Messages 203 Introduction 203 Using Error and Warning Messages 204 Explanations of Unnumbered Compiler Messages 206 Explanations of Numbered Compiler Messages 258 Explanations of Linker Messages 265 Enabling Suppressed Messages Introduction This appendix explains each of the error and warning messages that may be produced by the compiler and linker. Using Error and Warning Messages You should treat warnings as seriously as errors. If you do not know why a given warning is being produced, find out why. If you can safely ignore the warning in the future, use the ignore option on the compiler or the #pragma msg statement to suppress the warning. In general, the compiler attempts to prevent long cascades of error and warning messages that result from a single mistake, but this action is not always possible. As a result, you may see several messages generated by the same error, especially if the error is in a control statement such as an if, for, do, or switch statement. If you receive some messages that seem to be incorrect or confusing, fix as many errors or warnings as possible, and then recompile your program. The confusing messages may disappear. Sometimes the compiler may generate an error message for code that you believe is correct. In many cases, such errors are the result of incorrectly using the preprocessor. A typographical error in a preprocessor macro or accidental collision of a #def ined macro name with another name in your program can cause very confusing problems. If you think you are having problems with preprocessor macros, compile your program with the pponly option to generate preprocessed output, and check that to see exactly what the compiler is receiving. Alternatively, compile with the list option to generate a listing file. The 204 Appendix 2 listing file allows you to see exactly what symbols are being defined by the header files included by your program. Some error or warning messages are produced at the first non- preprocessor statement after the actual condition that caused the error or warning. For example, if your program is missing a semicolon, you do not get a message at the end of the line that is missing the semicolon; you get a message at the beginning of the next line of code. If you cannot find an error exactly where the message occurred, look at several previous lines in your source code . Remember, the compiler treats #include files as if they are part of your source file. For example, a missing close curly brace at the end of your last #include file may result in an error message at the first line of your C source file. You can compile with the pponly option to help diagnose this type of error. By default, many warning messages are suppressed but can be enabled with the strict, ansi, or warn options. The descriptions of each message indicate whether the message is suppressed and, if so, which options enable the message. You can enable any suppressed warning with the warn or error options. You can disable any warning with the ignore option. You cannot use the ignore option to disable error messages. See Chapter 8, "Compiling and Linking Your Program," for more information about the strict, ansi, error, warn, and ignore options. See also "Enabling Suppressed Messages" later in this appendix for a complete list of the suppressed messages and the options you can use to enable them. Some messages listed as warnings can also be produced as errors in some cases. If a message is produced as an error instead of a warning, it cannot be ignored (just as errors cannot be ignored). You can display help information on a specific message from the message browser utility (scmsg) by clicking on the message and pressing the Help key or by invoking the AmigaGuide utility on the file sc:help/scmsg.guide. Explanations of Unnumbered Compiler Messages Freeing Resources If you compile your program and your machine runs low on memory, the compiler displays this message and frees memory to enable it to continue the compilation. You can force the compiler to free memory at any time by pressing Control-F in the window to which the compiler is sending output. Error and Warning Messages 205 Floating point overflow optimizing constants The global optimizer was attempting to perform compile-time constant calculations, but the calculations caused a floating-point error. Your code is causing floating-point numbers to overflow. Can't open type file "name" for mode The compiler could not open the specified file. The mode is either read or write. Combined output filename too long The filename produced by the compiler, with the path, overflowed the compiler's internal buffer (255 bytes). Can't open sc:libs/lib-name.library The specified shared library could not be found. Make sure the library is available in sc:libs. CXWRN: text An internal error occurred. With CXWRN errors, the compiler attempts to continue the compilation, but may not be able to do so. Please contact the Technical Support Division. CXERR: num An internal error prevented the compiler from continuing. Please contact the Technical Support Division. Can't delete old GST: object is in use Continuing with no GST file You specified the makegst option, but an existing copy of the same GST was in use by another program. Check for other compilations that are using the GST. You may also be browsing the GST with the hypergst utility. Can't open GST file: gst-filename The specified GST file could not be loaded. Either the file is an invalid GST file, or the file does not exist. Invalid symbol definition: symbol-name You attempted to define the specified symbol on the command line with the define compiler option, but the symbol did not adhere to the normal rules for C preprocessor symbol syntax. Seek error on object file The compiler attempted to perform a seek operation on the output object file but encountered an I/O error. I/O error code on file "name" The compiler received the specified I/O error code from the operating system while attempting to read the named file. Refer to The AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991) or see the header file dos/dos.h for details on the numeric error codes. 206 Appendix 2 Explanations of Numbered Compiler Messages Warning 1: invalid preprocessor command This warning is generated by invalid use of preprocessor commands. For example, you could specify an unrecognized command, fail to include a space between command elements, or use an illegal preprocessor symbol. The command is ignored and compilation continues. Error 2: unexpected end of file This error is generated when the compiler expects more data, but it encounters the end of an input file. This error may occur in a #include file or in the original source file. A missing #endif or unbalanced curly brace or parentheses in the source file or in one of the previously included files may produce this message. In many cases, correcting a previous error eliminates this error. Error 3: file not found "filename" The filename specified in a #include command was not found or could not be opened. Error 4: invalid lexical token A character was found in the file that is not a standard character in the C character set or is in an inappropriate place. For example, entering a pound sign (#) in the middle of non-preprocessor C code or entering nonprintable control characters anywhere except in a comment produces this error. Error 5: invalid macro usage Your code invoked a macro incorrectly. Check for unbalanced parentheses and other syntax errors. The problem may be in a macro used by the macro that you invoked in your program. Error 6: line buffer overflow A line of preprocessed input was longer than the line buffer size. The size of the line buffer is controlled by the ppbuf and memsize options. If you do not specify ppbuf or memsize, the size of the line buffer is 8192 bytes. Error and Warning Messages 207 Error 8: invalid conversion You attempted to cast a type to an incompatible type. This error usually occurs when you attempt to convert something into an array, a structure, or a function. Check for missing indirection (*) and/or address (&) operators. For example, the following program tries to assign a whole structure to a pointer. void main ( void ) { struct FOO { int a, b; } f; struct FOO *p; p = f; /* Error 8 */ p = &f; /* Correct */ } Error 9: undefined identifier "name" The specified identifier has not been declared. You may not have included the proper header files to declare an extern, or you may have misspelled the name of a variable. This message is produced only once for each undeclared identifier. Subsequent uses of the identifier do not produce a message. Subsequent declarations of the identifier may produce messages about redeclaring the variable. Fix the error that is causing the first error 9 message and recompile your program before trying to fix additional messages involving the same variable. Error 10: invalid subscript expression An error was detected in an expression used inside square brackets ([]). This error may occur if: [] the expression is missing [] the expression is a preprocessor macro that evaluates to nothing [] the result of the expression is void [] the result of the expression is a pointer, a structure, or a union. Error 11: string not terminated The closing double quote (") was not provided when defining a string. 208 Appendix 2 Error 12: invalid structure reference The operand preceding the structure member ( . ) or structure pointer (->) operator is not a structure or a pointer to a structure, respectively. Make sure you are not trying to reference a structure member with the structure pointer operator or a structure pointer with the structure member operator. In many cases, correcting a previous error eliminates this message. Error 13: member name missing The name of the desired structure or union member did not follow the structure member operator ( . ) or the structure pointer operator (->). Check for preprocessor macros that may be defined to the same name as the member. Error 14: undefined member "name" The indicated identifier is not a member of the structure or union to which the structure member operator ( . ) or the structure pointer operator (->) referred. Error 15: invalid function call An identifier or constant is used where a function or function pointer identifier is required. This message can occur if you attempt to use a variable not declared as a function or function pointer but give the variable a parameter list. The compiler sees the parenthesized expression and thinks you are calling a function. Check for typographical errors such as leaving out an operator in an expression, which produces a variable and a parenthesized expression. Such typographical errors may also occur in preprocessor macros. For example: /* The incorrect expression below generates an */ /* "invalid function call" error. */ int i, j; void function(void) { i = i + (j*2); /* Intended expression */ i = i (j*2); /* INCORRECT - deleted "+" operator */ Error and Warning Messages 209 Error 16: invalid function argument A function argument expression following the left parenthesis of a function call is invalid. You may see this message if you omit: [] an argument expression [] a right parenthesis from a function call [] a comma separator between two function arguments. For example: func(.); func(; func(,1); Error 17: too many operands During expression evaluation, the end of an expression was encountered, but more than one operand was still awaiting evaluation. This message may occur if an expression contained an incorrectly specified operation. Warning 18: non-ANSI use of operator in preprocessor condition This message is suppressed by default, but you can enable it with the strict, ansi, or warn=18 options. The ANSI Standard states that the sizeof and comma (, ) operators should not be used in preprocessor conditions. The SAS/C Compiler supports their use in preprocessor conditions, but programs that require strict adherence to the ANSI Standard should not use them. Error 19: unbalanced parentheses The number of opening parentheses in an expression did not equal the number of closing parentheses. If the expression appears correct in the C source file, check any preprocessor macros to make sure they generate balanced parentheses. Error 20: invalid constant expression An expression that did not evaluate to a constant was encountered in a context that required a constant result. The compiler must be able to evaluate any constant expression (for example, expressions used to initialize static or external data) when the program is compiled. The expression in question did not meet this criterion. You may have used an illegal operator for a constant expression (such as ++, +=, function calls, and so on), or you may have used a variable whose value is available only at run time. 210 Appendix 2 Error 21: illegal use of struct, union, or array type An identifier declared as a structure, union, or array was encountered in an expression where such types are not permitted. For example, you cannot use the ++ postincrement operator with a structure: struct FOO { int a, b, c; } f; f++; /* Error 21 */ Warning 22: structure used as function argument This message is suppressed by default, but you can enable it with the warn=22 option. A structure or union was passed as an argument to a function. Although passing structures and unions is legal according to the ANSI Standard, some compilers do not allow you to pass structures or unions. Other compilers pass a pointer to the structure instead of the entire structure. Turn on this warning if your code comes from or must be ported to such a compiler. Error 23: invalid use of conditional operator The conditional expression operator (?: ) was used incorrectly. You may have included the question mark (?) but left out the colon (:). Also, check for an invalid expression after the operator. Error 24: pointer operand required An expression required a pointer at a specific place, but a non-pointer operand was provided. The compiler may generate this message if an expression after the indirection operator (*) was not a pointer or array expression or if the expression before the array indexing operators ( [ l ) was not a pointer or array expression. Error 25: modifiable lvalue required You have attempted to assign a value to an expression that cannot be modified. An Ivalue is any expression that can appear on the left side of an assignment operation. For example, the ANSI Standard states that the result of a cast is not an lvalue; therefore, the following statement is invalid: long x; (short)x = 2; /* Error 25 */ Error and Warning Messages 211 The following examples also generate this error message: #define ADDONE(x) (x)++ ADDONE(12); /* Error 25: Cannot increment a constant */ ADDONE(&g); /* Error 25: Cannot assign to an address */ if(func(10)=j-2); /* Error 25: "==" was intended, not "=" */ &x = &y; /* Error 25: Cannot assign to an address */ You may have defined a variable with the const keyword and then tried to modify the value of that variable. The SAS/C Development System Library Reference, Version 6.0 contains many variables defined with the const keyword, especially pointers to strings. This keyword is required by the ANSI Standard and indicates that these variables will not be modified in the library function to which they are passed. The const keyword is present in the parameter list of the prototype that is found in the associated header file. This prototype, not the declaration you should include in your program, is what is described in the synopsis for each function in the SAS/C Development System Library Reference. Use the synopsis as a guideline for your declarations, but do not include the const keyword. Error 26: arithmetic operand required An expression required an arithmetic operand but the provided operand was not arithmetic. An operand is arithmetic if it declared as char, short, int, long, float, or double or the signed and unsigned variants of these types. Pointers, structures, unions, and functions are not arithmetic operands. Error 27: arithmetic or pointer operand required An expression required an arithmetic or pointer operand, but a structure or union was provided. An operand is arithmetic if it declared as char, short, int, long, float, or double or the signed and unsigned variants of these types. A pointer operand can be a pointer to any other data type, or it can be the address of a variable or function. 212 Appendix 2 Error 28: missing operand During expression evaluation, the end of an expression was encountered but not enough operands were available for evaluation. The compiler may generate this message if you specified a binary operator (such as the addition, subtraction, multiplication, or division operator) with only one operand. Also, check for invalid preprocessor macro expansions. For example: int i; int ary[10]; i = i + ; /* Error 28 */ i = ary[i*]4; /* Error 28 (Among others) */ Error 29: operation cannot be performed on a pointer An operation was specified that was invalid for pointer operands, such as one of the arithmetic operations other than addition or subtraction. Warning 30: pointers do not point to same type of object In an assignment statement defining a value for a pointer variable, the expression on the right side of the assignment (=) operator did not evaluate to NULL or to a pointer of the same type as the pointer variable on the left side of the assignment operator. The warning is also produced when a pointer of any type is assigned to an arithmetic object. Error 31: integral operand required An expression required a given operand to be an integral type, but the actual operand was not an integral type. An operand is integral if it is declared as char, short, int, or long or the signed and unsigned variants of these types. For example, the following code generates error 31: double d; int ary[10]; ary[d] = 10; /* Error 31 */ Error and Warning Messages 213 Error 32: cannot convert to required type The compiler was unable to convert a data item from its base type to the type required by the operation. The compiler may generate this message if you attempt to cast any data type to a structure, instead of casting the type to a pointer to a structure, or if you attempt to cast a structure to any other type. This message can also be produced for implied conversions, such as passing a structure as a parameter to a function expecting some other type. For example, the following code generates error 32: struct FOO f; int j; j = (int)f; /* Error 32 */ Warning 33: non-portable operation on structure or union Your code has attempted to use an operator on a structure or union that is illegal for that type. For example, you may have used the equality == operator on two structures. The ANSI Standard does not permit the use of relational operators on structures or unions. The SAS/C Compiler generates the equivalent of a memcmp call for this construct, but it may not perform as expected. Because structures may contain padding bytes, two structures of the same type with all identical members may compare false. If you intend to use direct structure comparison, make sure you declare the structure static or extern, or initialize the structure to zeroes using a call to memset. For example, the following code generates warning 33: #include struct FileInfoBlock fib1, fib2; if(fib1 == fib2) /* Warning 33 */ Error 34: invalid initializer expression The expression used to initialize an object was invalid. The compiler may generate this message if you fail to separate elements in an initializer list with commas or if you attempt to initialize an array to a single object, as shown in the following examples: int a[3] = 0; /* Error 34 */ int b[3] = { 1 2 3 }; /* Error 34 */ 214 Appendix 2 Error 35: closing brace expected The compiler expected a closing brace (}) to terminate the definition of a function, structure, or nested block scope, but the brace is missing. The compiler may generate this message if: [] too many elements occur in an initializer expression list [] a structure member was improperly declared [] the end of the source file is reached before a definition is complete [] a previous error occurred in a control statement. Warning 36: control cannot reach this statement A statement with no label followed a goto, return, break, or continue statement. The statement is therefore unreachable. This warning can sometimes be produced incorrectly if the compiler reported a previous error while in a control flow statement. Fix all previous errors and recompile your program before trying to fix the error that is generating this message. Error 37: duplicate statement label "name" See line number in file "filename" The specified statement label has already been defined in the current function. You cannot define the same label more than once in the same function. Error 38: unbalanced braces In a set of compound statements, the number of opening left braces ({) did not equal the number of closing right braces (}). This warning may be produced incorrectly if the compiler reported a previous error in a control flow statement. Fix any previous errors and recompile your program before trying to fix the error that is generating this message. Error 39: invalid use of keyword "keyword" One of the C language reserved words appeared in an invalid context (for example, as a variable name). Error 40: break not inside loop or switch A break statement was detected that was not within the scope of a while, do, for, or switch statement. This error may be produced incorrectly because of errors in previous statements. Error 41: case not inside switch A case prefix was encountered outside the scope of a switch statement. This error may be produced incorrectly because of errors in previous statements. Error and Warning Messages 215 Warning 42: case expression not integral The expression defining a case value did not evaluate to an integral constant. This message is generated as an error message if the expression could not be converted into an integral constant and as a warning if the expression could be converted into an integral constant. For example, if you use a variable as a case value, the compiler generates an error message. If you use a floating-point constant as a case value, the compiler converts the constant to an integer (thereby truncating its value) and generates a warning message. For example, in the following code, the case value 1.6 is truncated to 1, and the value -1.6 is truncated to -1. switch(i) { case 1.6: /* Warning 42 */ break; case -1.6: /* Warning 42 */ break; } Error 43: duplicate of case value See line number in file "filename" You have used the same case value more than once within the same switch statement. Check for possible preprocessor macro definitions that expand to the same value. For example, both of the following case statements evaluate to zero: #define FOO 0 #define BAR 2 switch(i) { case FOO: break; case (FOO*BAR): /* Error 43 */ break; } 216 Appendix 2 Error 44: continue not inside loop A continue statement was detected that was not within the scope of a while, do, or for loop. This error may be produced incorrectly because of errors in previous statements. Error 45: default not inside switch A default label was encountered outside the scope of a switch statement. This message may be produced incorrectly because of errors in previous statements. Error 46: duplicate default See line number in file "filename" A default label was encountered within the scope of a switch statement in which a default label had already been encountered. Error 47: while missing from do statement A while clause did not follow the body of a do statement. This message may be produced incorrectly because of errors in previous statements. Error 48: invalid while expression The expression defining the looping condition in a while or do loop was void or was missing. If you intend for a loop to be infinite, you must supply a constant (such as 1) for the while condition. The error may be produced because of a preprocessor macro that expands to invalid code. In many cases, fixing a previous error eliminates this message. Error 49: else not associated with if An else keyword was detected that was not in the scope of a preceding if statement. This message may be caused by an error in a preceding statement, especially if the previous error occurred while processing the if statement with which the else statement is associated. Error 50: label missing from goto The compiler expected a statement label to follow the goto keyword but the label was missing. This message may be produced incorrectly because of errors in previous statements. Error and Warning Messages 217 Warning 51: C++ comment detected This message is suppressed by default, but you can enable it with the strict, ansi, or warn=51 options. In C++, comments begin with two slashes (//) and terminate at the end of the line on which they begin. The SAS/C Compiler accepts comments entered in this way for convenience and for compatibility with other implementations, but they are not part of the ANSI Standard for the C language. Error 52: invalid if expression The expression following the if keyword on an if statement was void, invalid, or missing. This error may be caused by a preprocessor macro expanding to inappropriate values or may be the result of an expression with an invalid return type (such as a structure type). In many cases, fixing a previous error eliminates this message. Error 53: invalid return expression The expression following the return keyword was void, invalid, or missing. The compiler may generate this message if a preprocessor macro expands to inappropriate values. In many cases, fixing a previous error eliminates this message. Warning 54: switch expression not integral The expression defining the test value for a switch statement did not define an integral value as required by the ANSI Standard. The value supplied is converted to int before any attempt is made to use it. If the switch value is a floating-point value, this conversion may truncate the value. This warning can also be generated as an error if the value could not be converted to int. Warning 55: no case values for switch statement The statement defining the body of a switch statement did not define any case statements. This warning may be produced incorrectly because of previous errors. Error 56: colon expected The compiler expected but did not find a colon (:). This message may be generated if a case expression was improperly specified or if the colon was omitted following a label to a statement. Because the compiler scans through newlines, blanks, and comments looking for the colon, this message is usually produced at the beginning of the line following the actual error. 218 Appendix 2 Error 57: semi-colon expected The compiler expected but did not find a semi-colon (;). This error can be generated if you use too many right parentheses or right curly braces (}). Because the compiler scans through spaces and tabs looking for the semicolon, this message is usually produced at the beginning of the line following the actual error. Error 58: missing parenthesis A required parenthesis is missing. This error is often caused by previous errors. Error 59: invalid storage class Possible storage classes are denoted by the keywords __near, __far, __chip, register, auto, extern, and static. Some of these keywords are invalid for certain types of data. For example, you cannot declare an external variable with the register keyword, and you cannot declare an automatic (local) variable with the __chip, __near, or __far keywords. Your code attempted to use a storage class keyword incorrectly. This error often occurs because of previous errors. Error 60: incompatible struct, union or array types Incompatible structure, union, or array types were used in an expression. struct A {int x;} a; struct B {double d;} b; a = b; /* Error 60 */ Error 61: undefined struct/union tag "tag-name" Your code has used a structure or union tag that has not been declared. Check for misspelled structure names. You may want to compile your program with the pponly option or the list option and look at the output produced. Warning 62: constant number out of range for type "type" Valid range is low to high Error and Warning Messages 219 The constant value indicated is not in the range of possible values for the type to which the value is being assigned. This message may occur if you are assigning a hexadecimal constant with the uppermost bit set to a signed variable. By definition, a hexadecimal constant is a positive value; therefore, the assignment to the variable reinterprets the constant as a negative number. For example, the following lines generate warning 62: signed char c = 0x80; /* Warning 62 */ short s = 100000; /* Warning 62 */ unsigned short uc = -1 /* Warning 62 */ Unless you use the unschar compiler option, variables of type char are signed and produce this warning if you assign any constant to them with the high bit set (that is, any value between 128 and 255.) You can suppress this warning for a specific case by casting the constant to the appropriate type. Out-of-range constants can cause problems in your code that are hard to debug. For example, the following code does not behave as intended: int i = 1xff; signed char c = 1xff; /* Warning 62 */ if(i == c) { /* Not executed */ } The constant initializer Oxf f is the decimal number 255. When assigned to the integer variable i, this value is preserved, and i gets the value 255. When assigned to the signed character variable c, the value of c becomes -1 because a signed character cannot represent numbers higher than 127, and the constant Oxf f overflows. Therefore, the comparison in the if statement results in the value false. Warning 63: item "name" already declared See line number file "filename" The named item was previously declared at the cited location. This warning is produced when two different members of the same structure, union, or enum are given the same name. 220 Appendix 2 Error 64: structure contains no members A structure declaration did not contain any members. This error can be produced by errors encountered during the structure's declaration. Fixing a previous error may eliminate this message. Error 65: invalid function definition Your code tried to define a function body inside another function body, inside a structure declaration, or inside a list of static initializers. This message may be produced incorrectly because of errors in previous statements. Warning 66: invalid array limit expression The expression defining the size of the subscript in an array declaration did not evaluate to a positive integral constant. For example: int x[10.7]; Error 67: illegal object Your code attempted to define an illegal item. For example, you may be declaring an array of functions (instead of an array of function pointers) or a function that returns an array (instead of a function that returns a pointer). This message can also be produced if you attempt to define a variable with the same name as a keyword. For example, the following code generates error 67: int break; /* Error 67 */ long while; /* Error 67 */ Error 68: illegal object for structure A structure (or union) included a function as a member. You cannot include a function as a member of a structure or union, although you can include a function pointer. Error 69: struct name includes instance of self The named structure or union contains an instance of itself. Although it is legal for a structure or union to include a pointer to its own type, the structure or union cannot contain an instance of itself. If the structure Error and Warning Messages 221 or union does not have a name, the name field is not printed in the message. For example, the following code generates error 69: struct FOO { int a, b, c; struct FOO x; /* Error 69 */ }; Warning 70: unrecognized escape sequence By default, this message is suppressed, but you can enable it with the strict, ansi, or warn=70 options. Escape sequences in string and character constants begin with a backslash (\) and contain one or more characters after the backslash. The ANSI Standard defines some escape sequences and reserves others for future expansion and for implementation-defined extensions. The SAS/C Compiler ignores the backslash on any such undefined escape sequences. Other compilers may take different action. For example, the following line prints the character q followed by a newline (\n) to stdout: printf("\q\n"); /* Warning 70 */ Other ANSI-conforming compilers may substitute any other character for the \q escape sequence. Error 71: formal declaration error "name" A variable was declared before the left curly brace of in an old-style function definition, but the variable did not appear in the list of identifiers in parentheses following the function name. For example, the declaration of j in the following code generates error 71: int func(i) int i; int j; /* Error 71 */ { } You may have misspelled one of your formal parameters or forgotten to add the parameter to the parameter list. 222 Appendix 2 Error 72: conflict with previous declaration See line number file "filename" A variable or function was declared that conflicts with a previous declaration for the variable or function in the same scope. The message indicates the filename and line number of the original declaration. If no prototype exists for a function, the first use of that function implicitly declares the function as returning an int. If the actual definition of the function follows the first use of the function and declares a different return type, the compiler produces this message. This message may be produced incorrectly if you forget to declare a variable in an earlier location and, therefore, received a previous error message about an undefined identifier with the same name. Fixing the previous error may eliminate this message. Warning 73: declaration expected The compiler expected to find the declaration of a data object or function but did not. This message can also occur if you enter too many or too few curly braces. This message may be produced incorrectly because of errors in previous statements. Fixing the previous errors may eliminate this message. Warning 74: initializer data truncated A static initializer expression contained more elements than the data item being initialized, as in the following example: char b[3] = "abcd"; /* Warning 74 */ String constants always have an implied NULL byte at the end. This byte is not counted when producing this warning. If you have a character array with three elements, you may initialize it as follows: char b[3] = "abc"; Error and Warning Messages 223 The three elements receive the values a, b, and c. If there is room, the NULL terminator byte is also copied: char c[4] = "abc"; The elements of the above array are assigned the values a, b, c, and \0. Error 75: invalid sizeof expression The expression passed to the sizeof operator was invalid. This message may be produced if an attempt is made to take the size of a function, bitfield, or incomplete type, or if the result of the expression used is of type void. For example, in the following code, a is an incomplete type because its size is not specified when it is declared: extern int a[]; int i; i = sizeof(a); /* Error 75 */ Error 76: left brace expected The compiler expected but did not find an opening left brace. For example, you may have omitted the opening brace on a list of initializer expressions for an aggregate. Error 77: identifier expected The compiler expected to find the name of an identifier to be declared. The compiler may generate this message if the prefixes to an identifier in a declaration (parentheses and asterisks) are incorrectly specified or if a sequence of declarations is listed incorrectly, as in the following example: int ; /* Error 77 */ Error 78: undefined statement label "name" A goto statement referred to the named label, but the label does not exist in the function that referred to it. Check the spelling of your label and the goto reference. Make sure the label is in the same function as the goto statement. 224 Appendix 2 Warning 79: duplicate of enumeration value See line line file "file" When declaring an enumeration type, more than one enumeration constant was assigned the same value, as in the following example: enum COLORS (RED=1, BLUE=2, GREEN=1); /* RED and GREEN are identical */ Any enumeration constants that are not assigned an explicit value are assigned values one higher than the previous constant in that enumeration. If the constant is the first constant in that enumeration, it is assigned the value zero. Therefore, the following enum generates warning 79: enum COLORS (RED, BLUE, GREEN=1); /* Warning 79 */ RED is the first constant, so it is assigned a value of 0. BLUE is assigned a value of 1. GREEN is explicitly assigned a value of 1, which conflicts with BLUE. Error and Warning Messages 225 Warning 80: invalid bit field or misplaced ':' This warning is commonly produced if you type a colon (:) when a semicolon (;) was expected. This warning can also be produced if you are actually declaring a bitfield and give an improper expression for the number of bits in the bitfield. Error 81: preprocessor symbol loop; macro expansion too long or circular When using the oldpp compiler option, a preprocessor symbol expanded to a value that contains a circular reference back to the symbol itself, thereby creating an infinite loop in the preprocessor. Check the definition of the macro being expanded on the line in question. This message cannot occur if the oldpp compiler option is not used because the ANSI Standard prohibits the expansion of preprocessor macros that occur as a result of expanding a previous instance of the same macro. Error 82: maximum object/storage size exceeded Your code attempted to declare a data item that exceeded the maximum size of objects in its storage class, or the last object declared caused the total size of declared objects in that storage class to exceed the maximum, as in the following example: char __near a[30000]; char __near b[30000]; char __near c[30000]; Because there is a limit of 32767 bytes on the amount of near data allowed, the above request for 90000 bytes of near data will not work. If you are compiling with data=near (the default), the __near keyword is implied on all data items. Fix this warning by declaring some large data items with the __far keyword or by compiling with the data=far option. 226 Appendix 2 Warning 83: reference beyond object size Your code used an address beyond the size of the object used as the base for the address calculation. This warning usually occurs when you refer to an element beyond the end of an array, as follows: char c[10]; void myfunc(void) { c[11] = 0; /* Warning 83 ~/ } This message can be produced only when the compiler can determine the value of the subscript at compile time, that is, the subscript is a constant. Warning 84: redefinition of pragma or preprocessor symbol "name" See line number file "filename" Your code is redefining the preprocessor symbol or #pragma originally defined at the indicated file and line number. Warning 85: return value mismatch for function "name" Expecting "typel", found "type2" The expression specifying the value to be returned from a function was not the same type as the function itself. If possible, the value specified is converted to the appropriate type. You can suppress this warning by casting the return expression to the appropriate type. Some pre-ANSI C code produces many of these warnings when functions declared as int (either explicitly or implicitly) do not return a value. Before the ANSI committee approved the void keyword, declaring functions as returning an int was the correct way to handle functions that returned nothing. You can compile with the nowarnvoidreturn option to suppress these warnings when a function that is declared as returning an int actually returns nothing. For example, the following two functions generate warning 85: functionl (x) int x; { } /~ Warning 85 ~/ int function2(x) int x; Error and Warning Messages 227 { char *p = NULL; return(p); /* Warning 85 */ } You can suppress the warning 85 for functionl by compiling with the nowvret option. The nowvret option does not affect function2, which is attempting to return a pointer from a function declared as returning int. Warning 86: formal parameters conflict with prototype See line number file "filename" The types of the parameters to the function do not match the types given in the prototype for the function. Check the prototype at the file and line indicated against your definition. Warning 87: argument count incorrect, expecting number arguments See line number file "filename" Your code invoked a function with an incorrect number of arguments, according to that function's prototype. Check the prototype at the indicated file and line number against your usage of the function and the actual function definition. Warning 88: argument type incorrect Expecting "type 1", found "type2" Your code invoked a function with an argument whose type conflicts with the corresponding parameter as declared in the function's prototype. The type of the argument expected is given as type 1, and the type of the argument actually provided is type2. If possible, the argument is converted to the appropriate type as if it were cast to that type. If the argument cannot be converted, an error message is produced. 228 Appendix 2 Warning 89: constant converted from "type1" to "type2" Your code supplied a constant that conflicted with the expected type. The constant was converted, but the conversion may have caused a loss of precision or lost values. For example, in the following code, the prototype for the function f oo specifies an int, but the function is passed a double constant: void foo(int); void myfunc(void) { foo(l0.67); /* Warning 89 */ } The double constant is converted to an integer, resulting in an integer argument of 10, and the compiler generates warning 89 to inform you of the conversion. Error 90: invalid argument type specifier An error was made in declaring an argument in a function or prototype declaration. For example, the following declaration does not specify a type for the parameter y. For example: void foo(int x, y) /* Error 90 */ { } Error 91: illegal void operand One of the operands in an expression was of type void. The void type represents no value and is, therefore, illegal in most expressions. Warning 92: statement has no effect An expression statement did not produce an assignment, function call, or other action. Such a statement serves no useful purpose and can be eliminated. This warning is often generated when a typographical error has been made in coding the statement. For example, you might enter Error and Warning Messages 229 the equality (==) operator when you intended to enter the assignment (=) operator: int i; i == 5; /* Warning 92 */ In this example, the user intended to assign the value 5 to the integer variable i, but because of the extra equals sign, the statement does nothing. Warning 93: no reference to identifier "name" Your code declared an automatic (local) variable but never used the variable. However, the variable might be used by code that has been excluded from the object module with #if or #ifdef statements. Warning 94: uninitialized auto variable "name" An automatic (local) variable was used in an expression before it was given a value. Automatic variables are not guaranteed to have any specific value when a function is entered, so an uninitialized automatic variable can create seemingly random bugs. It is possible for this warning to not be produced when appropriate or to be produced incorrectly because the compiler does not check all possible execution paths. In rare cases, the message is produced incorrectly if the variable is used in a loop construct and initialized later in the same loop construct, as shown: void myfunc(void) { int i, j; for(i=0; i<10; i++) { if(i > 0) printf("%d\n", j); /* Warning 94 */ j = i; } } Without doing detailed loop analysis, the compiler cannot tell that j is not referenced by the call to printf until after it is initialized. 230 Appendix 2 Some cases that use uninitialized variables may not produce the warning. For example, no warning is produced for the following code even though j is not initialized if x is greater than S: void myfUnc(int x) { int j; if(Y < 5) j = X; if(j < 5) /* j might be uninitialized */ { ... } } warning 95: unrecognized #pragma operand The keyword following a #pragma statement was not recognized as a SAS/C pragma keyword. Version 6 of the SAS/C Compiler supports the libcall, flibcall, syscall, tagcall, andmsg #pragmas. Error 96: missing name for #pragma In a libcall, flibcall, syscall, or tagcall #pragma statement, the name of the routine to be called was omitted or incorrect. Error 97: bad library base for #pragma In a libcall, flibcall, or tagcall #pragma statement, the library base was omitted or incorrect. Error 98: invalid data for #pragma In a libcall, flibcall, syscall, or tagcall #pragma statement, the offset or magic number fields were invalid. In a #pragma msg statement, a syntax error was made specifying the message number or the action to be taken. Error 99: attempt to change a const lvalue Your code attempted to modify a variable declared with the const keyword. Variables declared with the const keyword are read-only and cannot be modified. Error and Warning Messages 231 Warning 100: no prototype declared for function "name" Your code called the named function, but the compiler did not find a prototype for that function. Without a prototype, the compiler cannot perform parameter type checking. Remember, a function that takes no parameters still needs a prototype with void as its parameter list: int func(void); /* "func" returns "int" and takes no parms */ If the function is a SAS/C function, the SAS/C Development System Librar,v Reference tells you which header file to #include to get the correct definition for the function. If the function is an AmigaDOS function, its prototype is in the include: clib directory in the file for its library. For more information, you can refer to the Amiga ROM Kernel Reference Manual: Libraries, 3rd Edition (Commodore-Amiga, Inc. 1992) or use the grep command to search the header file in the include: clib directory for the prototype. Error 101: redundant keywords in declaration The same storage class keyword was specified multiple times when declaring a variable, function, or prototype. For example, you may have specified the const or __chip keyword twice. However, you can specify a typedef with a storage class keyword. Any variables declared with this typedef are automatically assigned to that specified storage class. Therefore, you may get an error 101 for specifying the keyword explicitly on a variable declared with the typedef, as in the following example: typedef int __far farint; farint x; /* Declares a far integer called "x" */ farint __far y; /* Error 101 */ Error 102: conflicting keywords in declaration You have specified two mutually incompatible storage class keywords when declaring a variable, function, or prototype. For example, you may have specified the __near and __far keywords on a variable definition. However, you can specify a typedef with a storage class keyword. Any variables declared with this typedef are automatically assigned to that specified storage class. Therefore, you may get an error 102 for 232 Appendix 2 specifying a keyword explicitly on a variable which conflicts with the keyword declared with the typedef, as in the following example: typedef int __far farint; farint x; /* Declares a far integer called "x" */ farint __near y; /* Error 102 */ Warning 103: uninitialized constant "[name]" The named variable was declared const, indicating that the variable is read-only, but you have not initialized the variable. If the variable is declared static or extern, it is initialized to zero for you but is probably not useful unless explicitly initialized. Warning 104: conversion from pointer to const/volatile to pointer to non-const/volatile A pointer to a const or volatile object is being converted to a pointer to a normal object. For example, you may be passing the address of a const variable to a function that takes a normal pointer. After the pointer has been converted, the const or volatile attribute is lost. Therefore, your const data might get modified, or your volatile data might be kept in a register. Error and Warning Messages 233 In the following example, warning 104 is produced when the function foo is called with the const array data as an argument. void foo(char *); void myfunc(void) { const char data [] = "Hello, World!\n"; foo(data); /* Warning 104 */ printf("%s\n", data); } void foo(char *p) { P[1] = 'a'; } The function foo actually modifies its data by writing to it. Therefore, printf prints the value Hallo, World! instead of Hello, World ! because the constant array has been modified. 234 Appendix 2 Warning 105: module does not define any externally-known symbols The C source file and all of its included headers were compiled, but no externally-visible functions or data items were defined. In this case, a valid object file is produced, but it contains nothing that can be accessed, and the file can removed from your link step if you desire. Error 106: postfix expression not allowed on a constant Your code attempted to apply a postfix ++ or--operator to a constant. This message may be generated because of an incorrect macro expansion. You can use the pponly option to generate a preprocessed file and check the macro expansion. Error 107: too many initializers A data item was being initialized, but too many initializer elements were provided, as in the following example: struct FOO { int i, j; }; struct FOO foo = {10, 20, 30}; /* Error 107 */ Warning 108: zero-length arrays are not an ANSI feature This message is suppressed by default, but you can enable it with the strict, ansi, or warn= 108 options. You have declared an array of size zero, probably as a member of a structure to allow variable-sized structures. While using zero-length arrays is a common extension to the ANSI Standard and is supported by the SAS/C Compiler, the ANSI Standard does not allow the use of zero-length arrays. Error 109: invalid use of type name or keyword A type name (possibly a typedef) has been encountered where it was not expected. You may have attempted to declare a variable with the same name as a keyword. Error and Warning Messages 235 Warning 110: enum constant expression is wrong type Expecting "type1", found "type2" An enumeration constant value was explicitly assigned that did not match the type of the enum being declared. For example, specifying a double constant when defining an enum or specifying a long constant when the shortint option is active will generate this message. Example: enum COLORS { RED=1.0 }; /* Warning 110 */ Warning 111: non-portable enum type specified This message is suppressed by default, but you can enable it with the strict, ansi, or warn= 111 options. As an extension to the ANSI Standard, the SAS/C Compiler supports short, char, and long enum types with the syntax short enum, char enum, and long enum. To improve the portability of your code, enable this warning. Warning 114: negative shift or shift too big for type shifts for type "type" must be between O and nUmber bits Your code attempted to shift an integral value by a constant number of bits, but the constant was either negative or higher than the number of bits in the value being shifted, as shown in the following examples: int i = l; i = i >> 33; /* Warning 114 */ i = i << -l; /* Warning 114 */ In the first example, i is 32 bits (an int) but is being shifted 33 bits. Shifting a value by a number of bits higher than the number of bits in the value generates a zero for the result. In the second example, i is being shifted by a negative number of bits. Attempting to shift a value by a negative number of bits usually generates a zero for the result (although this result is undefined by the ANSI Standard). Error 115: enum constant value "number~ out of range for enum type Your code specified a value for an enum constant while defining an enumerated type which is out of range for the type of enum being declared. Remember that enum constants that are not explicitly assigned a numerical value are given the value of the previous constant defined 236 Appendix 2 in the same enum incremented by one. This increment might place the constant's value out of the acceptable range, as in the following example: char enum COLORS { RED=254, /* Numeric value is 254 */ GREEN, /* Numeric value is 255 (254+1) */ BLUE /* Numeric value is 256 - too big for char */ }; /* Error 115 is issued */ The enum constant RED is assigned a value of 254. GREEN does not have an explicit value, so it is assigned 254+1, or 255. BLUE does not have an explicit value, so its value would normally be 255+1, or 256. However, the enum is declared as being a char enum, so 256 is too big and error 115 is issued. Warning 116: undefined enum tag "name" A reference was made to an enum that has not yet been declared. The compiler may generate this message as a warning if only a pointer to the enum is used, but the compiler generates this message as an error if any other use is made of the enum. Error 117: enum contains no members An attempt was made to define an enumerated type, but no member names were specified. Use the pponly option to generate a preprocessed file if you have problems eliminating this message. Error 118: conflicting use of enum/struct/union tag "name" An attempt was made to define an enum, struct, or union that has the same name as a previously defined enum, struct, or union in the same scope. You cannot define an enum with the same name as a struct, union, or another enum. Error and Warning Messages 237 Error 119: identifiers missing from definition of function "name" A prototype-style function definition was encountered, but the names of the parameters were missing. You can omit the parameter names from a prototype, but the names must be present in the actual function definition. For example the following code generates error 119: void func(int, int, double); /* Legal prototype */ void func(int, int, double) /* Illegal function definition */ { /* Error 119 */ } Warning 120: Integral type mismatch: possible portability problem Expecting "type1", found "type2" This message is suppressed by default, but you can enable it with the strict or warn=120 options. The wrong integral type was passed as a parameter. This error may be a problem on another compiler or another type of computer if the size of an int is different from the size of an int on the Amiga computer. This warning is not a problem if your code needs to run with the SAS/C Compiler only. In the following example, the SAS/C Compiler promotes the short integer to a long integer even if you compile with the shortint option: #pragma msg 120 warn void func(long); void main(void) { short s = 10; func(s); /* Warning 120 */ } However, pre-ANSI compilers on machines that define the int type to be the same as short may not perform the conversion or may perform the conversion and issue a warning message. In addition, if you remove the prototype, this code will not work on any machine where int is the same as short. 238 Appendix 2 Warning 121: hex/octal constant "constant" too large for char High bits may be lost Warning 121 is generated if a hexadecimal or octal constant specifies more digits than will fit into a single char. According to the ANSI Standard, hexadecimal bytes may be specified in a quoted string using the \xhh escape sequence. The ANSI Standard also states that the escape sequence consumes all valid hexadecimal characters in the string following the \x, even if all the characters consumed will not fit into a single byte, which may not be what you want. For example, in the case of \xabcdefgh, you may want the character 0xab first, followed by the string cdefgh. According to the ANSI Standard, this escape sequence evaluates to the character Oxef followed by the string gh, because the \x consumes all valid hexadecimal characters. A single byte cannot hold the hexadecimal number 0xabcdef, so the top bits are lost and 0xef is the result. The best way to get the character 0xab followed by the string cdefgh is to use ANSI string concatenation to terminate the escape sequence: \xab cdefgh. The two strings are concatenated to form the desired sequence. Warning 122: missing ellipsis A function or function prototype was encountered that attempted to specify variable arguments with a trailing comma in the argument list. According to the ANSI Standard, variable arguments must be specified by a trailing comma followed by an ellipsis (...). The SAS/C Compiler accepts the form without the ellipsis as if the ellipsis had been specified, but other ANSI conforming compilers may require the ellipsis, as in the following example: void foo(int x, ... ); /* Right */ void bar(int x, ); /* Wrong */ Warning 123: no tag defined for enumeration Cannot construct prototype The genproto option was active, but a prototype could not be generated for a function because an enum was used as a parameter to the function and that enum had no tag, as shown in the following example. void myfunc(colors) enum (RED, GREEN, BLUE) colors; { } Error and Warning Messages 239 The tag is the name normally appearing immediately after the keyword enum in the enum declaration. This message is produced only if the genproto compiler option is used to produce prototypes. Error 125: invalid number The numerical constant specified cannot be represented on the Amiga computer. The constant is probably an integer that is too large or too small (negative) to be represented in four bytes. This error can also be produced if a floating-point number is specified incorrectly or if invalid digits are provided to an octal constant. The following lines all produce error 125: double d = 10.3.2; /* Error 125 */ int i = 123456789123456789; /* Error 125 */ int j = 099; /* Error 125 */ In the first line, the value assigned to the floating-point variable has been incorrectly specified. In the second line, the value contains too many digits to fit into an int. In the third line, the value begins with a zero, which makes the value an octal constant, but it contains the digit 9, which is invalid for octal constants. Warning 126: #endif, #else, or #elif out of order A #endif, #else, or #elif was encountered but no #if or #ifdef was active. Error 127: operand to # operator must be a macro argument If a preprocessor macro parameter is preceded with the # operator, that parameter is replaced with the literal string consisting of the corresponding argument to the macro. For example, if you pass the argument FOO to a macro, and that argument in the macro definition is preceded by the # operator, that argument expands to the string "FOO". The # operator can be applied only to macro arguments. Error 128: text-from-#error This message is the result of a #error preprocessor directive in the source code being compiled. The text of the message is taken from the #error line. Error 129: ambiguous struct or union member "name" Your code referred to a structure or union member that did not exist. In an attempt to resolve the name, the compiler examined the names of all members of substructures or subunions. Two or more members of subaggregates matched the name you provided, so the compiler was unable to determine which member you intended to specify. 240 Appendix 2 Suppose you have the following code: void main(void) { struct FOO { int x, y, z; }; struct BAR { int a, b, x; }; struct COMBO { struct FOO foo; struct BAR bar; } combo.a = 10; /*Warning 193*/ combo.x = 10; /*Error 129*/ } The reference to combo.a succeeds, although it generates a warning 193 (implicit reference to structure member), because the full reference should be combo.bar.a. The reference to combo.x generates error 129, because both substructures of combo contain a member called x. The compiler cannot tell whether you mean combo.foo.x or combo.bar.x, so it issues the error message 129. See Chapter 11, "Using Amiga Specific Features of the SAS/C Language," for more information on implicit structure references. Error l31: maximum temporary or formal storage exceeded The compiler must allocate stack storage to allow you to pass and receive structures or other parameters to and from functions. Parameters are copied onto the stack for each function call, so if you are passing large structures, your code will run very slowly. Consider passing a pointer to your structure instead of the entire structure. Error and Warning Messages 241 Warning 132: extra tokens after valid preprocessor directive The ANSI Standard does not allow extra text on a preprocessor line, but this extra text may be allowed by some C compilers. For example, many programmers put a descriptive word after a #endif directive indicating the #if to which the #endif belongs. To make your code ANSI-compatible, you should place such descriptive words in comments, as shown in the following example: #ifdef SOMETHING #endif SOMETHING /* Warning 132 */ #ifdef SOMETHING #endif /* SOMETHING */ /* No warning */ Error 133: cannot redefine macro "name" An attempt was made to redefine a built-in preprocessor macro, like __FILE__ or __LINE__ You cannot redefine built-in preprocessor macros. Warning 134: too many arguments A macro definition was encountered with more than the allowable number of arguments. The current ANSI limit for macro arguments is 31, and the SAS/C Compiler does not allow more than 31 arguments. If message 134 is issued, the macro is not successfully defined. Any use of the macro in your code produces a warning for a function with no prototype and possibly a linker error when the name of the macro cannot be resolved by the linker. Error 135: argument count incorrect for macro "name", expecting number arguments See line number file "filename" Your code invoked a macro with too few or too many arguments. The macro is defined at the specified file and line number. Error 136: invalid use of register keyword Your code used one of the register keywords inappropriately. The register keywords are register, __a0, __d0, __a1, __d1, and so on. 242 Appendix 2 Warning 137: ANSI limits #line numbers to between 1 and 32767 This message is suppressed by default, but you can enable it with the strict, ansi, or warn=137 options. The ANSI Standard states that line numbers specified with a #line directive should be between 1 and 32767. However, the SAS/C Compiler accepts any number that will fit into a signed four-byte integer. Error 138: operation invalid for pointer to void Your code attempted to perform an operation on a void * pointer that is not valid for void *. Such operations include addition, subtraction, array indexing, and dereferencing (unary * operator). For example, the following code attempts to perform addition on a void * pointer: void *p = NULL; p = p + 1; /* Error 138 */ Warning 139: missing #endif See line number file "filename" The compiler encountered an #if, #ifdef, or #elif statement for which there is no matching #endif. The file and line number of the unmatched directive is specified in the message. This message occurs only at the end of the source file, so large portions of your program may have been ignored because of a stray #if or #ifndef with no matching #endif. Warning 140: sizeof operator used on array that has been converted to pointer Use of the sizeof operator on an array name gives the size of the array. However, if the array name has been converted (cast) to a pointer, the resulting size is the size of the pointer (4 bytes), not the size of the array. Almost any use of an array name in an expression implicitly casts the array name to pointer. To determine the actual size of the array, pass only the array name to the sizeof operator. Error and Warning Messages 243 In the following example, in the first assignment statement, i gets the value 4 (the size of a pointer to a character). In the second assignment statement, i gets the value 10. char ary[10]; int i; i = sizeof(ary+1); /* Warning 140 */ i = sizeof(ary); Error 142: array size never given for "name" You can declare an array as extern and not specify the first subscript. However, when you define the array, you must specify the subscript. Storage is allocated when you define an array, not when you declare an array as extern. For example: extern char ary1[][10]; /* Legal */ char ary2[][10]; /* Error 142 */ Error 143: object has no address An attempt was made to take the address of something that has no address. You may be attempting to take the address of a register variable or an expression. Warning 146: case value out of range for switch type A case value was specified in a switch statement that can never be taken. For example, if you compile with the shortint option and a switch statement is switching on a short or int value, case values too big to be stored in 16 bits will generate this warning: /* The SHORTINT compiler option is on. */ int i = 10; switch(i) /* i is a 16-bit integer */ { case 0x08000000: /* Warning 146 */ break; case 65000: /* Warning 146 */ break; } 244 Appendix 2 Warning 147: conversion between function and data pointers Your code has cast or otherwise converted a pointer that points to a function to a pointer that points to data. The ANSI Standard states that this conversion is not legal. This conversion works with the SAS/C Compiler in most circumstances, but you should use the absfuncpointer compiler option if your code is larger than 32K. Warning 148: use of incomplete struct/union/enum tag "name" See line number file filename This message is suppressed by default, but you can enable it with the warn= 148 option. An incomplete tag is one for which no definition has been seen. The ANSI Standard allows use of an incomplete tag (for declaring pointers, for example). If you want to know when an incomplete tag is being used, enable this warning. You may also want to enable warning 149. Warning 149: incomplete struct/union/enum tag in prototype scope "name" This message is suppressed by default, but you can enable it with the strict or warn= 149 options. An incomplete tag was discovered in a prototype. An incomplete tag is one for which no definition has been seen. The ANSI Standard requires the incomplete tag's scope to end at the end of the prototype. Therefore, any definition of the function later, even if the tag in question has been defined, may generate an error message and terminate the compilation. You may want to turn on warning 148 for the most information about incomplete tags. If you do not want to see all the incomplete tag information, you identify most problem cases by enabling only warning 149. The following function definition produces an error on many ANSI- conforming compilers because the structure FOO referred to in the definition is considered to be a different structure FOO than the one referred to in the prototype. Error and Warning Messages 245 void func(struct FOO *); /* Warning 149 */ struct FOO { int x, y, z; }; /* Many compilers issue an error here. */ void func(struct FOO *foo) { } This error could be fixed by moving the definition for the structure FOO before the prototype. Warning 150: the keyword "name" is meaningless for itemtype When declaring a function or data item, you have used a keyword that is meaningless for that type of item. For example, you cannot specify the following: void __chip foo(int); /* Warning 150 */ It is meaningless to say that a function is to be allocated in _ _ chip memory. The __near and __far storage class keywords are valid on both functions and data items, but have slightly different meanings. See the descriptions of the data=near and code=near options in Chapter 8, "Compiling and Linking Your Program," for more information. Some keywords that are valid on functions are also valid on data items because the data items may be pointers to functions of the designated type. For example, you may have a function that returns a pointer to a __regargs function. Keywords in this category include __stdargs, __regargs, __asm, and __interrupt. Other keywords need to be present only on the function definition. You do not need to add them to function pointers and function prototypes. Keywords in this category include __stackext and __saveds. If these keywords appear on a data item, warning 150 is generated and the extra keyword is ignored. For more information on specifying keywords, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." 246 Appendix 2 Error 152: cannot define function via typedef name Your code attempted to define a function using a typedef, as shown below: typedef int foo(int); foo bar /* Error 152 */ { } According to the ANSI Standard, you cannot define a function using a typedef. The SAS/C Compiler does not accept such a definition. Warning 154: no prototype declared for function pointer Function pointers require prototypes just like functions. To declare a prototype for a function pointer, enter the parameter list instead of the empty parentheses in the definition, as shown in the following example: void (*func1)(); /* Warning 154 */ void (*func2)(int, double, long); /* No warning */ Remember that a pointer to a function that takes no parameters still requires a prototype: void (*func3)(void); /* Function pointer takes no parms */ Error and Warning Messages 247 Warning 155: no statement after label The C language does not allow a label immediately before the curly brace ending a block (}). If you enter a label in this position, the SAS/C Compiler generates this warning. Enter a semicolon (representing a NULL statement) after the label to suppress the warning, as shown in the following example: void funcl(void) { goto foobar; /* more code */ foobar: /* Warning 155 */ } void func2(void) { goto foobar; /* more code */ foobar: ; /* No warning */ } Warning 156: operation/comparison of pointer to "int" and pointer to "type" This message is suppressed by default, but you can enable it with the warn= 156 options. If you compiled with the short int option, your program has used a pointer to int and a pointer to short in an operation. If you did not compile with the shortint option, your program has used a pointer to int and a pointer to long in an operation. 248 Appendix 2 For example, the following code will work if int and long are the same length, but the same code will not compile if ints and longs are different lengths: /* Assume SHORTINT is not active */ int *ip = NULL; long *lp = NULL; int diff; diff = ip - lp; Error 158: invalid type name The compiler expected a type name for a cast or of f setof operation, but the provided name was not recognized as a valid type name. Check the preprocessed output to make sure you are providing the correct information. Warning 159: use of unary minus on unsigned value This message is suppressed by default, but you can enable it with the strict or warn= 159 options. Your code has used the unary minus operator (-) on an unsigned variable. Using this operator on an unsigned variable may not produce the expected result because the result is still a non-negative number. Warning 161: no prototype declared at definition for function "name" An old-style function definition was encountered, and no prototype was in scope. The prototype must appear in the C file or a header file before the definition of the function, or the function definition itself must be a prototype-style definition. Warning 162: non-ANSI use of ellipsis punctuator This message is suppressed by default, but you can enable it with the strict, ansi, or warn=162 options. You have declared a function with the ellipsis punctuator (...) but the function has no arguments. The ANSI Standard requires functions that take a variable number of arguments to take at least one fixed argument. Warning 163: initialization of auto struct, union, or array This message is suppressed by default, but you can enable it with the strict or warn=163 options. Your code has initialized an automatic structure, union, or array. The ANSI Standard allows you to initialize automatic structures, union, and arrays, but many pre-ANSI compilers do not. Error and Warning Messages 249 Warning 164: & applied to array This message is suppressed by default, but you can enable it with the strict or warn= 164 options. Your code has used the address (&) operator on an array name. You should instead take the address of the first element in the array, or use the array name without the address operator. For example: int ary[10]; int *iptr; iptr = &ary; /* warning 165 */ iptr = ary; /* OK */ iptr = &ary[0]; /* OK */ Warning 165: use of narrow type in prototype This message is suppressed by default, but you can enable it with the warn = 165 option. This warning is provided for detecting situations that may cause problems on other compilers if your code mixes function prototypes and old-style function definitions. See Chapter 13, "Writing Portable Code," for information on using narrow types in function declarations. See also the descriptions of messages 176 and 179. Error 166: unrecoverable error or too many errors Terminating compilation Your program has exceeded the default or specified maxerr or maxwarn values, or an error has occurred that prevents the compiler from producing meaningful results. The default maximum number of errors is 50. By default, any number of warnings may be generated. Warning 169: ineompatible operands of conditional operator (?:) "type1" conflicts with "type2" The operands of the ?: conditional operator must be of compatible types. Your code supplied types to the ?: operator that were not compatible. For example, the following code generates warning 169: int func(void) { int i = 0; struct FOO *foo = NULL; return (int)(i > O ? foo : i); /* Warning 169 */ } 250 Appendix 2 The expression following the question mark (?) is of type struct FOO *. The expression following the colon (:) is of type int. This message can be an error if it is not possible to convert the types in question. This can occur if one of the types is a structure or union. Warning 170: overflow during operation on constants A constant expression overflowed the limits of the type in which it was being calculated. Perhaps you have added or multiplied two large integers, thereby resulting in a number too large to represent in a four- byte integer. Warning 176: implicitly promoted formal "name" conflicts with prototype See line number file "filename" This message is suppressed by default, but you can enable it with the strict, ansi, or warn= 176 options. You are defining a function using an old-style definition, which means that any narrow types (char, short, and float) in your definition are implicitly widened to their non-narrow equivalents (int, int, and double, respectively). However, a prototype is in scope that gives the narrow version of the type. Functions that call your function will not know that your function is using an old-style definition and, with some compilers, may pass an incorrect value. An incorrect value is never passed using the SAS/C Compiler on the Amiga hardware. See Chapter 13, "Writing Portable Code," for information on using narrow types in function declarations. See also the descriptions of messages 165 and 179. Warning 178: indirect call without indirection operator This message is suppressed by default, but you can enable it with the strict or warn= 178 options. You called a function using a function pointer, but did not use the indirection (*) operator to dereference the pointer first. The SAS/C Compiler generated correct code, but on pre-ANSI compilers this code may not work. Example: void (*funcptr)(int); funcptr(10); /* Warning 178 */ (*funcptr)(10); /* No warning */ Error and Warning Messages 251 Warning 179: narrow type used in old-style definition This message is suppressed by default, but you can enable it with the strict or warn=179 options. Your code has used a narrow type (char, short, or float) in an old-style definition. See Chapter 13, "Writing Portable Code," for information on using narrow types in function declarations. See also the descriptions of messages 165 and 176. Warning 180: no space between macro name and its replacement list This message is suppressed by default, but you can enable it with the strict, ansi, or warn=180 options. Your code is defining a preprocessor macro that takes arguments but does not have at least one blank after the closing parentheses of the argument list. The ANSI Standard requires white space after the closing parentheses. For example: #pragma msg 180 warn #define ADD(a,b)(a+b) /* Warning 180 */ Warning 181: "name" was declared both static and external See line number file "filename" Your code has declared a function as both static and external at different places. Both the function and its prototype must agree on whether the function is static. Warning 182: static function "name" declared but not defined See line number file "filename" Your code had a prototype for a function declared static but never defined the function. The function definition may be hidden with # i f or #ifdef statements. Warning 183: inline function declared but not defined See line number file "filename" Your code had a prototype for a function declared __inline but never defined the function. The function definition may be hidden with #if or #ifdef statements. Warning 184: invalid multi-byte character constant Your code has specified a multibyte character constant (such as ~ ab ' ), and you did not compile your code with the mccons option; or, if you compiled your code with the mccons option, the multibyte character is larger than the permitted four bytes. 252 Appendix 2 Error 185: comma expected The compiler expected a comma but did not find one. This error may be produced because of errors in previous statements. Fix all previous errors before fixing this one. Warning 186: implicit conversion between pointer and scalar Your code has converted a pointer to an integer while doing static initialization. You can suppress this warning by casting the pointer to the appropriate type. Warning 187: negative value assigned to unsigned type This message is suppressed by default, but you can enable it with the strict or warn=187 options. Your code has assigned a negative constant to an unsigned variable. In doing so, your code is in effect assigning a very large positive number to the variable, which may or may not be the action you intended. Warning 190: #include ignored because header already included See line number file "filename" This message is suppressed by default, but you can enable it with the warn=190 option. The nomultipleincludes compiler option is active, and your code included the same header file more than once. The compiler ignores the additional #include statement. You can use this message to locate all such multiple includes if you want to modify your header files to not include the same file more than once. You can get even more information about which header files were included by using the listincludes compiler option. Warning 192: wrong size for enum An enum variable was declared to be of a different type than the base enum was when it was defined. Suppose you have the following code: char enum COLORS = (RED, GREEN, BLUE); enum COLORS color; /* Warning 192 */ char enum COLORS color2; /* correct */ The enum variable color should be declared the same size as the base enum type, which is char enum. The base enum type overrides the enum variable's type definition. Error and Warning Messages 253 Warning 193: implicit reference to struct/union member Reference assumed to be "reference" Your code has referred to a struct or union member name that is actually a member of a substructure or subunion of the original. The compiler has searched all substructures and subunions and determined that exactly one member matches the name you specified, so it is using that member. The reference printed in the message text is the fully expanded name of the member that it is using. If you intend to take advantage of this feature of the SAS/C Compiler, you may disable this warning with the ignore= 193 option. If you choose to disable this warning, your code may not work on other compilers. For more information on using implicit structure references, see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." Warning 194: too much local data for NEAR reference, some changed to FAR You have declared more than 32K of static data. The compiler can address up to this amount using 16-bit offsets. Amounts greater than 32K must be addressed using 32-bit offsets. You may have compiled with the data=f aronly option and declared some data with the __near keyword. If your entire project is in one source file or is compiled with data=faronly, you can ignore this warning unless you get an error later in the compilation or link. Otherwise, you must eliminate some near data in one of three ways: [] Compile your program with the strmerge compiler option. This option moves all string constants to the code section, thereby moving them out of the near data section. [] Declare read-only data as static const. When you compile with the stringmerge option, this data will also be moved to the code section. [] Add the __far keyword to some of your larger external or static data items to move those items from the near section to the far section. Specify the data=far compiler option to move all data items except those declared with the _ _ near keyword to the far section. Note: The second line of message 194 is not printed unless you compiled with the data=auto option, or you compiled with the data = faronly option and declared data with the __near keyword. 254 Appendix 2 Warning 195: nested comment detected This message is suppressed by default, but you can enable it with the warn= 195 option. The compiler found the start of a comment (/*) inside of a comment. Some compilers allow comment nesting and others ignore the start of the second comment. The ANSI Standard does not allow nested comments. If you choose to use nested comments, you should specify the comnest compiler option. However, using the comnest option prevents your code from running on most ANSI- compliant compilers. Warning 196: specified include directory not found: "name" The named directory does not exist or could not be accessed. Warning 198: __regargs invalid for a varargs function Functions that take variable numbers of parameters always pass their parameters on the stack. The __regargs keyword is invalid for these functions. Error 199: unbalanced comment See line number file filename Your code has a comment open (/*) with no corresponding comment close (*/). This condition is not detected until the end of the C source file. Warning 204: macro invocation not terminated Your code invoked a macro but did not supply enough closing parentheses to terminate the invocation. Also, check any of the macros that are invoked by the macro that you invoked directly in your code. Warning 209: macro invocction may have multiple side effects You have passed an expression with a side effect as an argument to a macro, and that macro has evaluated the argument more than once. Operators with side effects are ++,--, +=, /=, *=, -=, >>=, <<=, |=, &=, and =. For example, the max and min macros evaluate each argument twice. If you invoke the max macro as MAX ( i ++, j ), the first argument is evaluated twice, and two post-increments take place. You could define the max macro as follows: #define MAX(x,y) ((x) > (y) ? x : y) int i = 0; i = MAX(i++, 0); /* Warning 209 */ Error and Warning Messages 255 The macro expands to: i = ((i++) > (0) ? i++ : 0); The expansion contains the expression i++ twice, so if that branch of the ?: operator is executed, the variable i is incremented twice. This warning may sometimes be produced incorrectly, but you should examine each case to determine whether there is an error. Function calls are also considered side effects, but function calls produce warning 217 instead of warning 209. Warning 212: item "name" already declared See line number file "filename" This message is suppressed by default, but you can enable it with the warn=212 option. You have declared an item twice. For example, you may have specified the prototype for a function twice, or you may have declared an extern twice. The declarations do not conflict, or the compiler would generate error 72, but code is harder to maintain if it defines the same item in more than one place. You may want to use the nomultipleincludes option to suppress multiple #includes of the same file if you enable warning 212. Warning 213: empty argument to preprocessor macro This message is suppressed by default, but you can enable it with the strict, ansi, or warn=213 options. Your code calls a preprocessor macro with no argument text. This action is accepted by the SAS/C Compiler but is not permitted by the ANSI Standard. For example: #define FOO(a,b) a FOO(lO,) Warning 216: symbol "name" found You have compiled with the fsym compiler option, and the compiler has found a definition of one of the symbols that you specified as the parameter to the fsym option. Warning 217: macro invocation may call function multiple times You have passed a function call as an argument to a macro that evaluates its arguments more than once. This action may cause incorrect results. See also the description of message 209. 256 Appendix 2 Error 218: declaration found in statement block The compiler found a declaration where it expected a statement. You may have a statement in the middle of your declaration block, or vice- versa. Any declarations found after this error are added as external variables, which suppresses warnings about undefined variables but may create additional errors later if your code declares a variable of the same name. In the following example, the variable y is declared after the first statement of the function: void func(void) { int x; x = 10; int y; /* Error 218 */ } Warning 220: old-fashioned assignment operator taken as "operators" This message is suppressed by default, but you can enable it with the strict or warn=220 options. Older compilers allowed the operators =-, =+, and so on. In ANSI C, these operators are specified as -=, +=, and so on. The older specification is ambiguous when assigning certain expressions (for example, x=-5; and x= - 5; ). To resolve this ambiguity, newer compilers use =-, and some pre-ANSI compilers use -=. Therefore, you should enter at least one space between the equals (=) sign and whatever operator follows it to ensure portability. Error 223: "filename" is not a valid GST file The specified filename was supplied using the gst compiler option as a Global Symbol Table file, but it is not a valid GST file. Delete the bad file and try re-creating it. Warning 224: item "name" already defined See line number file "filename" This message indicates that a variable, function, or typedef is being defined for the second time in a given scope. This message is normally an error, but if the redefinition is harmless, the compiler allows it and issues the message as a warning instead. As shown in the following example, the compiler allows redefinition of typedef names in the same scope if the new type is identical to the old type. The compiler does not allow redefinition of functions or variables in the same scope. Error and Warning Messages 257 typedef int foo; typedef int foo; /* Warning 224 */ void func(void) { } void func(void) /* Error 224 */ { } Warning 225: pointer type mismatch "type1" does not match "type2" Your code has performed an assignment or some other operation on two incompatible different pointer types or on a pointer type and an arithmetic type. For example: struct FOO { int x, y, z; } foo; int *ip; ip = &foo; /* Warning 225 */ Error 226: cannot convert "type1" to "type2" The compiler was unable to perform a requested or implicit conversion. For example, if one of the types is an instance of a structure, the structure cannot be cast to another structure type or to an arithmetic type. For example: struct FOO { int x, y, z; } foo; int i; i = (int) foo; /* Error 226 */ 258 Appendix 2 Explanations of Linker Messages Error 103: Out of memory!! Error 103: Out of memory!! slink has run out of memory. By default, slink attempts to cache slink has run out of memory. By default, slink attempts to cache the object modules in memory between pass 1 and pass 2. If slink runs out of memory, it attempts to free the cached object modules. In some cases, slink cannot find enough continuous memory. Try adding bufsize 4096 to the slink command. This option turns off object module caching. Error 425: Cannot find library library-name The linker cannot find the specified library. Usually, SAS/C libraries are located in the LIB: directory. You may have misspelled to library name in your slink command. Error 426: Cannot find object name The linker cannot find the specified object. Error 443: filename is an invalid file name The linker found an invalid character in a filename. Error 444: Hunk_Symbol has bad symbol-type symbol symbol-name The object module is corrupt. Try recompiling the object module. Error 445: Invalid HUNK_SYMBOL symbol-name The object module is corrupt. Try recompiling the object module. Error 446: Invalid symbol type symbol-type for symbol-name Either the object module is corrupt, or slink has found a symbol type that it does not recognize. Try recompiling the object module. For a list of valid symbol types, refer to the description of object file structure in The AmigaDOS Manual, 3rd Edition. Error 447: filename is a load file The file specified is an executable module instead of an object module. Error 448: filename is not a valid object file The file specified is not an object module. The file may be a C source file or a corrupt object module. Error 449: No hunk_end seen for filename The object module is corrupt. Try recompiling the object module. Error 450: Object file filename is an extended library A library file was specified as an object module. Add the library keyword in front of the library name. Error and Warning Messages 2S9 Error 501: Invalid Reloc 8 or 16 reference An 8- or 16-bit relocation address cannot reach its destination. The SAS/C Compiler does not generate 8-bit relocation records, but third party products may use them. The object module is probably corrupt. Try recompiling your source file. If recompiling the file does not correct the error, contact the Technical Support Division. Error 502: function-name symbol - Distance for Reloc16 greater than 32768 The distance from the point where the function is called to the function itself is greater than 32767 bytes. The function cannot be referenced with a 16-bit address field. Normally, slink tries to insert an ALV (Automatic Link Vector) at the end of the calling module, but if the module has more than 32K of code, the relocation may not reach the ALV. An ALV is the instruction used to reach functions that would otherwise be too far away. Compile the file with -code=far, or declare the function with the __far keyword. Error 503: function-name symbol - Distance for Reloc8 greater than 128 The distance from the point where the function is called to the function itself is more than 128 and so the function cannot be referenced with an 8-bit address field. The SAS/C Compiler does not generate 8-bit relocation records, but third party products may use them. Error 504: variable-name symbol - Distance for Data Reloc 16 greater than 32768 The distance for the 16-bit relocation is too far. You may see this message if a data item (such as a structure or an array) is larger than 64K or if the total amount of data in your program is greater than 64K. To correct the problem, you can either break the data item down and make it smaller than 64K, or you can place the __far keyword on the definitions of one or more data items to force all references to those items to be 32-bits. Using the __far keyword reduces the amount of data in the near data section to less than 64K. You can also compile your program with the data = far option. However, using data=far increases code size and execution time. Error 505: variable-name symbol - Distance for Data Reloc8 greater than 128 The distance for the 8-bit relocation is too far. The SAS/C Compiler does not generate 8-bit relocation, but third party products may use them. 260 Appendix 2 Error 506: Can't locate resolved symbol symbol-name If this message appears, please contact the Technical Support Division. See Chapter 3, "Getting Help," for a complete list of items that you need to provide to the Technical Support staff. Error 507: Unknown Symbol type symbol-type , for symbol symbol-name Either the object module is corrupt, or a slink has found a symbol type that it does not recognize. Try recompiling your source file. For a list of valid symbol types, see the description of object file structure in The AmigaDOS Manual, 3rd Edition. Error 508: Symbol type symbol-type unimplemented Either the object module is corrupt, or a slink has found a symbol type that it does not recognize. Try recompiling your source file. For a list of valid symbol types, see the description of object file structure in The AmigaDOS Manual, 3rd Edition. Error 509: Unknown hunk type symbol-type in Pass2 If this message appears, please contact the Technical Support Division. See Chapter 3, "Getting Help," for a complete list of items that you need to provide to the Technical Support staff. Error 510: symbol-name symbol - Near reference to a data item not in near data section The linker expected the specified symbol to be in the near data section, but the symbol is located in either the far data section, chip memory, or the code section. You may have defined a variable as __far with the __far keyword in one module and externally declared the same variable in another module without the __far keyword. If so, the module with the external declaration attempted to reference the data as near. To correct the problem, the definition and all declarations of the data item must be specified with the same keywords. If you compiled your file with the data=auto option, the compiler can place variables into the far data section if necessary. The compiler may have placed a variable in one module in the far section and a variable in another module in the near section. To correct this situation, either stop using the data=auto option, and use the __far keyword (if necessary) on the definition and all declarations of the variable that causes the error. Error and Warning Messages 261 Error 512: Invalid branch to function-name in overlay node module-name The linker detected a branch in an overlay node that calls another overlay node at the same level. This type of branch is not supported by the overlay manager. Error 513: Multiple NTRYHUNK segments not permitted The NTRYHUNK is the root overlay node. No other hunks should have this name. Error 514: Overlay manager _ovlyMgr is undefined This _ovlyMgr function is located in SAS/C libraries. To use the SAS/C overlay manager, link with sc.lib or scs.lib. You can also write your own overlay manager. See Chapter 8, "Compiling and Linking Your Program," for information on creating your own overlay manager. Error 515: An ALV was generated pointing to data variable-name symbol A 16-bit relocation could not reach its destination, so slink inserted an ALV (Automatic Link Vector) instruction, and then determined that the destination is not in a code hunk. To correct the problem, make the reference a 32-bit reference. This error may be generated for object code produced by third-party assemblers and compilers Error 516: Attempt to merge BSS with CODE or CODE/DATA Either you have attempted to merge the far BSS section with the far data section, or you have attempted to merge the near or far BSS section with the code section. You can merge a BSS section with the __MERGED section only. You will see this message if you have assigned the same name to either the far BSS section and the far data section or the far BSS section and the code section. If you get this error in another situation, please call the Technical Support Division. Note: Do not name the code section __MERGED. Error 600: Invalid command command The option listed is not a valid slink option. Error 601: option option specified more than once The option has been specified twice. 262 Appendix 2 Error 602: Unable to open output file filename slink cannot open the output file for write access. Another program such as CodeProbe may have left a lock on the file. Alternatively, the protection bits may prohibit write access to the file, or that the name specified may be a directory. Error 603: string is not a valid number The linker found a non-numerical character in a field where it expected to find a number. Error 604: with file is not readable The with file may contain binary characters or may be locked. Error 605: Cannot open with file filename The with file does not exist or may be locked. Error 607: No FROM/ROOT files specified You did not specify an object module, or if you are using overlays, the root node did not contain any objects. Error 608: Premature EOF encountered The object module is corrupt. Try recompiling the source file. Error 609: Error seeking in file filename The object module is corrupt. Try recompiling the source file. Error 610: module-name has no parent in overlay tree The with file specifies an overlay with no parent node. Error 611: Reloc found with odd address for symbol symbol- name, file filename The linker has found a relocation record with an odd address. This message can only be generated if your program is written in assembler and is usually caused by placing an odd length character string in the code section. Error 612: MERGED Data relocation to non-code section in Overlay Node Reference at offset hex-address in module-name, To Unit module-name The linker found a relocation from the near data section, which is placed in the root node, to the data section of an overlay node. This type of relocation is illegal. Error and Warning Messages 263 Error 613: MERGED Data relocation to static function is not resolvable by Overlay Manager. Reference at offset hex-address in filename , To Unit filename The overlay manager cannot resolve an indirect function call from the root node to a static function in a overlay node. To correct the problem, remove the static keyword from the function declaration. Error 614: More than one MERGED data section found Only one near data section is allowed. This error occurs only when using slink to strip debug information from an executable generated by a third party linker. If you get this message, do not use slink to strip debug information from this executable. Error 615: Code hunk named __MERGED slink merges all hunks with the name __MERGED and performs relocations to this hunk relative to register A4. Do not name the code hunk __MERGED . Error 616: ALVs were generated You have linked with the noalvs linker option, but the linker could not resolve all relocations without generating ALV instructions. Either the total code size is greater than 32K, or there are multiple code hunks. The executable will run, but the code section is not totally PC- relative. Error 617: MERGED data greater than 64K If your program does not generate any additional messages, then the program will still run. However, a 16-bit data relocation record may not be able to reach its target, and if this happens, slink will generate an error. Error 618: Multiple OVERLAY usage-previous occurrences were ignored You can only specify one overlay manager. Error 619: Ignoring null OVERLAY list You did not specify any files in the overlay list. 264 Appendix 2 Error 620: Missing '#' at end of OVERLAY list Enter a pound sign (#) at the end of the overlay tree. For more information on creating overlay trees, see Chapter 8, "Compiling and Linking Your Program." Error 621: Conflicting integer sizes found Some modules were compiled using short integers and some were compiled using long integers. You cannot mix integer sizes in an executable. Alternatively, you may have linked in the wrong version of the library. Error 622: Conflicting math types found You may have compiled the various object modules with conflicting math options. All object modules must be compiled with the same math library. Alternatively, you may have linked in the wrong math library. Error 623: Regargs function function called through overlay manager. Parameters passed in registers to this function will be destroyed. The regargs function passes parameters in scratch registers, but the overlay manager does not preserve scratch registers. You cannot call a regargs function across an overlay node. Error 624: Absolute reference to symbol module: file filename If you reference far data in a module linked with cres.o or when you are generating a shared library, your program may function improperly unless the data are read-only. slink cannot determine if the reference is read-only, so it generates this warning. Error 625: Proper math library has not been included You have not linked in the math library that is needed for the current math options. Error 626: Libcode used on module module You have compiled the module with the libcode compiler option that was used on the module, but the module is being linked into an executable. Use the libcode option for generating shared libraries only. Error 627: Near references found in executable that has a module compiled with FARONLY option You cannot mix modules compiled with data= faronly and modules that refer to near data. Error and Warning Messages 265 Enabling Suppressed Messages Many messages are suppressed by default. The strict and ansi compiler options turn on some of these messages, but you must use the warn option to enable the remaining messages. The ansi option enables the following messages: 18 51 70 108 111 137 162 176 180 213 The strict option enables the following messages: 18 70 111 137 159 163 176 179 187 220 51 108 120 149 162 164 178 180 213 The following messages can be enabled only with the warn option: 22 148 156 165 190 195 212 The following table lists each message that is suppressed by default and indicates which compiler options enable the message. Number Message Text ansi strict warn 18 sizeof operator used in preprocessor X X X condition 22 structure used as function argument X 51 C++ comment detected X X X 70 unrecognized escape sequence X X X 108 zero-length arrays are not an ansi feature X X X 111 non-portable enum type specified X X X 120 Integral type mismatch: possible portability X X problem Expecting "type1", found "type2" 137 ansi limits #line numbers to between 1 and X X X 32767 (cont~nued) 266 Appendix 2 Number Message Text ansi strict warn 148 use of incomplete struct/union/enum tag X "name" See line number file filename 149 incomplete struct/union/enum tag in prototype X X scope "name" 156 operation/comparison of pointer to "int" and X pointer to "type" 159 use of unary minus on unsigned value X X 162 non-ansi use of ellipsis punctuator X X X 163 initialization of auto struct, union, or X X array 164 & applied to array X X 165 use of narrow type in prototype X 176 implicitly promoted formal "name" conflicts X X X with prototype See line number file "filename" 178 indirect call without indirection operator X X 179 narrow type used in old-style definition X X 180 no space between macro name and its X X X replacement list 187 negative value assigned to unsigned type X X 190 #include ignored because header already X included See line number file "filename " 195 nested comment detected X 212 item "name" already declared X See line number file "filename" 213 empty argument to preprocessor macro X X X 220 old-fashioned assignment operator X X 267 Appendix 3 Implementation-Defined Behavior 267 Introduction 268 F.3.1 Translation 268 F.3.2 Environment 268 F.3.3 Identifiers 269 F.3.4 Characters 269 F.3.5 Integers 270 F.3.6 Floating-Point 270 F.3.7 Arrays and Pointers 271 F.3.8 Registers 271 F.3.9 Structures, Unions, Enumerations, and Bit-Fields 272 F.3.10 Qualifiers 272 F.3.11 Declarators 272 F.3.12 Statements 272 F.3.13 Preprocessing Directives 273 F.3.14 Library Functions 278 F.3.15 Locale-Specific Behavior Introduction The American National Standard for Information Systems--Programming Language-C (ANSI Standard X3J11/90-013) allows an implementation to define its own behavior in certain areas. Implementation-defined behavior is defined by the ANSI Standard as "behavior, for a correct program construct and correct data, that depends on the characteristics of the implementation. . ." (p.3). This appendix describes the SAS/C Compiler behavior for those areas listed in Section F.3, "Implementation-Defined Behavior," of the ANSI Standard. This appendix is organized like Section F.3. 268 Appendix 3 F.3.1 Translation [] Diagnostics consist of a line printed to the standard output stream containing the following elements: filename line class number: text where: filename is the name of the file that caused the diagnostic line is the number of the line that caused the diagnostic class is either Error or Warning number is an integer identifying the diagnostic text is the diagnostic text. Some diagnostics contain additional information in a second line. If present, this second line is indented to the same position as the text portion of the first line. F.3.2 Environment [] The compiler conforms to the ANSI Standard for a hosted environment as documented in Section 2.1.2.2 of the ANSI Standard, plus the extension of accepting a WBStartup structure as described under main in the SAS/C Development System Library Reference, Version 6.0. [] The compiler recognizes the streams stdin, stdout, and stderr as interactive devices. F.3.3 Identifiers [] By default, the number of significant characters for identifiers without external linkage is 31. However, this number can be changed to any value up to 255 with the idlen compiler option. [] The number of significant characters for identifiers with external linkage is the same as the number for identifiers without external linkage. [] Case distinctions are significant in identifiers with and without external linkage. Implementation Defined Behavior 269 F.3.4 Characters [] The source and execution character sets consist of the characters required by the ANSI Standard. In addition, national characters (characters with accents) are accepted as valid alphabetic characters unless the ansi compiler option is used. See The AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991) for a complete definition of the Amiga character set. [] No shift states are used for encoding multibyte characters. [] Each character in the execution character set consists of 8 bits. [] The source character set maps 1-to-1 to the execution character set. [] All wide character constants map directly into the execution character set. Thus, all wide character constants have the same value as their corresponding character in the execution character set. [] The C locale is used as the current locale. [] A plain char item is by default signed, but this default can be changed to unsigned with the unschar compiler option. F.3.5 Integers [] Integers are represented by two's-complement numbers. The range of possible values are specified in the header file limits .h and in Chapter 12, "How Does the Compiler Work?" The most-significant bit in the representation of signed integers is the sign bit and determines whether the number is positive or negative. [] When an integer is converted to a shorter signed integer, the high- order bytes are discarded. The bit pattern of the remaining bytes is unchanged. The bit pattern of an unsigned number is not changed when it is converted to a signed integer of equal length. [] The following list covers the results of bitwise operations on signed integers: ~ (bitwise NOT) The bits are inverted; that is, 1 bits are set to 0, 0 bits are set to 1. >> (shift right) The bits are shifted to the right. The sign bit (uppermost bit) is used to fill the vacated bit positions on the left. << (shift left) The bits are shifted to the left. The vacated bit positions on the right are filled with zeroes. & (bitwise AND) If the corresponding bits in both operands are 1, then the corresponding bit in the result is set to 1; otherwise, it is set to 0. 270 Appendix 3 | (bitwise OR) If either of the corresponding bits in the operands are 1, then the corresponding bit in the result is set to 1; otherwise, it is set to 0. ^ (bitwise XOR) If the corresponding bits in the operands are not alike, then the corresponding bit in the result is set to 1; otherwise, it is set to 0. [] In integer division, the remainder is either 0 or has the same sign as the dividend. [] In a right shift of a negative-valued signed integral type, the sign bit is used to fill the vacated bit positions on the left. That is, the result retains the sign of the left operand. F.3.6 Floating-Point [] Floating-point numbers are represented using the IEEE standard representation, unless the math= ffp option is on. In the latter case, the Motorola Fast Floating Point representation is used. The range of possible values for floating-point numbers is specified in the header file float.h and in Chapter 12, "How Does the Compiler Work?" [] If an integral number is converted to a floating-point number that cannot exactly represent the original value, the number is rounded for all math options except math=coprocessor. For math=coprocessor, the number is truncated. You can change the behavior for the math=coprocessor option by modifying the source code to the __fpinit.c function, located in sc:source/_fpinit. However, choosing another rounding mode affects the conversion from floating-point to integer such that the conversion does not adhere to the ANSI Standard. Specifically, the following statement might assign the integer value 6 to i if you specify math=coprocessor, and the coprocessor's rounding mode is not set to truncate: int i = (int)5.5; [] Conversions from double to float round or truncate in the same manner as conversions from integral types to floating-point types. F.3.7 Arrays and Pointers [] The type of integer required to hold the maximum size of an array is unsigned int. [] When a pointer is converted to integer, the resulting bit pattern is as if an object of type unsigned long with the same bit pattern as the pointer had been converted to the integer type. Implementation Defined Behavior 271 [] When an integer is converted to a pointer, the resulting bit pattern is the same as if the integer had been converted to an unsigned long. F.3.8 Registers [] Under normal circumstances, there can be up to 4 integer register variables, 3 pointer register variables, and 5 floating point register variables. Using the cover compiler option, the stackext compiler option, the __stackext keyword, or __aligned keyword on a function definition costs one pointer register variable. Using the data=faronly compiler option adds an additional pointer register variable. The reg i s ter keyword is ignored when the global optimizer is used because registers are allocated to variables by the global optimization phase. If you specify the autoreg option, the code generator selects additional register variables for you if registers are available after assigning your choices to registers. F.3.9 Structures, Unions, Enumerations, and Bit-Fields [] If a member of a union is accessed using a member of a different type, the result is undefined. If optimization is used, the compiler may attempt to keep the value stored in one member of a union in a register, and a subsequent access to a different member may get an old value. [] Structure members of type char can appear at any byte offset. Structure members of other simple types must be aligned on an even byte boundary, and padding is inserted if necessary. Any structure or union member declared with the __aligned keyword is aligned on a four-byte boundary, relative to the start of the structure or union, with padding inserted as necessary. Substructures and subunions have the same alignment requirements as their most restrictive members. Structures and unions are padded at the end to the boundary of their most restrictive member. For more information on structure padding, see Chapter 13, "Writing Portable Code." [] int bitfields are treated as unsigned int bitfields. [] The order of allocation of bitfields for an int is from left to right. Bitfields never cross storage unit boundaries. [] The values of an enumeration type are normally of type int. However, the SAS/C Compiler allows the declaration of char enum, short enum, and long enum types. Enumeration types so declared are of the specified type. For more information on using enumerated types, 272 Appendix 3 see Chapter 11, "Using Amiga Specific Features of the SAS/C Language." F.3.10 Qualiflers [] Any reference to an object whose type is qualified by the keyword volatile is considered an access to that object. F.3.11 Declarators [] There is no limit on the number of declarators that can modify an arithmetic, structure, or union type. F.3.12 Statements [] There is no limit to the number of case values in a switch statement. F.3.13 Preprocessing Directives [] The value of a single-character constant in a constant expression that controls conditional inclusion matches the value of the same character constant in the execution character set. Such a character can have a negative value unless the unschar compiler option is active. [] The compiler defines a search path for # include files that are included with angle brackets (<>) around their names. This path is defined as follows: 1. directories specified with the includedirectory compiler option 2. the logical assignment INCLUDE:. [] The compiler uses a slightly different search path for #include files that are included with double quotes ("") around their names. This path is defined as follows: 1. the current directory 2. the directory of the file containing the #include statement 3. directories specified with the includedirectory compiler option 4. the logical assignment INCLUDE:. [] Source file character sequences are not mapped. The string between the angle brackets (<>) or double quotes ("") is passed to the file system. Implementation Defined Behavior 273 [] The behavior of the libcall, syscall, and tagcall #pragma directives is described in the SAS/C Development System Library Reference. The behavior of the msg and flibcall #pragma directives is described in Chapter 11, "Using Amiga Specific Features of the SAS/C Language." [] The definitions for the __DATE __and __TIME __preprocessor macros contain the date and time as specified by the DateStamp AmigaDOS function. This function always returns a value, so the date and time are always available. F.3.14 Library Functions [] The NULL pointer constant to which the macro NULL expands is OL. [] The diagnostic printed by the assert function is of the form: Assertion (condition) failed in file filename at line number where: condition is the condition passed to the assert macro filename is the current value of __FILE__ number is the current value of__ LINE__. The assert function calls abort after printing the above line. For more information, refer to the description of the assert function in the SAS/C Development System Library Reference. [] The sets of characters tested for by the isalnum, isalpha, iscntrl, islower, isprint, and isupper functions is defined by the entries in the external array __ctype. The following table lists the hexadecimal values for each of the characters tested for by these functions. Function Name Character Type Hexadecimal Values isalnum alphabetic or 0x30 to 0x39, 0x41 to 0x5a, numeric 0x61 to 0x7a isalpha alphabetic 0x41 to 0x5a, 0x61 to 0x7a iscntrl control 0x00 to 0x1f, 0x7f (continued) 274 Appendix 3 Function Name Character Type Hexadecimal Values islower lowercase 0x61 to 0x7a isprint printable 0x20 to 0x7e isupper uppercase 0x41 to 0x5a [] The mathematics functions return zero on domain errors. [] On underflow range errors, the mathematics functions set the integer expression errno to the macro ERANGE. [] Zero is returned when the fmod function has a second argument of zero. [] The set of signals for the signal function are the minimum set defined by the ANSI Standard: SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, and SIGTERM. [] Refer to the description of the signal function in the SAS/C Development System Library Reference for the semantics of the signals. [] By default, the SIGINT signal results in calling the _ CXBRK function, which terminates the program. Also by default, the SIGFPE signal results in calling the _ CXFPE function, which sets errno and returns to the caller causing the exception. By default, all other signals are ignored. [] The default handling is reset if the SIGILL signal is received by a handler specified to the signal function. [] The last line of a text stream does not require a terminating newline character. No newline character is generated if one is not explicitly written. [] Space characters that are written out to a text stream immediately before a newline character appear when read in. [] The implementation does not append any NULL characters to data written to a binary stream. [] The file position indicator of an append mode stream is initially positioned at the beginning of a file. [] A write on a text stream does not cause the associated file to be truncated beyond that point (see Section 4.9.3 of the ANSI Standard). However, some of the modes truncate the file upon open. The following table lists whether a file is truncated after a write. Implementation Defined Behavior 275 File Mode Truncated? Comments "r" or "ra" N/A No writes allowed. "w" or "wa" No The file is truncated at open time only. "a" or "aa" No All data are written after EOF. "r+" or "ra+" No "w+" or "wa+" No "a+" or "aa+" No All data are written after EOF. "rb" N/A No writes allowed. "wb" No The file is truncated at open time only. "ab" No All data are written after EOF. " rb+ " No "wb+ " No "ab+" No All data are written after EOF. [] A call to the fopen function opens a buffered I/O stream. For writes, data are stored into the buffer until it is full, and then the data are written out. A call to the fflush function forces a write of any buffered data. You can use the library routines setbuf and setvbuf to change between buffered, unbuffered, and line buffered modes. For more information, refer to the description of these functions in the SAS/C Development System Librar,v Reference. [] A zero-length file can be created by either creating a file and not writing anything to it or by truncating an existing file. [] In general, a file can be opened multiple times as long as a previous call to open the file did not physically create the file. However, some devices or file-handlers may prevent multiple opens. Refer to the documentation for the device or file handler that you are using. [] A file cannot be deleted if there are any outstanding locks or file handles on the file. In this case, the remove function sets errno and OSERR and returns a nonzero value. [] The output for %p conversion specification for the fprintf function is the pointer's value in hexadecimal. 276 Appendix 3 [] The input for the %p conversion specification for the fscanf function is a hexadecimal pointer, optionally preceded by 0x or 0x. [] A minus (--) character that is neither the first nor the last character in the scanlist for a % [ conversion specification in the fscanf function is treated as a subrange specifier. That is, %[a-d] is equivalent to %[abcd]. [] The functions fgetpos and ftell set the variable errno to the value of EBADF for a bad file handle. Otherwise, errno is set as described in the SAS/C Development System Library Reference for the function lseek. [] The perror function generates the following messages: errno Value Description __________________________________ 0 Unknown error code EPERM User is not owner ENOENT No such file or directory ESRCH No such process EINTR Interrupted system call EIO I/O error ENXIO No such device or address E2BIG Arg list is too long ENOEXEC Exec format error EBADF Bad file number ECHILD No child process EAGAIN No more processes allowed ENOMEM No memory available EACCES Access denied (continued) Implementation Defined Behavior 277 errno Value Description ___________________________ EFAULT Bad address ENOTBLK Bulk device required EBUSY Resource is busy EEXIST File already exists EXDEV Cross-device link ENODEV No such device ENOTDIR Not a directory EISDIR Is a directory EINVAL Invalid argument ENFILE No more files (units) allowed EMFILE No more files (units) allowed for this process ENOTTY Not a terminal ETXTBSY Text file is busy EFBIG File is too large ENOSPC No space left ESPIPE Seek issued to pipe EROFS Read-only file system EMLINK Too many links EPIPE Broken pipe EDOM Math function argument error ERANGE Math function result is out of range [] If the functions calloc, malloc, or realloc are passed a size of zero, the allocation fails, and the function returns a NULL pointer. errno is set to the value of EINVAL. [] The abort function closes all open and temporary level 2 I/O files. The value passed to the exit function is the value that is passed back to the system. For EXIT _ SUCCESS, the value returned is 0. For EXIT _ FAILURE, the value returned is 20. 278 Appendix 3 [] The list of environment names are in the system file-handler ENV:. Environment name values are modified through the putenv function. [] The contents and mode of execution of the string passed to the AmigaDOS system by the system function is as follows: [] Under AmigaDOS Version 1.3, the AmigaDOS function Execute is called. [] Under AmigaDOS Version 2.0 or higher, the AmigaDOS function System is called. [] The system function returns the value returned from the AmigaDOS Execute or System function. If the command processor cannot be invoked, system returns a -1. [] The strerror function returns the same error messages as the perror function. The messages returned by the perror function are listed above. [] The default time zone is CST6, and the default for Daylight Savings Time is 0. [] The era for the clock function is based on the first call to the clock function. The first call returns a value of zero, and subsequent calls measure the processor time from that starting point. For more information, refer to the description of the clock function in the SAS/C Development System Library Reference. F.3.15 Locale-Specific Behavior [] The execution character set contains all ASCII characters in all locales. [] The direction of printing is from left to right. [] The period (.) is the decimal-point character. [] Refer to the description of the i s ..functions in the SAS/C Development System Library Reference for information on the implementation-defined aspects of character-testing and case-mapping functions. [] The collation sequence for ASCII characters is used as the collation sequence of the execution character set. [] The SAS/C Development System uses the normal U.S. time and date conventions for the C locale. Implementation Defined Behavior 279 Type Values ____________________________________________ Weekday name Sun Mon Tue Wed Thu Fri Sat Month name Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Date/Time DDD MMM dd hh:mn:ss YYYY format Tue Jun 16 14:12:22 1992 280 281 Appendix 4 Converting From Aztec C Options to SAS/C Options Table A4.1 lists each of the Aztec 5.0 options and their equivalent SAS/C options (if available). Some Aztec C options do not have equivalent SAS/C options. Also, for some SAS/C options listed in this table, you must specify additional options before the ones listed in this table will take effect. For example, you must specify the genprotos option before the genprotoparms option will take effect. Table A4.1 Converting From Aztec C Options to SAS/C Options Aztec C Option SAS/C Option Comments __________________________________________________________________________________________ -3 no equivalent -5 no equivalent -a disasm=filename These options generate assembly output. noobjname -at disasm=filename The debug option adds C source to the debug = line assembly output. noobj name -bd stackcheck stackcheck is the default setting. You can turn off stack checking with nostackcheck. -bs debug=level You can specify one of five levels of debug information. -c2 cpu=68020 -d define symbol=value -fa math=ieee You must also link with the appropriate math library. -ff math=ffp You must also link with the appropriate math library. -fm math=standard You must also link with the appropriate math library. (continued) 282 Appendix 4 TableA4.1 (continued) Aztec C Option SAS/C Option Comments ____________________________________________________________________________________________ -f8 math=68881 You must also link with the appropriate math library. -hi gst=gst-filename -ho makegst=gst-filename -i includedirectory=filename -k no equivalent -ma This option is on by default. -mb no equivalent -mc code=far -md data=far -me no equivalent -mm stringmerge stringmerge forces the compiler to have only one copy of identical strings and places these strings in the code section. stringmerge also places data declared static const into the code section. -ms nostringmerge -o objectname=filename -pa ansi trigraph -pb Bitfields are unsigned by default. Use the signed keyword to declare a signed bitfield. -pc ignore= 132 This option suppresses the warning for tokens after #endif. -pe no equivalent -pl noshortint -po oldpp -pp unsignedchar (continued) Converting From Aztec C Options to SAS/C Options 283 TableA4.1 (continued) Aztec C Option SAS/C Option Comments _____________________________________________________________________________________________ -ps shortintegers -pt trigraph -pu no equivalent -qa genprotoparms -qf errorrexx -qp nogenprotostatics -qq noverbose noversion -qs nogenprotoexterns -qv no equivalent -r4 data = faronly This option uses register A4 for register variables. Do not use the __near or __chip keywords if you use this option. -sa This option is always on. -sb no equivalent Include string.h in your source code. -sf optimize -sm no equivalent Include the appropriate header file in your source code. -sn This option is always on. -so optimize -sp The cleanup overhead reduction enhancement is always on unless you specify debug=sf or debug=ff. -sr optimize -ss stringmerge -su This option is the default setting. You can disable this option with the noautoreg option. (continued) 284 Appendix 4 Table A4. 1 (continued) Aztec C Option SAS/C Option Comments __________________________________________________________________________________________ -wa This option is the default setting. You can disable this option with the ignore=88 option. -wd -we error=all This option turns all warnings into errors. To make a specific message n an error message, specify error=n. -wl This option is the default setting. -wn ignore=225 -wo This option is the default setting. -wp This option is the default setting. You can disable this option with the ignore= 100 option. -wq no equivalent Use command line redirection. -wr This option is the default setting. You can disable this option with the nowarnvoidreturn or ignore=85 option. -ws ignore=all This option turns off all warnings. -wu This option is the default setting. You can disable this option with the ignore=93 option. -ww maxerr=n The number n specifies the new error limit. 285 Appendix 5 Converting from Version 5 to Version 6 285 Introduction 285 Upgrading from Previous Versions 286 Converting Compiler Options 294 Specifying Version 6 Libraries Introduction This appendix lists the Version 6 options and libraries that are equivalent to the Version 5 options and libraries. Upgrading from Previous Versions You should install Version 6 in a separate location from previous versions of the compiler. Modify your startup sequence files to either remove the LC: directory from your path or ensure that the directory SC: C is on your search path before LC: . In addition, make sure that include: and lib: get assigned to the correct include and link library directories for Version 6. The compiler for Version 6 does not use the QUAD: device used by previous versions. In general, it is a good idea to recompile all your code when you convert to Version 6. However, because the Version 6 libraries are ANSI- compliant, your old programs may not compile or may generate many warning messages. Appendix 1, "Solving Common Problems," provides solutions to some of the problems you may encounter in converting to Version 6. You may want to use the sc5 command to convert older, seldom-used projects. The sc5 command accepts Version 5 options and reads default options from the file sascopts. However, it is recommended that you become familiar with and begin using Version 6 as soon as possible. You can use the lctosc conversion utility to convert your Version 5 sascopts file to a Version 6 scoptions file and to determine quickly the Version 6 equivalent of a Version 5 option. The lctosc utility reads the sascopts file in the current directory, reads any command-line 286 Appendix 5 options, converts the options to Version 6 options, and writes the results to standard output. For example, to convert the sascopts file in the current directory to a Version 6 scoptions file, enter the following command at the Shell prompt: lctosc >scoptions To determine the Version 6 equivalent of the Version 5 option -cs, enter the following command: lctosc -cs For code compiled with previous versions of the compiler, the new version of CodeProbe can read the line number information but cannot read the symbol information from the executables. Recompile your code with the Version 6 compiler to produce usable debugging information for symbols. If you get unresolved symbols when you link your application, you may be referring to symbols whose name has changed so as to make the compiler conform to the ANSI Standard. In this case, look up the symbol name in the SAS/C Development System Library Reference, Version 6.0 to determine the new name, and change any references to the symbol name in your code to the new name. Alternatively, you can choose to use the define linker option to force all references to the old name to refer instead to the new name. Converting Compiler Options Table A5.1 lists each of the Version 5 options and the equivalent Version 6 option (if available). Some Version 5 options do not have equivalent Version 6 options. Also, for some Version 6 options listed in this table, you must specify additional options before the ones listed in this table will take effect. For example, you must specify the link option before any of the math=type options will take effect, and you must specify the genprotos option before the genprotoparms option will take effect. Converting from Version 5 to Version 6 287 Table A5.1 Converting Version 5 Options to Version 6 Options Version 5 Option Version 6 Option Description ____________________________________________________________________________________ -+ verbose Display commands as executed -. noversion Suppress execution message -ab bss=chip Force all uninitialized data (BSS) to chip memory -ac code=chip Force all code to chip memory -ad data=chip Force all initialized data to chip memory -b data=near Base relative data (16-bit offsets) -b0 data=far Non-base relative data (32-bit offsets) -b1 data=near Base relative data (same as -b) -ba data=auto Automatic non-base relative on data overflow -c+ idlen=100 Allow longer identifiers for C++ -ca ansi Maximize ANSI compatibility -cc commentnest Allow nested comments -cd ignore=77 Allow $ in identifiers -ce noerrorsource Suppress source line printing for errors -cf Require function prototypes [1] -ci nomultipleincludes Suppress multiple includes of same file -ck ansi Suppress non-ANSI keywords (chip, far, near) -c1 Use __aligned keyword [2] Align all externs on longword boundary -cm multiplecharconstants Allow multiple character constants -co oldpp Enable old style preprocessor -cp Allow #if to span files -cq structequivalence Allow passing of equivalent structure silently (continued) [1]sc5 did not require function prototypes. By default, Version 6 requires function prototypes. To suppress the Version 6 messages dealing with prototypes, specify ignore=100+161+154. [2]Use the __aligned keyword to force individual objects to longword boundaries. 288 Appendix 5 TableA5.1 (continued) Version 5 Option Version 6 Option Description ______________________________________________________________________________________________ -cr Disallow __asm keyword on function definitions -cs stringmerge Create only one copy of identical strings -ct Obsolete - does nothing -cu unsignedchar Force all char declarations to unsigned char -cw nowarnvoidreturn Shut off warning for return without a value -cx noexternaldefs Treat all global declarations as externs -C onerror = continue Continue on error -d debug=line Enable debugging -d0 nodebug Disable debugging -d1 debug=line Enable debugging - dump line table -d2 debug=symbol Generate symbol information -d3 debug=symbolf lush Generate symbol information and flush registers at every line -d4 debug=full Generate full symbol information -d5 debug= fullflush Generate full symbol information and flush registers at line -dsym=val define sym=val Define preprocessor symbol to a value -E errorrexx Invoke Editor on error -Efilename Invoke Editor on error, filename is an errorfile name -e Enable Asian character set (default is Japanese) -e0 Enable Japanese character set (same as -e) -e1 Enable Chinese character set -e2 Enable Korean character set -f math=ffp Use Motorola FFP (forces -fs) -f8 math=68881 Generate code for Motorola 68881 (continued) Converting from Version 5 to Version 6 Z89 TableA5.I (continued) Version 5 Option Version 6 Option DescFiption _____________________________________________________________________________________________ -fd precision=double Use double precision for both float and double -ff math=ffp UseMotorolaFFP -fi math=ieee Generate code for IEEE libraries -f1 math= standard Use standard SAS/C floating point library -fm precision=mixed Use single precision for float, double for double -fs Use single precision for both float and double -gc xref system Cross-reference compiler-provided files -gd xrefmacros Cross-reference defined symbols -ge List excluded lines -gh listheaders List header files -gi listsystem List included files -gm listmacros List macro expansions -gn listnarrow Print narrow lines -go errorlisting Put errors and warnings to both stderr and errorconsole listing file -gs list List source -gx xreference Produce cross reference listing -g=filename listfile=filename Generate listing file with name filename -Hname gst=gst-filename Read in precompiled header file name -hb bss=fast Force all uninitialized data (BSS) to fast RAM -hc code=fast Force all code to fast RAM -hd data=fast Force all initialized data to fast RAM -ix incdirectory=filename Specify directory to search for includes -jn ignore=n Disable message number n (conhnued) 290 Appendix 5 Table A5.1 (continued) Version 5 Option Version 6 Option Description __________________________________________________________________________________________ -jne error=n Make message number n an error instead of a warning -j*e error =all Turn all warnings into errors -jni ignore=n Disable message number n (same as - jn) -j*i ignore=all Disable all warnings -jnw warn=n Enable message number n as a warning -ja noerrorhighlight Suppress ANSI escape codes from error line output -L+ ob ject=object-file Specify additional linker objects library = link-library -La addsym Add symbol information when linking -Lc smallcode Use small code memory model (16bit jumps) -Ld smalldata Use small data memory model (16-bit data offsets) -Lf math=ffp LinkwithFFPmathlibrary -Lh maphunk Produce linker hunk map -Li stdio Link with _ tinymain instead of _ main -L1 maplib Produce linker library map -Lm math=math-type Link with appropriate math library -Ln stripdebug Suppress debugging information in executables -Lo mapoverlay Produce linker overlay map -Ls mapsym Produce linker symbol map -Lt smallcode Use typical link options (same as -Lc, -Ld, -Lv, smalldata or -Lcdv) verbose -Lv verbose Print verbose linking information -Lx mapxref Produce linker cross-reference (continued) Converting from Version 5 to Version 6 291 TableA5.1 (conhnued) Version 5 Option Version 6 Option Description _______________________________________________________________________________________ -l Use __aligned keyword. [1] Align objects on longword boundaries -M modified Compile only modified source files -m cpu=any Generate code for Motorola 68000 -mO cpu=68000 Generate code for Motorola 68000 (same as -m) -m1 cpu=68010 Generate code for Motorola 68010 -m2 cpu=68020 Generate code for Motorola 68020 -m3 cpu=68030 Generate code for Motorola 68030 -ma cpu=any Generate code for all Motorola processors (same as -m) -mc Disable cleanup overhead reduction enhancement -ml libcode Generate code for resident library use -mp absfuncpointer Generate 32bit references to functions -mr noautoregister Disable automatic registerization -ms optsize Generate code optimized for space optimize -mt opttime Generate code optimized for time optimize -N Disable linking from editor -n identifierlength=8 Retain only 8 characters for identifiers -nn identifier length=n Specify maximum length for identifiers -O optimize Invoke global optimizer -ox objectname=filename Place object file in filename -Px programname=filename Use filename as the name of the final executable module (continued) [1] Use the __aligned keyword to force individual objects to longword boundaries. 292 Appendix 5 TableA5.1 (continued) Version 5 Option Version 6 Option Description _________________________________________________________________________________________ -p preprocessonly Preprocess only -pe nogenprotostatics Generate prototypes for external functions -ph makegst=filename Generate precompiled header file -pi Include identifier names in generated prototypes -pp genprotoparms Generate prototypes with __PARMS for portability -pr genproto Generate prototypes for external and static functions -ps nogenprotoexterns Generate prototypes for static functions only nogenprotodataitems -pt nogenprototypedefs Suppress use of typedefs when generating prototypes -qx Place quad file in location x -qne maxerr=n Quit compilation after n error/warnings -qnw maxwarn=n Quit compilation after n warnings -q maximumwarn= 1 Quit after 1 error or 1 warning (same as maximumerrors=1 -q1e1w) -r code=near Default function calls to near (PC-relative) -r0 code=far Default function calls to far (Absolute) -r1 code=near Default function calls to near (Same as -r) -rr parms=register Pass and receive parameters in registers -rs parms=stack Pass and receive parameters on the stack -rb parms=both Generate code for both register and stack conventions -Rfilename objectlib=filename Place compiled objects into library filename (continued) Converting from Version 5 to Version 6 293 Table A5.1 (conhnued) Version 5 Option Version 6 Option Description _____________________________________________________________________________________________ -s Use default segment names text, data, and udata -sb=name bssname=name Specify a name for uninitialized data (BSS) segment -sc=name codename=name Specify a name for code segment -sd=name dataname=name Specify a name for data segment -t startup= cback Link with cback.o instead of c.o -tb startup=cback Link with cback.o instead of c.o (same as -t) -tc startup= catch Link with catch.o instead of c.o -tcr startup=catchres Link with catchres.o instead of c . o -tr startup=cres Link with cres.o instead of c.o -t=x startup=filename Link with filename instead of c.o -u Undefine all preprocessor symbols -v nostackcheck Disable stack checking code -w shortintegers Default to short integers -x noexternaldefs Treat all global declarations as externals (same as -cx) -y saveds Load A4 with base address at start -znnn ppbuf=nnn Set preprocessor expansion buffer size to nnn 294 Appendix 5 Specifying Version 6 Libraries Table A5.2 lists each of the Version 5 libraries and the equivalent Version 6 library. In Version 6, the standard libraries provide support for registered parameters. To use registered parameters, you must compile with the params=registers option, but you do not need a special library. Table A5.2 Version 5 Library Version 6 Library _____________________________________________ lc.lib sc.lib lcm.lib scm.lib lcmieee.lib scmieee.lib lcmffp.lib scmffp.lib lcmr.lib scm.lib lcms.lib scms.lib lcmsr.lib scms.lib lcm881.lib scm881.lib lcmr881.lib scm881.lib lcnb.lib scnb.lib lcr.lib sc.lib lcs.lib scs.lib lcsnb.lib scsnb.lib lcsr.lib scs.lib 295 Index A __ aligned keyword 155-156 __ asm keyword 157-158 .a filename extension 78 __ chip keyword 156-157 abbreviated menus 50 __ far keyword 156-157 abort function 277 __ Inline keyword 159 absfuncpointer compiler option 85, 177 __ interrupt keyword 157 accelerator keys 50 __ near keyword 156-157 addressing data 176-177 __ regargs keyword 157-158 chip data 176 __ saveds keyword 158-159 modifying access to program code and __ stackext keyword 160-161 data 176-177 __ stdargs keyword 157-158 reentrant and non-reentrant programs amigaguide.se, AREXX macro 69 176 AmigaGuide, invoking 28 addsym linker option 121 ANSI compiler option 85, 181 addsymbols compiler option 85 ANSI Standard __ aligned keyword 155-156 See also implementation defined affecting definitions of functions 155 behavior automatic variable problems 156 See also portable code, v.~riting ensuring stack alignment 156 default argument promotion rules 187 example 156 format for incoming command line 140 pointer register variables 161 ANSI compliant C compilers 182 Alt keys AREXX interface 65-73 equivalence 60 AREXX port 68 independent operation 60 command summary 70-73 Amiga keys commands without keystroke equivalents caution against redefining 60 70-73 Amiga-specific features of SAS/C language communicating with external programs 153-169 68-69 C++ style comments 168 definition 73 comma (,) operator 168 executing a series of editor commands common model external data 168-169 65-68 enumerated types 167 keystroke equivalents for commands equivalent structures 164-166 70-73 implicit structure references 164 AREXX macros managing stack space 160-161 amigaguide.se 69 national characters in variable names assigning to keys 66 168 definition 73 nested comments 168 deletetabs.se 69 #pragma statements 161 163 examples 66-68, 69 sizeof operator 168 findsym.se 69 special keywords 154 159 indent.se 70 unnamed unions 163-164 newline character (\n) 65 zero-length arrays 163-164 provided with the compiler 69-70 296 Index AREXX macros (conhnued) autotermination function 145-147 .se suffix required 65 definition 145 tolower.se 70 example 146 toupper.se 70 level 1 or 21/O functions not used 147 unindent.se 70 order in which modules called 147 argc and argv _STD preceding function name 145 ANSI Standard requirement 140 __dtors array 146, 147 Shell environment 135-136 Autowrap option 61-62 Workbench environment 136 Aztec C options, converting 281-284 arguments raising argument limits 140-141 argumentsize= compiler option 85-86 B See also memorysize= compiler option arrays __BackGroundlO external definition 143 SAS/C Compiler behavior 270-271 backslash (\) asctime function 200-201 preceding comment character 62 .asm filename extension 78 _Backstdout external definition __asm keyword AmigaDOS functions requirements 143 affecting caller and callee 155 definition 143 Amiga-specific features 157-158 NULL file handle 143 Asm modes 61-62 printing messages in the Shell 143 assembler= compiler option 78, 86 backup copies of installation diskettes 3 assert function 273 Backup File Mode option, Options pull down assign statements, adding to startup file 10 menu 63 asterisk (-) backward searching 42 Asm mode 62 batch compiler option 86 indicating depth of overlay tree 129 batch linker option 121 indirection operator 155 Beginning option at sign (@) Block pull down menu 53 preceding linker symbols 122, 158 Beginning option, Block pull down menu /AUTO keyword 138 51 Auto Indent Mode, Options pull down menu bitfields 62-63 SAS/C Compiler behavior 271 autoinitialization function 145-147 bitwise operations 269-270 definition 145 BIX (Byte Information Exchange) 31 example 146 block operations 43-44, 53 level 1 or 2 I/O functions not used 147 marking blocks 43 library bases automatically initialized unmarking blocks 44 148-149 Block pull down menu order in which modules called 147 Beginning 51, 53 _STI preceding function name 145 Copy 53 __ctors array 146, 147 Delete 52, 53 automatic storage class 180 End 51, 53 automatic variables Move 53 stack alignment problems 156 Print 53 _autoopenfail function Read 53 calling when autoimtialized libraries Write 53 cannot open 150-151 braces ({ }) source code 151 Auto-lndent Mode 62-63 autoregister compiler option 86, 180, 271 bssmemory= compiler option 86, 177 Index 297 bssname= compiler opvion 87 chip data bufsize linker option 121 reentrant and non-reentrant programs Build icon 176 compiling and linking programs 18-19 chip hunk 172 definition 14 __chip keyword 156-157 declaring data items 176 overriding data=auto compiler option C 90 purpose and use 156-157 c directory 6 chip linker option 121 .c filename extension 78 chip memory 157 c.o startup module clock function 278 default module 142 /CLOSE keyword 138 definition 140 Close Window option C+ + style comments 168 Project pull down menu 47 calloc function 141, 277 Windows pull-down menu 54 Case Sensitive Characters option, Options code= compiler option 87, 177 pull-down menu 63-64 code hunk 172 case sensitive searches 42 codememory= compiler option 87, 177 casting results of short integers 179 codename= compiler option 87 catch.o startup module CodeProbe creating snapshot files 142 See debugging programs definition 140 colon (:) catchres.o startup module Asm mode 62 debugging residentable programs 144 colors, changing 54 definition 140 Column Display option, Options pull down saveds compiler option and __saveds menu 63 keyword not allowed 159 comma (,) snapshot files 142, 144 separating filenames for sc command 78 cback.o startup module comma (,) operator in preprocessor char *__procname external definition directives 168 142 commentnest compiler option 87-88, 168 creating detachable programs 142-143 comments definition 140 C++ stylecomments 168 extern BPTR _ Backstdout external comment characters, Asm mode 62 definition 143 comment start sequence (/') 168 long _ BackGroundlO external nested comments 168 definition 143 nested comments not allowed by ANSI long __priority external definition 142 168 long _stack external definition 142 slashes (//) defining comment blocks 168 uses 142 common compiler option 88, 169 char *__procname external definition 142 common model external data 168-169 character constants 104 compiler options 79-119 character strings, replacing See also compiler options, setting See replacing character strings abbreviations 80 character strings, searching absfuncpointer 85, 177 See searching for character strings addsymbols 85 characters ANSI 85, 181 locale specific behavior 278-279 argumentsize= 85-86 SAS/C Compiler behavior 268 assembler= 78, 86 298 Index compiler options (continued) genprototypedefs 95 autoregister 86, 180, 271 globalsymboltable= 96 batch 86 GSTimmediate 96 bssmemory= 86, 177 icons 96-97 bssname= 87 identifierlength= 97 case-insensitivity 80 ignore= 97 code= 87, 177 includedirectory= 97 codememory= 87, 177 keepline 97 codename= 87 keyword options 79 commentnest 87-88, 168 libcode 98, 159 common 88, 169 library= 78, 98 constlibbase 88 link 16, 17, 24, 98 converting from Aztec C options linkeroptions= 98-99, 120 281-284 list 99 converting Version 5 options to Version 6 listfile= 99 286-293 listheaders 99 coverage 88-89, 271 listinclude 99-100 CPU= 89 listmacros 100 csource= 78 listnarrow 100 data= 89-90, 132, 157, 177 listsystem 100 data=auto 90 makeglobalsymboltable= 100 data=far 89, 182 map 100 data=faronly 90, 161, 182 mapfile= 100 datamem= chip 172 maphunk 101 datamemory= 90, 177 maplib 101 dataname= 91 mapoverlay 101 data=near 89, 172 mapsymbols 101 debug= 91, 173 mapxreference 101 debug=full 91 math= 102 debug = fullflush 91 math = coprocessor 2 70 debug = line 91 math = ffp 2 70 debug=symbol 91 math=ieee 270 debug=symbolflush 16, 17, 91 math=standard 16, 17 define= 92 maximumerrors= 102 disassemble= 92 maximumwarnings= 102 error= 92 memorysize= 103 errorconsole 92 modified 104 errorhighlight 93 multiplecharacterconstants 104-105 errorlist 93 multipleincludes 105 errorrexx 16, 17, 93 noautoreg 180 errorsource 93 object= 78, 105 externaldefs 93 objectlibrary= 106 findsymbol= 93 objectname= 106 from 94 oldpreprocessor 106-107 genprotodataitems 94 onerror= 107-108 genprotoexterns 94 optimize 108 genprotofile= 94 optimizealias 108 genprotoparameters 94 optimizercomplexity= 108 genprotos 94-95 optimizerdepth= 109 genprotostatistics 9S optimizerglobal 109 Index 299 optimizerinline 109 xreferenceheaders 118 optimizerinlocal 109 xreferencesystem 119 optimizerloop 109 compiler options, setting optimizerpeephole 109 gadgets for selecting options 17 optimizerrecurdepth= 110 saving settings 17 optimizersize 110 scopts screens 23 optimizertime 110 scopts utility 16-18 overriding settings in scoptions file 79 Shell method 23 parameters= 110-111 specifying from screen editor (se) 26 parameters=both 202 specifying on command line 23 parameters=register 202 Workbench method 16 18 precision= 111 compiling programs 77 78, 171-173 preprocessor symbols defined 120 See also compiler options preprocessorbuffer= 111 See also sc command preprocessoronly 111-112 Build icon 18-19 programname= 112 hunks 171-173 resetoptions 79, 112 numbered compiler messages 206-257 SAS/C Compiler Options Index screen portability considerations 181-182 17 sc command 24, 77-78 saveds 112, 144 screen editor (se) 48 scoptions file 79 Shell method 22-24 shortintegers 112, 178, 179, 183 solving problems 195-197 smallcode 113, 132, 177 unnumbered compiler messages 204-205 smalldata 113, 132, 177 Workbench method 18-19 solving problems 196 CON: keywords 138 sourceis= 113 Configuration Window, screen editor (se) specifying 79-80 57-64 stackcheck 113, 160, 161 Asm modes 61-62 stackextend 113, 160, 161 AutolndentModeoption 62-63 standardio 114 Autowrap option 62 startup= 114 Backup File Mode option 63 strict 114, 181-182, 183 Case Sensitive Characters option 63-64 stringconst 114 Column Display option 63 stringmerge 114-115, 132, 177, 180 displaying 57-58 stripdebug 116 illustration 58 structureequivalence 116, 164, 275 Input processing option 61-62 summary of options 80-84 key definitions, displaying 59 60 switch options 79 key definitions, setting 60-61 to= 116 Keys 14 pull down menu 58 trigraph 116 No processing option 61-62 underscore 116 Options pull down menu 58 unschar 272 Project pull-down menu 58 unsignedchar 116, 177 Prompt Before Undo option 63 utilitylibrary 117 reusing saved settings 64 verbose 117, 173 saving new settings 64 version 117 Searches Method option 41, 63 warn= 117-118, 183, 265 Tab Expansion Method option 62 warnvoidreturn 118 tab stops, setting 61 with= 118 console window 138 xreference 118 const keyword problems 196-197 300 Index constlibbase compiler option 88 purpose and use 89-90 control characters, entering 46 using in overlays 132 Control-\ escape character 46 data storage classes 179-180 conversion of data types 178-179 data types and sizes 177-179 Convert Macro to Key option, Project pull- casting results of short integers 179 down menu 55 conversion 178-179 converting compiler options effect of shortint option 178, 179 Aztec C options 281 284 narrow types in pre ANSI function Version 5 options to Version 6 286-293 declarations 187-188 converting from Version 5 to Version 6 pointer length 178 285-294 portability considerations 183 compilation errors 195-196 signed and unsigned objects 177 compiler option conversion 286-293 sizes and values 177-178 installing Version 6 285 widest operand 178 recompiling code 285 data=auto compiler option 90 sascopts file conversion 285-286 data=far compiler option 89 182 specifying Version 6 librarieS 294 data=faronly compiler Option 90 161 symbol information 286 182 Copy option, Block pull down menu 53 datamem=chip compiler option 172 Correcting errors in source file 16, 19, 24 datamemory= compiler Option 90 177 erage compiler Option 88-89, 271 dataname= compiler Option 91 cpr (Codeprobe) command 25 data=near compiler option 89 143 172 cpr.guide help database 28 __DATE preprocessor macro 273 CPU= compiler option 89 locale specific behavior 278-279 crashing the machine 200 daylight savings time, default 278 Create New CLI option, Windows pull-down debug compiler option 91, 173 menu 54 Debug icon cres.o startup module definition 14 creating residentable programs 143-144 starting the debugger 20 definition 140 saveds compiler option and __saveds debug=fullflush compiler option 91 keyword not allowed 159 debugging programs csource= compiler option 78 cpr (CodeProbe) command 25 __ctors array 146, 147 Dialog window 20-21, 25 customizing screen editor (se) display command 21 See Configuration Window, screen editor go command 21, 25 (se) problems with CodeProbe 197 __CXBRK function 274 quit command 21, 25 __CXFPE function 274 Source window 20-21, 25 __CXOVF stack overflow routine 160 stepping through programs 21 using Shell 25 using Workbench 20-21 D debug =line compiler option 91 debug=symbol compiler option 91 d command debug=symbolflush compiler option 16, See display command 17, 91 d option, se command 38 declarators data= compiler option SAS/C Compiler behavior 272 changing data addressing methods 177 def _ changing default data section 157 beginning of names for icons 25-26 Index 301 default icons for tools 26 End option, Block pull-down menu 51, 53 define= compiler option 92 enumerated types, specifying size 167 define linker option enumerations eliminating standard 1/0 window 137 SAS/C Compiler behavior 271 forcing symbol name references Z86 env directory 7 purpose and use 121-122 ENV: logical device 10 Delay function (AmigaDOS) 20 ENV:sc subdirectory 11 Delete option, Block pull down menu 52, environment 53 SAS/C Compiler behavior 268 deletetabs.se, AREXX macro 69 environment names 278 deleting text 41, 52 environment variables setting 10 11 See also undoing changes equivalent structures 164 166 detachable programs 142-143 definition 164 See also residentable programs examples 165,166 cback.o startup module 142- 143 error and warning messages 203-266 creating 142 definition 142 eliminating informational messages 202 external definition requirements 142 143 enabling suppressed messages 265 restricting to one copy running 143 diagnostics numbered compiler messages 206-257 SAS/C Compiler behavior 268 unnumbered compiler messages 204-205 Dialog window (CodeProbe) 20-21, 25 using error and warllmg messages directories created by installation program 6-8 error compiler options c 6 error= 92 errorconsole 92 env 7 examples 6 errorhighlight 93 help 6 errorlist 93 icons 6 errorrexx 16, 17, 93 Include 7 errorsource 93 Lib 7 maximumerrors= 102 libs 7-8 onerror= 107-108 source 7 errors in source file, correcting 16, 19, 24 starter _ project 6 escape character (Control-\) 46 disassemble= compiler option 92 examples directory 6 diskcopy command (AmigaDOS) 3 executable module 172 display command 21 exit function 277 Display Names option, Project pull-down Exit SE option, Project pull-down menu menu 56 47, 56 DOSBase exiting screen editor (se) 46 47, 56 initialized by startup code 149 extern BPTR _ Backstdout external __dtors array 146, 147 definition 143 external data, common model 168-169 external storage class 180 E external symbol information in hunks 172 externaldefs compiler option 93 Edit icon 14, 38 editor See screen editor (se) F Electronic Mail Interface to Technical Support (EMITS) 31-32 fancy linker option 122 302 Index far BSS hunk 172 __fpinit.c function Z70 far data 172 ! fprint problems 197 far data hunk 172 fprintf function 275 __far keyword 154, 156-157 __fpterm function affecting only calling function 155 from compiler option 94 compatibility with previous releases 157 from linker option 122 declaring data items 176 fscanf function 276 declaring far data 172 ftell function 276 overriding data=auto compiler option function pointers 90 effect of keywords 155 purpose and use 156-157 functions fast linker option 122 calling functions in overlays 128 faster linker option 122 function call problems 199 fax numbers for Technical Support 30 writing replacement functions for SAS/C fflush function 275 library functions 202 fgetpos function 276 fwidth linker option 122 filename extensions options for specifying with sc command 78 G recognized by sc command 78 files g command See also screen editor (xe) See go command editing new files 55 genprotodataitems compiler option 94 maximum number of open files 39 genprotoexterns compiler option 94 naming 56 genprotofile= compiler option 94 opening more than one 38 genprotoparameters compiler option 94 saving 46-47 genprotos compiler option 94-95 specifying multiple filenames with sc genprotostatistics compiler option 95 command 78 genprototypedefs compiler option 95 switching between 38, 39 geta4 function 159 truncation after a write 275 getch function 198 FindPort function 143 getchar problems 198 findsym.se, AREXX macro 69 global message port 143 findsymbol= compiler option 93 global optimization 159, 180, 271 flibcall #pragma statement 162 global symbol information in hunks 172 floating-point numbers globalsymboltable= compiler option 96 conversion types 179 See also makeglobalsymboltable= SAS/C Compiler behavior 270 compiler option value limits 178 go command floppy disk product installation 8-9 completing program execution 21, 25 disks created 9 grep Pretend to Install process 8-9 compared with screen editor (se) read.me file 9 searching 43 fmod function 274 GST= compiler option 96 fopen function 275 GSTimmediate compiler option 96 formal storage class 180 formatted print functions %p conversion 275 276 H problems 197 __fpinit function 146 .h filename extension 78 Index 303 H_DEBUG hunk 173 I H_SYMBOL hunk 173 hard disk product installation 4-8 icons 25-26 directories created 6-8 contained in starter _ project directory 14 modifying startup files 5-6 default icons for tools 26 Pretend to Install process 4 modifying 26 header files naming conventions 25 function call problems 199 object file icons 26 incorrect characters at beginning 196 preventing all icons 26 multipleincludes compiler option 105 preventing specific types 26 reasons for including incorrect file 199 representing SAS/C tools 14 heap area 175 templates in sc:icons drawer 25 height linker option 122 icons compiler option 96-97 help command 27 icons directory 6 help directory 6 identifierlength= compiler option 97 help system 27-29 identifiers See also problem solving SAS/C Compiler behavior 268 See also Technical Support ignore= compiler option 97 help databases 28-29 implementation defined behavior 267-279 installation procedure 4 ANSI definition 267 invoking AmigaGuide 28 arrays and pointers 270-271 menu bar of help screens 29 bitfields 271 navigating through help databases 29 characters 269 sc command 78 declarators 272 screen editor (se) 48 enumerations 271 Screen Editor Help screen 28 hunk symbol records 121 floating_point numbers 270 hunks 171-173 identifiers 268 changing hunk names 175 integers 269-270 library functions 273-278 chip hunk 172 locale speclfic behavior 278-279 preprocessing directives 272-273 contained in primary (root) node 174 qualifiers 272 contents 171-1 72 far BSS hunk 172 registers 271 far data hunk 172 structures 271 H_DEBUG hunk 173 translation 268 H_SYMBOL hunk 173 unions 271 letters indicating hunks produced by implicit structure references 164 compiler 173 Include directory 7 near BSS hunk 172 #include files search paths 272 near data hunk 172 include: device name, assigning 10 NTRYHUNK 133, 175 includedirectory= compiler option 97 reserved section names 175 incomplete structure tags 188-189 udata hunk 172 indent linker option 123 __MERGED hunk 172, 175 indent.se, AREXX macro 70 __NOMERGE hunk 175 indirection operator (-) 155 hwidth linker option 123 __inline keyword 159 304 Index Input Processing option 61-62 exiting screen editor (se) 56 Asm modes 61-62 inserting text 52 Autowrap 61-62 keystroke macros 55 No processing 61-62 managing windows 54 Insert File option, Project pull down menu moving around in files 40, 51 52 qualifier keys 59 inserting text 40-41, 52 saving files 56 installing SAS/C Development System 3-11 searching for and replacing strings 53 assigning logical device names 10 Shift keys 60 directories created by installation undoing changes 56 program 6-8 Keys pull down menu floppy disk installation 8-9 definition 58 hard disk installation 4-8 determining functions of commands 59 modifying startup files 5-6 keystroke equivalents for AREXX preparing for installation 3 commands 70-73 read.me file 5 keystroke macros 45-46 setting environment variables 10-11 assigning macros to another key 46 integers creating 45 SAS/C Compiler behavior 268 keys 55 value limits 177-178 menu options 55 Interlace Toggle option, Windows pull down reloading 45-46 menu 54 replacing 45 __interrupt keyword 155, 157 saving 45-46 IntuiMessage structure 165, 166 keyword options 79 IOExtSer structure 166 keywords isalnum function 273-274 affecting caller and callee 155 affecting definition of functions 155 isalpha function 273-274 iscntrl function 273 274 affecting only calling function 155 islower function 273-274 /CLOSE 138 isprint function 273-274 CON: keywords 138 isupper function 273-274 const 196-197 controlling standard 1/0 window 138 list of special keywords 154 K register 180, 271 signed 177, 183 keepline compiler option 97 specifying on function pointers 155 key definitions 59-61 unsigned 177 displaying 59-60 /WAIT 138 qualifiers 60 __aligned 155-156, 161 raw code 60 __asm 155, 157-158 setting 60-61 __chip 90, 156-157, 176 keyboard shortcuts 50 __far 90, 155, 156-157, 172, 176 keys __inline 159 accelerator keys 50 __interrupt 157 Alt keys 60 __near 90, 155, 156-157, 172, 176 assigning AREXX macros 66 __regargs 111, 155, 157-158, 202 block operations 53 __saveds 112, 144, 145, 155, changing colors 54 158-159 deleting text 41, 52 __stackext 155, 160-161 editing new files 55 __stdargs 111, 155, 157-158 Index 305 L startup modules 141 using with sc command Z4, 120 lctosc conversion utility 285-286 linker (slink) Lib directory 7 See slink command .lib filename extension 78 linker options 121-127 lib: device name, assigning 10 addsym 121 libcode compiler option 98, 159 batch 121 libent.o module 144 bufsize 121 libfd linker option 123 chip 121 libinit.o module 144 define 121-122, 137, 286 libinitr.o module 144 fancy 122 libprefix linker option 123-124 fast 122 libraries faster 122 See also shared libraries from 122 problems creating resident libraries 201 fwidth 122 Version 5 and Version 6 library height 122 equivalences 294 hwidth 123 library base pointers indent 123 See constlibbase compiler option libfd 123 library bases, initializing libprefix 123-124 See system library bases, initializing library 124 library= compiler option 78, 98 librevision 124 .library files libversion 124 library bases 149 map 124 library functions maxhunk 124 SAS/C Compiler behavior 273-278 noalvs 124 library linker option 124 nodebug 125 library revision numbers 150 nover 202 librevision linker option 124 onedata 125 libs directory 7-8 overlay 125 scdebug.library 7 overlymgr 125 scgo.library 7 plain 125 scgst.library 7 prelink 125 schi.library 8 pwidth 125 sckeymap.library 8 quiet 126 sclist.library 8 root 126 scpeep.library 7 smallcode 126 scspill.library 8 smalldata 126 sc1.library 7 stripdebug 126 sc2.1ibrary 7 swidth 126 libversion linker option 124 to 126 Line Number option, Search pull down verbose 126 menu 51 verify 126 link compiler option width 126 displayed in SAS/C Compiler Options with 127 Index screen 17 xref 127 eliminating standard I/O window 137 linker symbols nostdio option 137 absolute symbols not used with purpose and use 98 residentable programs 159 running example.c program 16 at sign (@) preceding 122 306 Index linker symbols (continued) M converting from Version 5 to Version 6 286 macros created for residentable programs 144 See AREXX macros extra underscores preceding 122 See keystroke macros NEWDATAL 144 Main Menu key (F2) 50 RESBASE 144 __main routine RESLEN 144 converting incoming command to ANSI resolving undefined symbols 193 195 format 140 __LinkerDB 144, 158 opening standard I/O window 137 __LinkerDB symbol 144, 158 raising argument limits 140-141 linkeroptions= compiler option 98-99, 120 makedir command (AmigaDOS) 22 linking programs 120-127, 173-174 makeglobalsymboltable= compiler option See also linker options 100 See also sc command See also globalsymboltable= compiler See also slink command option eliminating standard I/O window 137 malloc function 141, 277 entering slink command 121 map compiler option 100 linker messages 258-264 map linker option 124 producing executable modules 173-174 mapfile= compiler option 100 sc compared with slink 120 startup modules 14l-l44 maphunk compiler Option 101 maplib compiler option 101 using Bulld Icon 18 19 mapoverlay compiler option 101 using Shell 24 mapsymbols compiler Option 101 list compiler option 99 mapxreference compiler option 101 listfile= compiler option 99 math= compller option 102 listheaders compiler option 99 math libraries listinclude compiler option 99-100 including incorrect library 194 listmacros compiler option 100 unresolved symbol problems 193-194 listnarrow compiler option 100 math=coprocessor compiler option 270 listsystem compiler option 100 mathematics functions 274 load and stay resident programs math=ffp compiler option 102, 270 See detachable programs math=ieee compiler option 102, 270 See residentable programs math=standard compiler option 16, 17, load files 172 102 Load Macros option, Project pull down math=68881 compiler option 102, 158 menu 55 math=68882 compiler option 102 locale specific behavior 278-279 MAXARG symbol 140 logical device names maxhunk linker option 124 ENV: 10 maximumerrors= compiler option 102 ram: 11 maximumwarnings= compiler option 102 logical device names, assigning 10 memory options include: 10 bssmemory= 86 lib: 10 codememory= 87 sc: 10 datamemory= 90 long __BackGroundIO external definition memorysize= 103-104 143 memorysize= compiler option 103-104 long __priority external definition 142 See also argumentsize= compiler long __stack external definition 142 option Index 307 See also preprocessorbuffer= compiler overriding data=auto compiler option option 90 default values for argumentsize and purpose and use 156-157 preprocessorbuffer options 104 nested comments 168 size specifications 103 See also commentnest compiler option menus NEWDATAL symbol 144 See also specific menus newline character (\n), AREXX macros 65 abbreviated menus 50 \n (newline character) 65 block operations 53 No processing option 61-62 deleting text 52 noalvs linker option 124 editing new files 55 noautoreg compiler option 180 exiting screen editor (se) 56 nodebug linker option 125 inserting text 52 __NOMERGE hunk 175 keystroke macros 55 non-reentrant programs 176 managing windows 54 nostdio option 137 moving around in files 51 nover linker option 202 naming files 56 NTRYHUNK code hunk 133, 175 saving files 56 searching for and replacing strings 53 selecting menu options 50 O undoing changes 56 __MERGED hunk 172, 175 .o filename extension 78 message browser object= compiler option 78, 105 See scmsg (message browser) object file icons 26 messages objectlibrary= compiler option 106 See error and warning messages objectname= compiler option 106 modified compiler option 104 oldpreprocessor compiler option 106-107 Move option, Block pull down menu 53 onedata linker option 125 moving around in files 40, 51 onerror= compiler option 107-108 msg statement online help See #pragma msg statement See help system multiplecharacterconstants compiler option Open New Window option, Project pull- 104-105 down menu 55 multipleincludes compiler option 105 Open Window option Project pull down menu 55 Windows pull-down menu 47, 54 N operands conversion types 179 naming files 56 widest operand 178 narrow types in pre-ANSI function optimize compiler option 108 declarations 187-188 optimizealias compiler option 108 national characters in variable names 168 optimizercomplexity= compiler option 108 near BSS hunk 172 optimizerdepth= compiler option 109 near data 172 optimizerglobal compiler option 109 near data hunk 172 optimizerinline compiler option 109 __near keyword 154, 156-157 optimizerinlocal compiler option 109 affecting only calling function 155 optimizerloop compiler option 109 compatibility with previous releases 157 optimizerpeephole compiler option 109 declaring data items 176 optimizerrecurdepth= compiler option declaring near data 172 110 308 Index optimizersize compiler option 110 parameters=register compiler option 110, optimizertime compiler option 110 157-158, 202 Options pull down menu parameters=registers option 294 Auto-lndent Mode 62 63 parameters=stack compiler option 110, Backup File Mode 63 158 Case Sensitive Characters 63-64 patterns, searching for 43 Column Display 63 perror function messages 276-277 Configuration Window 57 plain linker option 125 definition 58 plus sign (+) Input Processing 61-62 continuing lines of filenames for Prompt Before Undo 63 overlays 129 Searches Method 63 separating filenames for overlays 129 Tab Expansion Method 62 separating filenames for sc command 78 __OSlibversion external long integer 150 pointers overlay linker option 125 declaring 155 overlay manager default length 178 customizing 133 SAS/C Compiler behavior 270-271 definition 127 portable code, writing 181-189 overlay tree See also implementation defined asterisks indicating depth 129 behavior definition 127 compiling with strict or ANSI options examples 128,130-131,132 181-182 terminating with pound sign (#) 129 data and type sizes 183 overlays 127 133 defining __STRICT__ANSI preprocessor data=near compiler option 132 symbol 182 definition 127 guidelines for avoiding problems functions in overlays 128 182 183 listing filenames 129 incomplete structure tags 188-189 maximum number 129 narrow types in pre ANSI function nodes in executable module 174 declarations 187-188 overlay option 129 structure size and padding 493 root node 127, 128-129 writing structures to disk file 184-186 smallcode compiler option 132 pound sign (#) smalldata compiler option 132 terminating overlay tree 129 specifying compiler options 132-133 #pragma msg statement 162, 162-163 stringmerge compiler option 132 error 162 using mu]tiple shared libraries instead example 163 12, ignore 162 with files 129 130 pop 162 overlymgr linker option 125 push 162 overwrite mode 41 warn 162 __ovlymgr global symbol 133 #pragma statements 161-163 flibcall 162 types of #pragma statements 161 P using in residentable programs 143 precision= compiler option 111 .p filename extension 78 prelink linker option 121, 125 padding structures 183 preprocessing parameters= compiler option 110-111 comma (,) operator 168 parameters=both compiler option 110, oldpreprocessor compiler option 106-107 158, 202 sizeof operator 168 Index 309 preprocessing directives Prompt Before Undo option, Options pull- SAS/C Compiler behavior 272-273 down menu 63 preprocessor symbols prototype generation 94 95 defined by compiler 119 PutMsg exec function 165 defined by compiler options 120 pwidth linker option 125 __STRICT__ANSI 85, 182 preprocessorbuffer= compiler option 111 preprocessoronly compiler option 111-112 Q primary node 174 Print option, Block pull down menu 53 q (quit) command 21, 25 printing messages in the Shell 143 qualifier keys 59, 60 __priority external definition 142 problem solving 193-202 qualifiers See also Technical Support SAS/C Compiler behavior 272 asctime function 200-201 question mark (?) CodeProbe problems 197 getting help for sc command 78 compilation errors 195-197 quiet linker option 126 crashing the machine 200 quit command (debugger) 21, 25 eliminating informational messages 202 formatted print functions 197-198 getchar problems 198 R incorrect results from function calls 199 resident programs or libraries 201 ram: logical device 11 resolving undefined symbols 193-195 raw code for key definitions 60 standard I/O window 201 rawcon function 198 writing replacement functions 202 Read option, Block pull-down menu 53 proceed command read.me file 5, 9 equivalent to Return key 21 realloc function 277 process restrictions using startup modules recompiling and linkillg (rebuilding) 141 programs 19, 24 processor-specific code reentrant and non-reentrant programs 176 See CPU= compiler option regargs keyword 157 158 programname= compiler option 112 affecting caller and callee 155 Project pull down menu purpose and use 157 158 Close Window 47 Convert Macro to Key 55 usmg with user-written replacement definition 58 functions 111,202 Display Names 56 register keyword 180, 271 Exit SE 47, 56 register storage class 180 Insert File 52 registerized parameterS 294 Load Macros 55 registers Open New Window 55 SAS/C Compiler behavior 271 Open Window 55 regular expressions Rename 56 definition 41 Save & Close 19, 24, 47, 56 entering in searches 43 Save & Continue 47, 56 Use Regular Expressions option 63 Save & Reopen 47, 55, 56 relocation records 172 Save Macros 55 remove function 275 Undo Last Change 56 Rename option, Project pull-down menu projects, setting up 14-15 56 310 Index replacing character strings 42-43 s:user startup file entering regular expressions 43 modifying 5-6 keys 53 solving problems 195 menu options 53 SAS/C language options 43 See Amiga-specific features of SAS/C prompted replacements 42 language RESBASE symbol 144 sascopts file, converting 285-286 resetoptions compiler option 79, 112 Save & Close option, Project pull-down resident command (AmigaDOS) menu 19, 24, 47, 56 not used with detachable programs 143 Save & Continue option, Project pull-down using with residentable programs 143 menu 47, 56 resident libraries, creating 201 Save & Reopen option, Project pull down resident program menu 47, 55, 56 definition 143 Save Macros option, Project pull-down residentable programs 143-144 menu 55 See also detachable programs saveds compiler option 112, 144, 158 creating 143-144 __saveds keyword 112, 158-159 cres.o startup module 143, 144 affecting definitions of functions 155 debugging with catchres.o startup Amiga-specific features 158-159 module 144 applications without startup modules requirements 144 145 solving problems 201 compared with saveds compiler option symbols created by slink 144 158 unable to reference absolute symbols equivalent to geta4 function 159 159 not used with cres.o and catchres.o RESLEN symbol 144 startup modules 144, 159 resolving undefined symbols 193-195 purpose and use 112 restoring text saving See undoing changes compiler options 17 Return key files 46-47, 56 equivalent to proceed command 21 keystroke macros 45-46 reusing saved configuration settings 64 new settings in Configuration Window root linker option 126 64 root node sc command 77-78 contents 128-129, 174 See also compiler options definition 127 compared with slink command 120 running programs 174-175 compiling and linking programs 24 heap area 175 default icons 26 Shell method 24-25 filename extensions 78 stack area 174 link compiler option 24, 120 Workbench method 19-20 options for specifying filename extensions 78 specifying multiple filenames 78 S specifying startup modules 141 startup option 141 .s filename extension 78 syntax 77 s:startup-sequence file sc.guide help database 29 modifying 5-6 sclib.guide help database 29 solving problems 195 sc util.guide help database 28 s:startupII file, modifying 5 sc: device name, assigning 10 Index 311 scdebug.library 7 status line 39-40 scgo.library 7 substituting another editor 14 scgst.library 7 switching between windows 38, 48 schi.library 8 undoing changes 44, 56 sckeymap.library 8 window display size 39 sclist.library 8 window management 47-48, 54 scmsg (message browser) screen editor (se), controlling 49-56 correcting source file errors 18, 24 block operations 43-44, 53 SAS/C Message Browser window 18 changing colors 54 specifying errorrexx compiler option 16, deleting text 41, 52 17 editing new files 55 scmsg.guide help database 28 exiting the editor 47, 56 scoptions file inserting text 40-41, 52 converting sascopts file 285-286 keystroke macros 45-46~ 55 overriding settings 79 managing windows 47-48, 54 saving options 16, 23 moving around in files 40, 51 SCoptions icon 14 naming files 56 scopts utility replacing character strings 42-43, 53 gadgets for selecting options 17 saving files 46 47, 56 running from screen editor (se) 48 searching for character strings 41-42 setting compiler options 16-18 43, 53 specifying options on command line 23 selecting menu options 50 starting with SCoptions icon 14, 16 undoing changes 44, 56 using scopts screens 23 screen editor (se), customizing See Configuration Window, screen editor scpeep.library 7 (se) screen editor (se) 37-48 See also AREXX interface screen editor (se), startmg 38 39 See also se command block operations 43-44 53 specifymg more than one filename 38 compiling programs 8 using Edit icon 14, 38 setup command control characters 46 default icons 26 creating source files 15-16, 22 setting up projects 14-15 deleting text 41, 52 scspill.library 8 Edit window, illustration 19 sc1.library 7 editing text 40 46 sc2.library 7 entering text 40-46 sc5 command exiting 46-47, 56 converting old code to Version 6 285 getting help 48 se command insert mode 40-41, 52 See also screen editor (se) keystroke macros 45-46, 55 -d option 38 maximum number of open files 39 default icons 26 moving around in files 40, 51 syntax 38 overwrite mode 41 -v option 38 replacing character strings 42-43, 53 se.dat file 38 saving files 46-47, 56 se.guide help database 28 Screen Editor Help screen 28 Search pull down menu searching for character strings 41-42, Line Number 51 43, 53 Search Again 53 split-screen mode 48 Search and Replace 53 starting 14, 38-39 String Search 53 312 Index Searches Method option compared with sc command 120 Options pull-down menu 63 default icons 26 String Matching 41, 63 define linker option 137 Use Regular Expressions 63 eliminating standard I/O window 137 searching for character strings 41-42 invoked by smake utility 19 See also replacing character strings linker messages 258-264 backward searching 42 specifying startup modules 141 case sensitivity 42 symbols created for residentable entering regular expressions 43 programs 144 forward searching 41 syntax 121 keys 53 smake utility menu options 53 compiling programs 18-19 regular expressions 41 definition 14 String Matching option 41 starting with Build icon 14 semicolon (;) smallcode compiler option 113, 132, 177 Asm mode 62 smallcode linker option 126 setbuf funnion 275 smalldata compiler option 113, 132, 177 setbufv function 275 smalldata linker option 126 setenv command 11 snapshot files shared libraries creating 142, 144 creating 144 hard drive corruption 142, 144 using instead of overlays 127 Shell solving problems environment for argv and argc 135-136 See problem solving printing messages in the Shell 143 source code programs linked with startup module not placed in sc dlrenory tree 8 141 source directory 7 using SAS/C tools 22-25 source file errors, correning 16, 19 24 Shift keys source files, creating equivalence 60 screen editor (se) 15-16, 22 independent operation 60 Shell 22 short integers Workbench 15-16 problems with casting results 179 Source window (CodeProbe) 20-21, 25 shortintegers compiler option 112, 178, sourceis= compiler option 113 179, 183 special keywords SIGILL signal 274 See keywords SIGINT signal 274 stack signal funnion 274 alignment problems 156 signed data types definition 160 See data types and sizes managing stack space 160-161 signed keyword 177, 183 purpose and use 174 sizeof operator running out of stack space 161 portability of structures 183 __stack external definition 142 preprocessor direnives 168 __stack external long integer 160, 161 slash (/) stack overflow routine (__ CXOVF) 160 comment start sequence (/*) 168 stackcheck compiler option 113, 160, 161 slashes (//) defining comment blocks 168 __stackext keyword 160-161 slink command affecting definitions of functions 155 See also linker options managing stack space 160-161 See also linking programs pointer register variables 161 Index 313 stackextend compiler option 113 stepping through programs 21 managing stack space 160, 161 _STI preceding function name 145 pointer register variables 161 __STKNEED external long integer 160, purpose and use 113 161 standard I/O window storage classes 179-180 changing window attributes 137-138 automatic 180 declaring _ stdiowin external variable external 180 137 formal 180 eliminating 137, 201 register 180 keeping open 20 static 180 keywords for controlling 138 strerror function 278 program crashes caused by eliminating __STRICT __ANSI preprocessor symbol 138 85, 182 standard programs, creating 142 strict compiler option 114, 181-182, 183 standardio compiler option 114 strict reference-definition model 169 starter _ project directory 6, 14 String Search option, Search pull-down startup= compiler option 114 menu 53 startup files, modifying stringconst compiler option 114 adding assign statements 10 stringmerge compiler option 114-115 s:StartuP sequence file 5-6 declaring data items 177 s:startupll 5 effect on static objects 180 s:user-startup file 5-6 purpose and use 114-115 startup modules 140-145 using overlays. 132 . See also autoinitialization function stripdebug compiler option 116 stripdebug linker option 126 See also autotermmahon functlon struct IntuiMessage 165, 166 argument hmut, changmg 140-141 struct Message 166 detachable programs (load and stay struct WBStartup 136 resident) 142-143 linking with startup modules 141-144 Structureequivalence compiler option 116, 154,275 list of modules 140 structures modifying __main 140-141 determining size and padding 183-184 residentable programs 143-144 equivalent structures 164-166 shared libraries 144 implicit structure references 164 Shell process restrictions 141 incomplete structure tags 188-189 standard programs 142 IntuiMessage structure 165, 166 tasks performed by all modules 140 IOExtSer 166 writing applications without startup portability guidelines 185-186 modules 145 SAS/C Compiler behavior 271 startup option 141 writing to disk file 184-186 statements __stub library function 121 SAS/C Compiler behavior 272 suppressed messages, enabling 265 static storage class 180 swidth linker option 126 status line, screen edhor (se) 39-40 switch options 79 _STD preceding function name 145 Switch Windows option, Windows pull-down __stdargs keyword 111 menu 39 affecting caller and callee lSS Switch windows option, Windows pull-down purpose and use 111, 157-158 menu 54 __stdiov37 external variable 138 switching between windows 38, 39, 48 __stdiowin external variable, declaring symbols 137-138 See linker symbols 314 Index SYSBase tolower.se, AREXX macro 70 initialized by startup code 149 toupper.se, AREXX macro 70 system function 278 translation (diagnostics) system library base pointers SAS/C Compiler behavior 268 See constlibbase compiler option trigraph compiler option 116 system library bases, initializing 147-151 automatically initialized library bases 148-149 U defining library bases in your code 149 examples 148, 149-150 udata hunk 172 failure of libraries to open 150-151 undefined symbols, resolving 193-195 library bases for .library files 149 underscore ( _ ) library revision numbers 150 default prefix for functions 123 preceding linker symbols 122 T underscore compiler option 116 undo command 44 Undo Last Change option, Project pull down Tab Expanslon Method opbon, Optlons pull- menu 56 down menu 62 undoing changes 44, 56 tab stops, setting 61 tb utility 142, 144 fifty line limit 44 Technical Support 29-34 keys 56 See also problem solving last line of text deleted 41 BIX support 31 menu options 56 contacting 29-34 Prompt Before Undo option 63 ITS (Electronic Mail Interface to unindent.se, AREXX macro 70 Technical Support) 31-32 unions information required 33-34 SAS/C Compiler behavior 271 Internet support 31-32 unnamed unions 163-164 phone number requirement 33 unschar compiler option 272 phone, mail, and fax support 30 unsigned data types problem description requirement 33_34 See data types and sizes registration number requirement 3, 33 unsigned keyword 177 return address requirement 33 unsignedchar compiler option 116, 177 Usenet support 31-32 utilitylibrary compiler option 117 version number requirement 33 when to call 29-30 telephone numbers for Technical Support V 30 text hunk 172 -v option, se command 38 time and date variables locale specific behavior 278-279 displaying values 21 __TIME preprocessor macro 273 national characters in variable names time zone, default 278 168 __tinymain routine 290 verbose compiler option 117, 173 to= compiler option 116 verbose linker option 126 to linker option 126 verify linker option 126 Toggle Display Size option, Windows pull- version compiler option 117 down menu 39, 54 Version 5, converting Toggle Screen Size option, Windows pull- See converting from Version 5 to down menu 48 Version 6 Index 315 W X /WAIT keyword 138 _ XCEXIT function 151 warn= compiler option XDEFS in hunks 172 enabling suppressed messages 265 xref linker option 127 enabling warnings 183 xreference compiler option 118 purpose and use 117-118 xreferenceheaders compiler option 118 warnings, enabling xreferencesystem compiler option 119 See also error and warning messages See also warn= compiler option incomplete structure tags 189 Z narrow types 188 warnvoidreturn compiler option 118 zero-length arrays 163-164 widest operand 178 width linker option 126 windows Special Characters displaying two files 39 managing in screen editor (se) 47-48, 54 {} (braces) switching between windows in screen See braces ({ }) editor (se) 38, 39 \ (backslash) text window size in screen editor (se) 39 See backslash (\) Windows pull down menu / (slash) Close Window 54 See slash (/) Create New CLI 54 + (plus sign) Interlace Toggle 54 See plus sign (+) Open Window 47, 54 * (asterisk) Switch Windows 39 See asterisk (*) Switch windows S4 *__procname external definition 142 Toggle Display Size 39, 54 ; (semicolon) Toggle Screen Size 48 See semicolon (;) with= compiler option 118 , (comma) with files See comma (,) asterisk (-) indicating depth of overlay _(underscore) tree 129 See underscore ( _ ) examples 130-131 ? (question mark) format 129 See question mark (?) plus sign (+) separating filenames 129 : (colon) pound sign (#) terminating overlay tree See colon (:) 129 # (pound sign) with linker option 127 See pound sign (#) Workbench 135-138 @ (at sign) environment for argv and argc 136 See at sign (@) program structure, example 136 running programs 135-138 standard I/O window management 1 137-138 using SAS/C tools 14-21 16-bit address Write option, Block pull down menu 53 advantages and disadvantages 176 writing portable code relative to program counter 176 See portable code, writing relative to register A4 176 316 Index 16-bit references specifying with code = compiler option 87 __far keyword 156 __near keyword 156 3 32-bit address advantages and disadvantages 176 32-bit references chip data 176 specifying with code = compiler option 87