Part1 - Part2


  SAS Development System

  User's Guide

  Volume 1:

  Introduction, Editor, Compiler

 

 

  Version 6.0

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

     SAS Institute Inc.

     SAS Campus Drive

     Cary, NC 27513

 

 


 

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 <stdio.h>, 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 <stdio.h>

                  #include <math.h>

                  #include <proto/dos.h>

                  

                   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 <stdio.h>

       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 <stdio.h>

   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 <stdio.h>

                          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: <nil: program-name


 

142 Chapter 10

 

 

 

 

         Creating  For most of your programs, you can use the default startup module, c . o.

         Standard  If you are debugging a standard program, you can use the catch . o

         Programs  startup module to capture information if your program terminates

                   abnormally. If you link with catch . o and your program terminates

                   abnormally, catch . 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 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 <proto/intuition.h>

 

 

 

 

                            /* 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 <proto/intuition.h>

 

 

              /* 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 l