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

ISBN 1-55544-496-2

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

Amiga Workbench Version 2.0

Installer

AmigaGuide and WDisplay

Distributed under license from Commodore.

Enforcer and Mungwall

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

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

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

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.

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 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).

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.

[] 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

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.

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

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"'

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

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-

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-

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.

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

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

>> 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

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

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

_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

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.

the stack. If you run the global optimizer, the optimizer allocates all

run the optimizer and you specify the noautoreg option, only those

variables you declare with the register keyword are stored in

registers. If you compile with autoreg, the code generator decides

which additional variables are stored in registers.

181

13 Writing Portable Code

181 Introduction

181 Compiling Your Program

182 Writing Your Program

183 Dealing with Data Type Sizes

183 Determining Structure Size and Padding

184 Writing Structures to a Disk File

187 Using Narrow Types in Pre-ANSI Function Declarations

188 Using Incomplete Structure Tags

Introduction

The C language has many characteristics of a portable language, but some

features of the C language are dependent on the type of machine on

which the program is running. However, you can write programs that

run on many different machines if you follow some guidelines when

compiling and writing your program.

The following sections describe actions you can take to improve the

portability of your programs.

Compiling Your Program

You can compile your program with the strict and/or ansi options.

These options enable many warnings that identify possible problems in

your code that may cause errors if you port your code to systems other

than the Amiga system. For example, the following code generates

message number 120:

void func1(long);

void func2(void)

{

short s=0;

func1(s);

}

182 Chapter 13

If you compile this code with the strict option, the compiler displays

the following message:

Warning 120: Integral type mismatch: possible portability problem

Expecting "long", found "short"

Writing Your Program

If you use only library functions and language features that are defined in

the ANSI Standard (American National Standard for Information

Systems--Programming Language C), your program should compile

without modification on any system that has an ANSI-compliant C

compiler. However, there are many features of the C language that are

implementation-defined. Even if your program compiles without

generating errors, it may not run as you expect. See Appendix 3,

"Implementation-Defined Behavior," for more information.

To help you identify non-portable functions and macros in your

program, you can define the _STRICT_ANSI preprocessor symbol. You

can define this symbol by entering define _STRICT_ANSI= 1 in the

sc command or by entering the following statement in your C source file

before any header files are included:

#define _STRICT_ANSI 1

If you define _STRICT_ANSI, the header files that are defined by the

ANSI Standard (such as errno.h and stdio.h) do not define any

prototypes or macros for functions not permitted by the ANSI Standard.

If your program calls a non-ANSI function, the compiler issues a warning

message because the function has no prototype. For more information on

the _STRICT_ANSI symbol, refer to SAS/C Development System Library

Reference, Version 6.0.

In addition, if you follow a few additional guidelines, you can avoid

most portability problems. The following list contains some guidelines

that can help improve the portability of your program.

[] Do not assume data type sizes are standard.

[] Do not assume structure padding or size is standard.

[] Be careful when writing structures to disk.

[] Do not use narrow types in old-style definitions.

[] Be careful about using incomplete structure tags.

[] Do not write pointers to files. Pointers are useless outside of the

invocation of the program that generates them.

Writing Portable Code 183

[] Do not assume that you know whether char variables are signed.

[] Do not assume that you know the placement of bitfields within

structures.

The following sections discuss these guidelines in more detail.

Dealing with Do not assume that the int data type is always a particular length. The

Data Type Sizes ANSI Standard specifies that the int type must be at least as long as the

short type and that the short data type must be able to hold numbers

in the range 32767 to -32768. Therefore, portable code should never

store numbers larger than 32767 or smaller than -32768 in an int. Use

long for larger numbers.

The default size of an int on the Amiga system is four bytes. On other

systems (such as the IBM PC), the size of an int is two bytes. The

SAS/C Compiler treats the data types int and long as the same data

type. However, you can set the size of an int to two bytes by compiling

your program with the shortint option. If you compile with

shortint, the compiler treats the data types int and short as the

same data type.

If you port your program to a system that uses two-byte integers and

you do not compile with the shortint option, you may receive

unexpected results. For example, when passing parameters on the Amiga

system, short and char variables are silently promoted to ints.

Therefore, any function declared as receiving a long does not produce a

warning if you pass a short or char to the function. To receive an

appropriate warning message, you can enable warning 120 by compiling

with the warn= 120 or strict compiler options.

Declaring an object as signed is usually redundant, because integral

objects are signed by default. However, judicious use of the signed

keyword can enhance your program's portability, because some compilers

may make char declarations and bitfields unsigned by default.

Determining Even though the Motorola 68000 processor uses byte addresses, it

Structure Size requires that 16-bit and 32-bit data items be aligned on even addresses.

and Padding That is, the lowest bit of the address must be zero. Because of this

requirement, the SAS/C Compiler inserts dummy bytes (called padding) as

necessary to align integers, floats, doubles, and pointers.

For example, in the following structure, the SAS/C Compiler adds one

byte between the structure members a and 1.

struct misc

{

char a[3];

184 Chapter 13

long l;

};

If the dummy byte was not added, the long structure member would

end up on an odd boundary and an addressing exception would result.

On other systems, an ANSI compliant C compiler may add more or less

padding as required. Many computers require that long integers fall on

four-byte boundaries, so the compiler would add three bytes of padding

instead of one.

Because of these alignment requirements, data structures may be

different sizes on different machines. Do not assume that you know the

size of a structure based on the fields declared in it. Use the s i z eo f

operator to determine the size, and do not depend on sizeof to return

the same result on different machines. Using the previous example, the

expression sizeof ( struct misc ) has a value of 8, and the following

expression has a value of 7:

sizeof(misc.a) + sizeof(misc.l)

Writing If you try to write structures to a disk file on one system and read the file

Structures to a on another system, you may get different values. This problem may be

Disk File caused by differences in structure padding (as described under

"Determining Structure Size and Padding") or by differences in the

representations for characters, floating-point numbers, or integers. For

example, the following program writes a structure to a file:

linclude <stdio.h>

main()

{

FILE *fp;

struct

{

char x;

short y;

} record;

fp = fopen("testfile","wb");

record.x = 3;

record.y = 4;

fwrite(&record,sizeof(record),1,fp);

fclose(fp);

}

Writing Portable Code 185

If you compile and run this program using the default compiler options,

the file testfile contains four bytes in the following order: 03 00 00

04. However, if you compile and run this program under MS-DOS,

which uses the Intel 8086 processor, the file contains 03 04 00. The

reasons for the different values are as follows:

[] The SAS/C Compiler inserts a padding byte so that integer y is

correctly aligned. The Intel processor does not require this padding.

[] The Motorola processor writes integers from the high byte to the low

byte, and the Intel processor writes integers from the low byte to the

high byte.

The following paragraphs describe some simple rules that you can use

to make your structures more portable between the Amiga computer and

most other computers. These guidelines help you produce a structure that

your program can write to disk and then read in a single operation.

These guidelines are not guaranteed to work in all cases, but they do gain

you limited ability to interchange files between various computers.

The computer to which you are porting your program must do the

following:

[] Use the same floating-point format for doubles that you are using on

the Amiga system (FFP if the math= ffp option is specified, IEEE for

all other formats).

[] Use the ASCII character set.

[] Use the same sizes for data types:

char 1

short 2

long 4

[] Store integers using the same bit pattern that the Amiga system does.

The structure to be written must follow these rules:

[] The structure can contain only the following data types:

Type Length

char 1

short 2

float 4

long 4

double 8 (or 4 if you compile with math=ffp)

Do not use ints or any pointer types in the structure.

[] Structures or unions may contain other structures or unions that

follow these rules.

[] Each field must be placed at an offset relative to the start of the

structure that is an exact multiple of the field's size.

186 Chapter 13

[] A nested structure or union must be placed at an offset that is an exact

multiple of the largest simple arithmetic type occurring in any of its

fields, including the fields of any substructures or subunions.

[] If the structure or any of its substructures contains a double, the

structure must contain extra fields as needed to ensure that its total

size is an exact multiple of the size of a double. If it does not contain

a double, it must contain extra fields to ensure that its total size is an

exact multiple of four.

For example, you cannot port the following structure between systems:

struct NOTDISKABLE /* Non-diskable structure */

{

char a;

double d;

short s;

long l;

char name[27];

struct XXX

{

char a, b;

} foo[11];

};

To make the previous structure portable between systems, you must

declare the structure as follows:

struct DISKABLE /* Diskable version of same structure */

{

char a;

char dummyl[7]; /* following double needs 8-byte offset */

double d;

short s;

short dummy2; /* following long needs 4-byte offset */

long l;

char name[27];

char dummy2[5]; /* following structure needs 4-byte offset */

struct XXX

{

char a, b;

char dummy3[2]; /* Pad to multiple of 4 bytes */

} foo[11];

char dummy4[4]; /* Pad to multiple of 8 bytes */

};

Writing Portable Code 187

Using Narrow The ANSI Standard states that function definitions should specify the data

Types in type of each parameter, as in the following example:

Pre-ANSI

Function /* ANSI Standard prototype-style definition */

Declarations void newfunc(short s, float f)

{

}

Pre-ANSI C accepted function definitions in the following form:

/* Pre-ANSI old-style definition */

void oldfunc(s, f)

short s;

float f;

{

}

The ANSI Standard default argument promotion rules (described in

Section 3.3.2.2 of the ANSI Standard) differ for functions defined with

prototype style definitions and functions defined with old-style definitions.

You may get incorrect results on ANSI conforming compilers if you use

ANSI standard prototypes and old-style function definitions for the same

function. You can avoid this problem by not using narrow data types

(char, short, and f loat) in function prototypes and definitions.

The ANSI Standard says that functions defined with old-style definitions

and no prototypes must receive all char and short parameters as if

they were type int and receive all float parameters as type double.

The incoming parameters are then converted to the appropriate shorter

type. Functions defined with new-style definitions are free to receive

narrow types as declared. Unfortunately, the caller of the function does

not know whether the function is defined with a prototype-style definition

or with an old-style definition.

The ANSI Standard does not define what happens if you declare a

function using an old-style definition but also include an ANSI standard

prototype for the function. To make more programs work as expected, the

SAS/C Compiler treats such definitions as if they were new-style

definitions.

188 Chapter 13

If you do not port your program to a system other than the Amiga

system, you should not encounter any problems with narrow types unless

the following situation occurs:

The caller has a prototype for a function that says float. The

called function does not include the prototype and has an old-

style definition that says f loat.

The data types char and short do not cause problems on the Amiga

system because they are passed as if they were type int for both old-

style and prototype-style function definitions.

To help identify problem situations, you can enable the following

warnings:

Warning Description

165 This message identifies narrow types that have been used

in function prototypes. You can enable this warning with

the warn=165 option.

176 This message identifies arguments that have been

promoted using the default argument promotion rules

and, as a result, conflict with the prototype given for the

function. You can enable this warning with the strict,

ansi, or warn=176 option.

179 This message identifies narrow types that have been used

in an old-style function definition. You can enable this

warning with the strict or warn=179 option.

Using Incomplete An incomplete structure tag is a structure tag (or name) that has not yet

Structure Tags been defined. The ANSI Standard allows you to refer to structures by

name before they have been defined, as long as you only declare pointers

to the structure and do not attempt to dereference these pointers.

Incomplete structure tags can cause problems if they occur in a

function prototype. The ANSI Standard allows incomplete structure tags

in function prototypes but states that the incomplete tag goes out of scope

at the closing parenthesis of the prototype. Any declaration of the

structure later in the program is not associated with the incomplete tag

used in the prototype and is considered to be a completely different

structure.

If you define the function later in the program, an ANSI-conforming

compiler may issue an error message, and your program may not

compile.

Writing Portable Code 189

For example, many ANSI-compliant compilers generate an error

message for the following code, claiming that the type of the parameter

does not match the type declared in the prototype.

void func(struct FOO *); /* Incomplete tag FOO */

struct FOO

{

int x, y, z;

};

void func(struct FOO *parm) /* Error here! */

{

}

If you move the definition of struct FOO before the prototype, this

code compiles without problems.

To help you identify incomplete tags, you can enable the following

warnings:

Warning Options

148 This warning identifies any use of incomplete tags. You

can enable this warning with the warn= 148 option.

149 This warning identifies incomplete tags that are used in

function prototypes. You can enable this warning with

the strict or warn=149 option.

191

190 Chapter 13

[] Part 4

Appendices

Appendices 1 Solving Common Problems

2 Error and Warning Messages

3 Implementation-Defined Behavior

4 Converting From Aztec C Options to SAS/C Options

5 Converting from Version 5 to Version 6

192

193

Appendix 1

Solving Common Problems

193 Introduction

193 Resolving Undefined Symbols

195 Fixing Compilation Errors

197 Using CodeProbe

197 Using Formatted Print Functions

198 Using getchar

199 Getting Incorrect Results from Function Calls

200 Crashing the Machine

200 Using The asctime Function

201 Managing the Standard I/O Window

201 Linking Resident Programs or Creating Resident Libraries

202 Writing Replacement Functions for SAS/C Library Functions

202 Eliminating Informational Messages

Introduction

This appendix describes the solutions to some of the most common

problems for which users call the Technical Support Division. This

appendix also includes questions that the Technical Support Division

anticipates will be generated by the conversion to Version 6.

Before calling the Technical Support Division, read the read.me file

on disk 1 carefully. (The read.me file is also copied to the directory into

which you install the product if you installed the SAS/C Development

System on a hard drive.) This file contains errata for the documentation

and information about any feature that may have been added after the

documentation went to press.

Resolving Undefined Symbols

When I compile and link, I get messages reporting Undef ined

Symbol: _CXnnn and saying that the proper math library has not

been included.

In your program, you have accessed floating-point math routines, but

you have not linked with the appropriate math library. Specify the

appropriate math option for the library with which you want to link,

such as math=standard. If you are using the link option to link

your program, the compiler links with the correct math library. If you

194 Appendix 1

call the linker separately from the compiler, you must specify the

correct math library in the slink command after the libs keyword.

Refer to SAS/C Development System Library Reference, Version 6.0 for

more information about math libraries.

I am getting BLTN and/or CXERR errors, and I am using math libraries

and header files.

You may be including the math header files for one type of floating-

point format and linking with libraries for another type of floating-

point format. For example, you may be including m68881.h and

linking with scmffp.lib. Different floating-point formats are

incompatible and should not be mixed. Make sure that your included

header files match the math library with which you are linking.

If you find no problem with the compatibility between your header

files and your math library, contact the Technical Support Division.

When I link my project, I get undefined symbols. This code worked in

Release 5.10.

Some of the library symbol names have been changed to comply with

the ANSI Standard for symbol names. The ANSI Standard states that

any symbols that are not mandated by the Standard must begin with

an underscore and a capital letter or two underscores.

When you compile your program, the compiler adds an additional

underscore to the beginning of any symbols defined in C code.

Therefore, a C symbol with two underscores has three underscores

when the linker finally sees the symbol.

If your code refers to a symbol that has changed names from

Version 5 to Version 6, the linker may produce an undef ined

symbol message when you link your program. If you receive this

message, first check the SAS/C Development System Library Reference

for different versions of the symbols with different numbers of

underscores. Remember, the linker reports one more underscore on

the symbol than the SAS/C Development System Library Reference

shows.

Change your C code to refer to the new name for the symbol as

described in the SAS/C Development System Library Reference. If this

solution is not practical because of the number of references to the

symbol, you can solve this problem in one of two other ways:

[] Use the define option on the sc command or a #define

statement in a header file to define the old name to the new name.

[] Use the define option on the slink command to force all

references to one of the names to refer to the other. If you define

the item in your code (in other words, you declare it without the

extern keyword), you should use the def ine option to defife the

Solving Common Problems 195

new name (used by the library) to the old name (used by your

code). If you declare the item with the extern keyword and,

therefore, use the library definition for the item, use the define

option to define the old name (used by your code) to the new name

(used by the library).

One very common technique used in Version 5 was to declare the

main routine of your program as _main instead of main to bypass

the overhead required to set up stdio and argument parsing. You

should change this name to __main and add the keyword

__stdargs to be compatible with Version 6. If you do not change

this name, the linker issues a message saying that the symbol _ main

is undefined. (Remember, the linker puts in an extra underscore, so

the symbol it is really looking for is main).

Fixing Compilation Errors

I have installed my compiler correctly, but I keep getting the message

se not found or sc not found whenever I try to do anything.

Your s:user-startup may not be set up correctly. The installation

program places three assign statements and the path statement at

the end of your s:user-startup file. If you are invoking any

programs that create a new Shell (such as PopCLI) in your

s: user-startup file before the path sc: c add statement, sc: c

may not be in new shells created by the program. To correct the

problem, move the three assign statements and the path statement

above any calls to programs that create a new Shell.

If you are running under AmigaDOS Version 1.3, you may have a

different problem. The installation program places the necessary

assigns in a file named s :user-startup, which is called from

s: startup-sequence. You may have to edit

s: startup-sequence and make some changes. See Chapter 1,

"Installing Your SAS/C Development System," for information on

modifying your startup file.

After switching to Version 6, my old programs will not compile, or

they compile with a lot of warning messages. Why is this happening

and how can I fix it?

There are two solutions:

[] In Version 6, the compiler assumes that your code will provide

prototypes for all functions. (In Version 5, you had to specify the

-cf option for the compiler to identify missing prototypes.) If your

code does not define prototypes for all functions, the compiler may

produce several warning 100, 154, and 161 messages. Specify

196 Appendix 1

ignore= 100+154+161 to suppress these warnings, or use the

genprotos option to generate prototypes for your functions and

#include the resulting header file.

[] Unlike previous versions, the header files and libraries for

Version 6 of the SAS/C Compiler are ANSI-compliant. The ANSI

specifications affect both ANSI and non-ANSI functions and data

names, so some non-ANSI functions and data names have also

changed.

Convert your program to use the new ANSI-compliant libraries

and headers. For any functions mentioned in error messages, read

the description of the function in the SAS/C Development System

Library Reference. This reference manual describes the parameter

list, return value, and necessary header files required by each

function. Make sure that you are including the correct header for

each of the SAS/C or AmigaDOS functions that you are calling.

When I compile, the options I requested do not act as expected.

When you compile your program, whether you compile from the Shell

or the Workbench screen, the compiler looks for an scoptions file

in your current directory. If it does not find one, it looks for the file

ENV: sc/scoptions. If it finds either of these files, it uses any

additional options specified in the file. You can run the scopts utility

or edit the scoptions file to review the options specified in these

files. If you want to prevent the compiler from reading the options

specified in any scoptions file, specify the resetoptions option

as the first option in the sc command. If your program then runs as

expected, you have a problem with the options that you have specified.

If you specify the verbose option, the compiler tells you the location

of the scoptions file used.

During compilation, I get the message semi-colon expected in a

header file.

Check for extra characters at the beginning of your file in front of

your #include statements or in one of your header files. You may

have accidentally pressed a key while starting the editor.

I keep getting the message Error 25: Modifiable lvalue

required, but I am declaring all my variables for a function just like

it says in the library reference manual.

Do not include the const keyword in your declarations. The SAS/C

Development System Library Reference contains many variables defined

with the const keyword, especially pointers to strings. This keyword

is required by the ANSI Standard and indicates that these variables

will not be modified in the library function to which they are passed.

The const keyword is present in the parameter list of the prototype

Solving Common Problems 197

that is found in the associated header file. This prototype, not the

declaration you should include in your program, is what is described

in the synopsis for each function in the SAS/C Development System

Library Reference. Use the synopsis as a guideline for your

declarations, but do not include the const keyword.

Using CodeProbe

I do not get all of the information I expect out of CodeProbe, or

CodeProbe does not know about variables and functions it should

know about.

You may not be compiling with the correct debug option. If you are

compiling with nodebug or debug=line, try compiling with

debug=sf. For a complete description of each debug option, see

Chapter 8, "Compiling and Linking Your Program."

CodeProbe does not work if I double-click on the Debug icon from the

WorkBench screen.

To invoke CodeProbe from the WorkBench screen, click on the Debug

icon. Then, hold down the Shift key and double-click on the icon for

your program's executable module.

Using Formatted Print Functions

printf (or sprintf, fprintf, and so on) does not print the correct

values.

This problem can happen for the following reasons:

[] You are asking printf to print a variable, but the variable

conversion characters are incorrect. For example, you are trying to

print a long integer using %d as the conversion character. A

long variable requires a %ld if the shortint compiler option is

active. Often, if you have one conversion character wrong, the rest

of the line you are printing is also incorrect. Check your entire

printf (or fprintf, etc.) format string carefully.

[] You are trying to print a float or a double, but you have not

linked with the proper math library. You must link with a floating

point math library to perform any floating point operations. If you

are linking with a floating point library, make sure that it is

positioned in your slink command line before sc . lib so that the

linker can find the correct version of printf. If you specify the

link option in the sc command, the compiler links the libraries in

the correct order.

198 Appendix 1

[] You are linking with amiga.lib before the math library and

sc.lib. You should specify amiga.lib as the last library in the

slink command.

Using getchar

getchar does not work as expected.

Input and output on the Amiga system are buffered. On most other

systems, getchar immediately gets a character from stdin (usually

the keyboard). However, the CON: device on the Amiga system buffers

its input, so your program does not actually read any characters until

you do one of the following:

[] fill up the console input buffer

[] press Return

[] enter the Amiga End-of-File character, Ctrl-\.

The SAS/C Development System libraries include two functions that

you can use to deal with this problem:

getch gets a character from the console in RAW mode. The

character is returned as soon as the user types it.

rawcon turns RAW mode on and off. rawcon(1) sets the console

into RAW mode. rawcon (0) restores the console to non-

RAW mode.

When the console is in RAW mode, any characters typed by the user

are passed immediately to the application.

getch returns a single character from stdin just like getchar,

but getch gets the character in RAW mode. If your console is not in

RAW mode, using getch is equivalent to the following sequence:

rawcon(1);

c = getchar();

rawcon(0);

If your console is in RAW mode, getch is equivalent to getchar.

For more information about getchar, refer to SAS/C Development

System Library Reference.

Solving Common Problems 199

Getting Incorrect Results from Function

Calls

My program compiles and links without errors, but I am getting the

wrong results from some of my SAS/C function calls.

You can get incorrect results from a function if you do not include the

correct header files for the function you are calling. The header files

contain prototypes for each of the SAS/C functions, as well as

definitions for many common data structures required by these

functions. By including the correct header file, you are providing the

compiler with a prototype for the SAS/C functions you call.

The ANSI Standard requires that the compiler assume that functions

that are called without the previous inclusion of a prototype return an

int. For example, this means that if you call atof, which returns a

double, without including math . h, the compiler assumes that atof

returns an int and allocates only 4 bytes for the return value. When

atof is called and the correct 8-byte double value is returned in the

4-byte space allocated for it, the value appears to be incorrect.

You may be including the incorrect header file for one of these

reasons:

[] In Version 6, the prototype is contained in a different header file

than in Version 5. For example, in Release 5.10, the function atof

was included in math.h. In Version 6, the atof prototype was

moved to stdlib.h as required by the ANSI Standard. Check the

SAS/C Development System Library Reference for the correct header

file for the functions that you are using.

[] You may be including the right header file from the wrong

directory. For example, the include:dos directory contains many

header files with the same names as those in the root level

include: directory. However, these header files are AmigaDOS

header files and not ANSI header files. The AmigaDOS header files

do not contain the necessary prototypes and data declarations. For

example, you may be including dos /stdio.h instead of

stdio.h. Do not substitute header files from the include:dos

directory for standard headers.

[] You may be including header files from the proto directory instead

of those in the root level include: directory. Although the files in

the proto directory do contain prototypes for many of the SAS/C

functions, these files are intended to be included in addition to the

standard header files, not in place of them. Do not use header files

in include: subdirectories as substitutes for the root level header

files.

200 Appendix 1

Crashing the Machine

My program compiled and linked without any errors, but when I run

it, my machine crashes. What am I doing wrong?

The following list contains some of the more common errors that

crash programs. Most of these errors are caused when your program

accesses memory that it is not supposed to access.

[] You have declared a pointer to an array or structure for which you

have not allocated memory. This mistake is especially easy to make

when calling functions that fill the array or structure with

information, such as the fstat, lstat, and stat functions.

To correct this problem, call malloc or calloc to allocate the

appropriate amount of memory for the array or structure.

[] You have assigned an inappropriate value to a pointer, so the

pointer no longer points to a valid memory space. This type of error

can be quite difficult to track down. You may want to run the

CodeProbe, the Enforcer, or the Mungwall program if you think

these types of errors may occur. Enforcer and Mungwall are

programs that detect memory errors. They are available from

Commodore Applications and Technical Support (CATS) and are

shipped with Version 6.

[] You have specified the nostackcheck option and are overwriting

your stack. Do not specify nostackcheck until your program is

completely debugged. The stackcheck option is the default unless

you are creating a shared library using the libcode option.

Using The asctime Function

I am using the asctime function to convert the time to Greenwich

Mean Time (GMT) correctly, but the result is exactly an hour (or two

or three...) off.

Your machine is probably in the default time zone, Central Standard

Time (CST), and has not been reset to your actual time zone. To

correct the problem, reset your machine's time zone environment

variable to your actual time zone with the following AmigaDOS

command:

setenv TZ=your-time-zone

Solving Common Problems 201

For your-time-zone, enter your zone's standard three letter

abbreviation followed by the number of hours difference between your

time zone and Greenwich Mean Time. For example, for Eastern

Standard Time, the command would be as follows:

setenv TZ=EST5

You can also initialize the _ TZ variable as described in the SAS/C

Development System Libra~y Reference. Initialize the _ TZ variable with

the same time zone data as you would enter with the AmigaDOS

command described above (for example, EST5).

Note: The AmigaDOS environment variable does not have a

leading underscore that the SAS/C data name has.

Managing the Standard 1/0 Window

An annoying window opens when I run my program from the

Workbench screen. How do I get rid of this window?

The SAS/C startup code opens the window to allow programs that are

run from the Workbench screen to access stdin, stdout, and

stderr. You can eliminate this window or change its attributes. For

information on managing this window, see Chapter 9, "Running Your

Program from the Workbench Screen."

Linking Resident Programs or Creating

Resident Libraries

I get the message absolute reference to name from the linker.

You are linking a resident program with the cres . o startup module,

or you are creating a resident library, but the linker detected a

reference to an absolute symbol. Make sure that the symbol being

referenced is not being modified. If the item is not being modified,

then you can ignore the warning message.

202 Appendix 1

Writing Replacement Functions for SAS/C

Library Functions

I wrote a replacement function for one of the SAS/C library routines,

but the library routines don't seem to be using my replacement

function.

If you write a function that has the same name as a library function,

you need to add the __regargs keyword to your function or

compile with the parms=both or parms=register option. For

example, you may want to replace the SAS/C library function malloc

with your own version of malloc. If you compile with the

parms=stack option or define your version of malloc with the

__stdargs keyword, then two versions of malloc are linked into

your executable. If you use other SAS/C library functions that call

malloc, these functions use the version of malloc in the SAS/C

libraries. However, your functions that call malloc use your version

of malloc. To make sure that all calls to malloc are using your

version of malloc, define your version with __regargs or compile

with the parms=both or parms=register option.

Eliminating Informational Messages

How can I turn off all of the informational messages the compiler and

linker produce every time I compile and link?

You can specify the following options on the sc command line:

sc nover link filename.c

203

Appendix 2

Error and Warning

Messages

203 Introduction

203 Using Error and Warning Messages

204 Explanations of Unnumbered Compiler Messages

206 Explanations of Numbered Compiler Messages

258 Explanations of Linker Messages

265 Enabling Suppressed Messages

Introduction

This appendix explains each of the error and warning messages that may

be produced by the compiler and linker.

Using Error and Warning Messages

You should treat warnings as seriously as errors. If you do not know why

a given warning is being produced, find out why. If you can safely ignore

the warning in the future, use the ignore option on the compiler or the

#pragma msg statement to suppress the warning.

In general, the compiler attempts to prevent long cascades of error and

warning messages that result from a single mistake, but this action is not

always possible. As a result, you may see several messages generated by

the same error, especially if the error is in a control statement such as an

if, for, do, or switch statement. If you receive some messages that

seem to be incorrect or confusing, fix as many errors or warnings as

possible, and then recompile your program. The confusing messages may

disappear.

Sometimes the compiler may generate an error message for code that

you believe is correct. In many cases, such errors are the result of

incorrectly using the preprocessor. A typographical error in a

preprocessor macro or accidental collision of a #def ined macro name

with another name in your program can cause very confusing problems.

If you think you are having problems with preprocessor macros, compile

your program with the pponly option to generate preprocessed output,

and check that to see exactly what the compiler is receiving.

Alternatively, compile with the list option to generate a listing file. The

204 Appendix 2

listing file allows you to see exactly what symbols are being defined by

the header files included by your program.

Some error or warning messages are produced at the first non-

preprocessor statement after the actual condition that caused the error or

warning. For example, if your program is missing a semicolon, you do

not get a message at the end of the line that is missing the semicolon; you

get a message at the beginning of the next line of code. If you cannot find

an error exactly where the message occurred, look at several previous

lines in your source code . Remember, the compiler treats #include

files as if they are part of your source file. For example, a missing close

curly brace at the end of your last #include file may result in an error

message at the first line of your C source file. You can compile with the

pponly option to help diagnose this type of error.

By default, many warning messages are suppressed but can be enabled

with the strict, ansi, or warn options. The descriptions of each

message indicate whether the message is suppressed and, if so, which

options enable the message. You can enable any suppressed warning with

the warn or error options. You can disable any warning with the

ignore option. You cannot use the ignore option to disable error

messages. See Chapter 8, "Compiling and Linking Your Program," for

more information about the strict, ansi, error, warn, and ignore

options. See also "Enabling Suppressed Messages" later in this appendix

for a complete list of the suppressed messages and the options you can

use to enable them.

Some messages listed as warnings can also be produced as errors in

some cases. If a message is produced as an error instead of a warning, it

cannot be ignored (just as errors cannot be ignored).

You can display help information on a specific message from the

message browser utility (scmsg) by clicking on the message and pressing

the Help key or by invoking the AmigaGuide utility on the file

sc:help/scmsg.guide.

Explanations of Unnumbered Compiler

Messages

Freeing Resources

If you compile your program and your machine runs low on memory,

the compiler displays this message and frees memory to enable it to

continue the compilation. You can force the compiler to free memory

at any time by pressing Control-F in the window to which the

compiler is sending output.

Error and Warning Messages 205

Floating point overflow optimizing constants

The global optimizer was attempting to perform compile-time constant

calculations, but the calculations caused a floating-point error. Your

code is causing floating-point numbers to overflow.

Can't open type file "name" for mode

The compiler could not open the specified file. The mode is either

read or write.

Combined output filename too long

The filename produced by the compiler, with the path, overflowed the

compiler's internal buffer (255 bytes).

Can't open sc:libs/lib-name.library

The specified shared library could not be found. Make sure the library

is available in sc:libs.

CXWRN: text

An internal error occurred. With CXWRN errors, the compiler attempts

to continue the compilation, but may not be able to do so. Please

contact the Technical Support Division.

CXERR: num

An internal error prevented the compiler from continuing. Please

contact the Technical Support Division.

Can't delete old GST: object is in use

Continuing with no GST file

You specified the makegst option, but an existing copy of the same

GST was in use by another program. Check for other compilations that

are using the GST. You may also be browsing the GST with the

hypergst utility.

Can't open GST file: gst-filename

The specified GST file could not be loaded. Either the file is an invalid

GST file, or the file does not exist.

Invalid symbol definition: symbol-name

You attempted to define the specified symbol on the command line

with the define compiler option, but the symbol did not adhere to

the normal rules for C preprocessor symbol syntax.

Seek error on object file

The compiler attempted to perform a seek operation on the output

object file but encountered an I/O error.

I/O error code on file "name"

The compiler received the specified I/O error code from the operating

system while attempting to read the named file. Refer to The

AmigaDOS Manual, 3rd Edition (Commodore-Amiga, Inc. 1991) or see

the header file dos/dos.h for details on the numeric error codes.

206 Appendix 2

Explanations of Numbered Compiler

Messages

Warning 1: invalid preprocessor command

This warning is generated by invalid use of preprocessor commands.

For example, you could specify an unrecognized command, fail to

include a space between command elements, or use an illegal

preprocessor symbol. The command is ignored and compilation

continues.

Error 2: unexpected end of file

This error is generated when the compiler expects more data, but it

encounters the end of an input file. This error may occur in a

#include file or in the original source file. A missing #endif or

unbalanced curly brace or parentheses in the source file or in one of

the previously included files may produce this message. In many cases,

correcting a previous error eliminates this error.

Error 3: file not found "filename"

The filename specified in a #include command was not found or

could not be opened.

Error 4: invalid lexical token

A character was found in the file that is not a standard character in the

C character set or is in an inappropriate place. For example, entering a

pound sign (#) in the middle of non-preprocessor C code or entering

nonprintable control characters anywhere except in a comment

produces this error.

Error 5: invalid macro usage

Your code invoked a macro incorrectly. Check for unbalanced

parentheses and other syntax errors. The problem may be in a macro

used by the macro that you invoked in your program.

Error 6: line buffer overflow

A line of preprocessed input was longer than the line buffer size. The

size of the line buffer is controlled by the ppbuf and memsize

options. If you do not specify ppbuf or memsize, the size of the line

buffer is 8192 bytes.

Error and Warning Messages 207

Error 8: invalid conversion

You attempted to cast a type to an incompatible type. This error usually

occurs when you attempt to convert something into an array, a

structure, or a function. Check for missing indirection (*) and/or

address (&) operators. For example, the following program tries to

assign a whole structure to a pointer.

void main ( void )

{

struct FOO

{

int a, b;

} f;

struct FOO *p;

p = f; /* Error 8 */

p = &f; /* Correct */

}

Error 9: undefined identifier "name"

The specified identifier has not been declared. You may not have

included the proper header files to declare an extern, or you may

have misspelled the name of a variable. This message is produced only

once for each undeclared identifier. Subsequent uses of the identifier do

not produce a message. Subsequent declarations of the identifier may

produce messages about redeclaring the variable. Fix the error that is

causing the first error 9 message and recompile your program before

trying to fix additional messages involving the same variable.

Error 10: invalid subscript expression

An error was detected in an expression used inside square brackets ([]).

This error may occur if:

[] the expression is missing

[] the expression is a preprocessor macro that evaluates to nothing

[] the result of the expression is void

[] the result of the expression is a pointer, a structure, or a union.

Error 11: string not terminated

The closing double quote (") was not provided when defining a string.

208 Appendix 2

Error 12: invalid structure reference

The operand preceding the structure member ( . ) or structure pointer

(->) operator is not a structure or a pointer to a structure, respectively.

Make sure you are not trying to reference a structure member with the

structure pointer operator or a structure pointer with the structure

member operator. In many cases, correcting a previous error eliminates

this message.

Error 13: member name missing

The name of the desired structure or union member did not follow the

structure member operator ( . ) or the structure pointer operator (->).

Check for preprocessor macros that may be defined to the same name

as the member.

Error 14: undefined member "name"

The indicated identifier is not a member of the structure or union to

which the structure member operator ( . ) or the structure pointer

operator (->) referred.

Error 15: invalid function call

An identifier or constant is used where a function or function pointer

identifier is required. This message can occur if you attempt to use a

variable not declared as a function or function pointer but give the

variable a parameter list. The compiler sees the parenthesized

expression and thinks you are calling a function. Check for

typographical errors such as leaving out an operator in an expression,

which produces a variable and a parenthesized expression. Such

typographical errors may also occur in preprocessor macros. For

example:

/* The incorrect expression below generates an */

/* "invalid function call" error. */

int i, j;

void function(void)

{

i = i + (j*2); /* Intended expression */

i = i (j*2); /* INCORRECT - deleted "+" operator */

Error and Warning Messages 209

Error 16: invalid function argument

A function argument expression following the left parenthesis of a

function call is invalid. You may see this message if you omit:

[] an argument expression

[] a right parenthesis from a function call

[] a comma separator between two function arguments.

For example:

func(.);

func(;

func(,1);

Error 17: too many operands

During expression evaluation, the end of an expression was

encountered, but more than one operand was still awaiting evaluation.

This message may occur if an expression contained an incorrectly

specified operation.

Warning 18: non-ANSI use of operator in preprocessor condition

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=18 options. The ANSI Standard states that

the sizeof and comma (, ) operators should not be used in

preprocessor conditions. The SAS/C Compiler supports their use in

preprocessor conditions, but programs that require strict adherence to

the ANSI Standard should not use them.

Error 19: unbalanced parentheses

The number of opening parentheses in an expression did not equal the

number of closing parentheses. If the expression appears correct in the

C source file, check any preprocessor macros to make sure they

generate balanced parentheses.

Error 20: invalid constant expression

An expression that did not evaluate to a constant was encountered in a

context that required a constant result. The compiler must be able to

evaluate any constant expression (for example, expressions used to

initialize static or external data) when the program is compiled.

The expression in question did not meet this criterion. You may have

used an illegal operator for a constant expression (such as ++, +=,

function calls, and so on), or you may have used a variable whose value

is available only at run time.

210 Appendix 2

Error 21: illegal use of struct, union, or array type

An identifier declared as a structure, union, or array was encountered

in an expression where such types are not permitted. For example, you

cannot use the ++ postincrement operator with a structure:

struct FOO

{

int a, b, c;

} f;

f++; /* Error 21 */

Warning 22: structure used as function argument

This message is suppressed by default, but you can enable it with the

warn=22 option. A structure or union was passed as an argument to a

function. Although passing structures and unions is legal according to

the ANSI Standard, some compilers do not allow you to pass structures

or unions. Other compilers pass a pointer to the structure instead of the

entire structure. Turn on this warning if your code comes from or must

be ported to such a compiler.

Error 23: invalid use of conditional operator

The conditional expression operator (?: ) was used incorrectly. You may

have included the question mark (?) but left out the colon (:). Also,

check for an invalid expression after the operator.

Error 24: pointer operand required

An expression required a pointer at a specific place, but a non-pointer

operand was provided. The compiler may generate this message if an

expression after the indirection operator (*) was not a pointer or array

expression or if the expression before the array indexing operators ( [ l )

was not a pointer or array expression.

Error 25: modifiable lvalue required

You have attempted to assign a value to an expression that cannot be

modified. An Ivalue is any expression that can appear on the left side of

an assignment operation. For example, the ANSI Standard states that

the result of a cast is not an lvalue; therefore, the following statement is

invalid:

long x;

(short)x = 2; /* Error 25 */

Error and Warning Messages 211

The following examples also generate this error message:

#define ADDONE(x) (x)++

ADDONE(12); /* Error 25: Cannot increment a constant */

ADDONE(&g); /* Error 25: Cannot assign to an address */

if(func(10)=j-2); /* Error 25: "==" was intended, not "=" */

&x = &y; /* Error 25: Cannot assign to an address */

You may have defined a variable with the const keyword and then

tried to modify the value of that variable. The SAS/C Development

System Library Reference, Version 6.0 contains many variables defined

with the const keyword, especially pointers to strings. This keyword is

required by the ANSI Standard and indicates that these variables will

not be modified in the library function to which they are passed. The

const keyword is present in the parameter list of the prototype that is

found in the associated header file. This prototype, not the declaration

you should include in your program, is what is described in the

synopsis for each function in the SAS/C Development System Library

Reference. Use the synopsis as a guideline for your declarations, but do

not include the const keyword.

Error 26: arithmetic operand required

An expression required an arithmetic operand but the provided operand

was not arithmetic. An operand is arithmetic if it declared as char,

short, int, long, float, or double or the signed and unsigned

variants of these types.

Pointers, structures, unions, and functions are not arithmetic operands.

Error 27: arithmetic or pointer operand required

An expression required an arithmetic or pointer operand, but a

structure or union was provided. An operand is arithmetic if it declared

as char, short, int, long, float, or double or the signed and

unsigned variants of these types.

A pointer operand can be a pointer to any other data type, or it can be

the address of a variable or function.

212 Appendix 2

Error 28: missing operand

During expression evaluation, the end of an expression was encountered

but not enough operands were available for evaluation. The compiler

may generate this message if you specified a binary operator (such as

the addition, subtraction, multiplication, or division operator) with only

one operand. Also, check for invalid preprocessor macro expansions.

For example:

int i;

int ary[10];

i = i + ; /* Error 28 */

i = ary[i*]4; /* Error 28 (Among others) */

Error 29: operation cannot be performed on a pointer

An operation was specified that was invalid for pointer operands, such

as one of the arithmetic operations other than addition or subtraction.

Warning 30: pointers do not point to same type of object

In an assignment statement defining a value for a pointer variable, the

expression on the right side of the assignment (=) operator did not

evaluate to NULL or to a pointer of the same type as the pointer

variable on the left side of the assignment operator. The warning is also

produced when a pointer of any type is assigned to an arithmetic object.

Error 31: integral operand required

An expression required a given operand to be an integral type, but the

actual operand was not an integral type. An operand is integral if it is

declared as char, short, int, or long or the signed and unsigned

variants of these types.

For example, the following code generates error 31:

double d;

int ary[10];

ary[d] = 10; /* Error 31 */

Error and Warning Messages 213

Error 32: cannot convert to required type

The compiler was unable to convert a data item from its base type to

the type required by the operation. The compiler may generate this

message if you attempt to cast any data type to a structure, instead of

casting the type to a pointer to a structure, or if you attempt to cast a

structure to any other type. This message can also be produced for

implied conversions, such as passing a structure as a parameter to a

function expecting some other type. For example, the following code

generates error 32:

struct FOO f;

int j;

j = (int)f; /* Error 32 */

Warning 33: non-portable operation on structure or union

Your code has attempted to use an operator on a structure or union

that is illegal for that type. For example, you may have used the

equality == operator on two structures. The ANSI Standard does not

permit the use of relational operators on structures or unions.

The SAS/C Compiler generates the equivalent of a memcmp call for

this construct, but it may not perform as expected. Because structures

may contain padding bytes, two structures of the same type with all

identical members may compare false. If you intend to use direct

structure comparison, make sure you declare the structure static or

extern, or initialize the structure to zeroes using a call to memset.

For example, the following code generates warning 33:

#include <proto/dos.h>

struct FileInfoBlock fib1, fib2;

if(fib1 == fib2) /* Warning 33 */

Error 34: invalid initializer expression

The expression used to initialize an object was invalid. The compiler

may generate this message if you fail to separate elements in an

initializer list with commas or if you attempt to initialize an array to a

single object, as shown in the following examples:

int a[3] = 0; /* Error 34 */

int b[3] = { 1 2 3 }; /* Error 34 */

214 Appendix 2

Error 35: closing brace expected

The compiler expected a closing brace (}) to terminate the definition of

a function, structure, or nested block scope, but the brace is missing.

The compiler may generate this message if:

[] too many elements occur in an initializer expression list

[] a structure member was improperly declared

[] the end of the source file is reached before a definition is complete

[] a previous error occurred in a control statement.

Warning 36: control cannot reach this statement

A statement with no label followed a goto, return, break, or

continue statement. The statement is therefore unreachable. This

warning can sometimes be produced incorrectly if the compiler reported

a previous error while in a control flow statement. Fix all previous

errors and recompile your program before trying to fix the error that is

generating this message.

Error 37: duplicate statement label "name"

See line number in file "filename"

The specified statement label has already been defined in the current

function. You cannot define the same label more than once in the same

function.

Error 38: unbalanced braces

In a set of compound statements, the number of opening left braces ({)

did not equal the number of closing right braces (}). This warning may

be produced incorrectly if the compiler reported a previous error in a

control flow statement. Fix any previous errors and recompile your

program before trying to fix the error that is generating this message.

Error 39: invalid use of keyword "keyword"

One of the C language reserved words appeared in an invalid context

(for example, as a variable name).

Error 40: break not inside loop or switch

A break statement was detected that was not within the scope of a

while, do, for, or switch statement. This error may be produced

incorrectly because of errors in previous statements.

Error 41: case not inside switch

A case prefix was encountered outside the scope of a switch

statement. This error may be produced incorrectly because of errors in

previous statements.

Error and Warning Messages 215

Warning 42: case expression not integral

The expression defining a case value did not evaluate to an integral

constant. This message is generated as an error message if the

expression could not be converted into an integral constant and as a

warning if the expression could be converted into an integral constant.

For example, if you use a variable as a case value, the compiler

generates an error message. If you use a floating-point constant as a

case value, the compiler converts the constant to an integer

(thereby truncating its value) and generates a warning message. For

example, in the following code, the case value 1.6 is truncated to 1,

and the value -1.6 is truncated to -1.

switch(i)

{

case 1.6: /* Warning 42 */

break;

case -1.6: /* Warning 42 */

break;

}

Error 43: duplicate of case value See line number in file

"filename"

You have used the same case value more than once within the same

switch statement. Check for possible preprocessor macro definitions

that expand to the same value. For example, both of the following case

statements evaluate to zero:

#define FOO 0

#define BAR 2

switch(i)

{

case FOO:

break;

case (FOO*BAR): /* Error 43 */

break;

}

216 Appendix 2

Error 44: continue not inside loop

A continue statement was detected that was not within the scope of a

while, do, or for loop. This error may be produced incorrectly

because of errors in previous statements.

Error 45: default not inside switch

A default label was encountered outside the scope of a switch

statement. This message may be produced incorrectly because of errors

in previous statements.

Error 46: duplicate default See line number in file

"filename"

A default label was encountered within the scope of a switch

statement in which a default label had already been encountered.

Error 47: while missing from do statement

A while clause did not follow the body of a do statement. This

message may be produced incorrectly because of errors in previous

statements.

Error 48: invalid while expression

The expression defining the looping condition in a while or do loop

was void or was missing. If you intend for a loop to be infinite, you

must supply a constant (such as 1) for the while condition. The error

may be produced because of a preprocessor macro that expands to

invalid code. In many cases, fixing a previous error eliminates this

message.

Error 49: else not associated with if

An else keyword was detected that was not in the scope of a

preceding if statement. This message may be caused by an error in a

preceding statement, especially if the previous error occurred while

processing the if statement with which the else statement is

associated.

Error 50: label missing from goto

The compiler expected a statement label to follow the goto keyword

but the label was missing. This message may be produced incorrectly

because of errors in previous statements.

Error and Warning Messages 217

Warning 51: C++ comment detected

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=51 options. In C++, comments begin with

two slashes (//) and terminate at the end of the line on which they

begin. The SAS/C Compiler accepts comments entered in this way for

convenience and for compatibility with other implementations, but they

are not part of the ANSI Standard for the C language.

Error 52: invalid if expression

The expression following the if keyword on an if statement was

void, invalid, or missing. This error may be caused by a preprocessor

macro expanding to inappropriate values or may be the result of an

expression with an invalid return type (such as a structure type). In

many cases, fixing a previous error eliminates this message.

Error 53: invalid return expression

The expression following the return keyword was void, invalid, or

missing. The compiler may generate this message if a preprocessor

macro expands to inappropriate values. In many cases, fixing a previous

error eliminates this message.

Warning 54: switch expression not integral

The expression defining the test value for a switch statement did not

define an integral value as required by the ANSI Standard. The value

supplied is converted to int before any attempt is made to use it. If the

switch value is a floating-point value, this conversion may truncate

the value. This warning can also be generated as an error if the value

could not be converted to int.

Warning 55: no case values for switch statement

The statement defining the body of a switch statement did not define

any case statements. This warning may be produced incorrectly

because of previous errors.

Error 56: colon expected

The compiler expected but did not find a colon (:). This message may be

generated if a case expression was improperly specified or if the colon

was omitted following a label to a statement. Because the compiler scans

through newlines, blanks, and comments looking for the colon, this

message is usually produced at the beginning of the line following the

actual error.

218 Appendix 2

Error 57: semi-colon expected

The compiler expected but did not find a semi-colon (;). This error can

be generated if you use too many right parentheses or right curly braces

(}). Because the compiler scans through spaces and tabs looking for the

semicolon, this message is usually produced at the beginning of the line

following the actual error.

Error 58: missing parenthesis

A required parenthesis is missing. This error is often caused by

previous errors.

Error 59: invalid storage class

Possible storage classes are denoted by the keywords __near, __far,

__chip, register, auto, extern, and static. Some of these

keywords are invalid for certain types of data. For example, you cannot

declare an external variable with the register keyword, and you

cannot declare an automatic (local) variable with the __chip,

__near, or __far keywords. Your code attempted to use a storage

class keyword incorrectly. This error often occurs because of previous

errors.

Error 60: incompatible struct, union or array types

Incompatible structure, union, or array types were used in an

expression.

struct A {int x;} a;

struct B {double d;} b;

a = b; /* Error 60 */

Error 61: undefined struct/union tag "tag-name"

Your code has used a structure or union tag that has not been declared.

Check for misspelled structure names. You may want to compile your

program with the pponly option or the list option and look at the

output produced.

Warning 62: constant number out of range for type "type"

Valid range is low to high

Error and Warning Messages 219

The constant value indicated is not in the range of possible values for

the type to which the value is being assigned. This message may occur if

you are assigning a hexadecimal constant with the uppermost bit set to

a signed variable. By definition, a hexadecimal constant is a positive

value; therefore, the assignment to the variable reinterprets the constant

as a negative number. For example, the following lines generate

warning 62:

signed char c = 0x80; /* Warning 62 */

short s = 100000; /* Warning 62 */

unsigned short uc = -1 /* Warning 62 */

Unless you use the unschar compiler option, variables of type char

are signed and produce this warning if you assign any constant to them

with the high bit set (that is, any value between 128 and 255.) You can

suppress this warning for a specific case by casting the constant to the

appropriate type.

Out-of-range constants can cause problems in your code that are hard

to debug. For example, the following code does not behave as intended:

int i = 1xff;

signed char c = 1xff; /* Warning 62 */

if(i == c)

{

/* Not executed */

}

The constant initializer Oxf f is the decimal number 255. When

assigned to the integer variable i, this value is preserved, and i gets

the value 255. When assigned to the signed character variable c, the

value of c becomes -1 because a signed character cannot represent

numbers higher than 127, and the constant Oxf f overflows. Therefore,

the comparison in the if statement results in the value false.

Warning 63: item "name" already declared

See line number file "filename"

The named item was previously declared at the cited location. This

warning is produced when two different members of the same

structure, union, or enum are given the same name.

220 Appendix 2

Error 64: structure contains no members

A structure declaration did not contain any members. This error can be

produced by errors encountered during the structure's declaration.

Fixing a previous error may eliminate this message.

Error 65: invalid function definition

Your code tried to define a function body inside another function body,

inside a structure declaration, or inside a list of static initializers. This

message may be produced incorrectly because of errors in previous

statements.

Warning 66: invalid array limit expression

The expression defining the size of the subscript in an array declaration

did not evaluate to a positive integral constant. For example:

int x[10.7];

Error 67: illegal object

Your code attempted to define an illegal item. For example, you may be

declaring an array of functions (instead of an array of function pointers)

or a function that returns an array (instead of a function that returns a

pointer). This message can also be produced if you attempt to define a

variable with the same name as a keyword. For example, the following

code generates error 67:

int break; /* Error 67 */

long while; /* Error 67 */

Error 68: illegal object for structure

A structure (or union) included a function as a member. You cannot

include a function as a member of a structure or union, although you

can include a function pointer.

Error 69: struct name includes instance of self

The named structure or union contains an instance of itself. Although it

is legal for a structure or union to include a pointer to its own type, the

structure or union cannot contain an instance of itself. If the structure

Error and Warning Messages 221

or union does not have a name, the name field is not printed in the

message. For example, the following code generates error 69:

struct FOO

{

int a, b, c;

struct FOO x; /* Error 69 */

};

Warning 70: unrecognized escape sequence

By default, this message is suppressed, but you can enable it with the

strict, ansi, or warn=70 options. Escape sequences in string and

character constants begin with a backslash (\) and contain one or more

characters after the backslash. The ANSI Standard defines some escape

sequences and reserves others for future expansion and for

implementation-defined extensions. The SAS/C Compiler ignores the

backslash on any such undefined escape sequences. Other compilers

may take different action. For example, the following line prints the

character q followed by a newline (\n) to stdout:

printf("\q\n"); /* Warning 70 */

Other ANSI-conforming compilers may substitute any other character for

the \q escape sequence.

Error 71: formal declaration error "name"

A variable was declared before the left curly brace of in an old-style

function definition, but the variable did not appear in the list of

identifiers in parentheses following the function name. For example, the

declaration of j in the following code generates error 71:

int func(i)

int i;

int j; /* Error 71 */

{

}

You may have misspelled one of your formal parameters or forgotten to

add the parameter to the parameter list.

222 Appendix 2

Error 72: conflict with previous declaration

See line number file "filename"

A variable or function was declared that conflicts with a previous

declaration for the variable or function in the same scope. The message

indicates the filename and line number of the original declaration. If no

prototype exists for a function, the first use of that function implicitly

declares the function as returning an int. If the actual definition of the

function follows the first use of the function and declares a different

return type, the compiler produces this message. This message may be

produced incorrectly if you forget to declare a variable in an earlier

location and, therefore, received a previous error message about an

undefined identifier with the same name. Fixing the previous error may

eliminate this message.

Warning 73: declaration expected

The compiler expected to find the declaration of a data object or

function but did not. This message can also occur if you enter too many

or too few curly braces. This message may be produced incorrectly

because of errors in previous statements. Fixing the previous errors

may eliminate this message.

Warning 74: initializer data truncated

A static initializer expression contained more elements than the data

item being initialized, as in the following example:

char b[3] = "abcd"; /* Warning 74 */

String constants always have an implied NULL byte at the end. This byte

is not counted when producing this warning. If you have a character

array with three elements, you may initialize it as follows:

char b[3] = "abc";

Error and Warning Messages 223

The three elements receive the values a, b, and c. If there is room, the

NULL terminator byte is also copied:

char c[4] = "abc";

The elements of the above array are assigned the values a, b, c, and \0.

Error 75: invalid sizeof expression

The expression passed to the sizeof operator was invalid. This

message may be produced if an attempt is made to take the size of a

function, bitfield, or incomplete type, or if the result of the expression

used is of type void. For example, in the following code, a is an

incomplete type because its size is not specified when it is declared:

extern int a[];

int i;

i = sizeof(a); /* Error 75 */

Error 76: left brace expected

The compiler expected but did not find an opening left brace. For

example, you may have omitted the opening brace on a list of initializer

expressions for an aggregate.

Error 77: identifier expected

The compiler expected to find the name of an identifier to be declared.

The compiler may generate this message if the prefixes to an identifier

in a declaration (parentheses and asterisks) are incorrectly specified or

if a sequence of declarations is listed incorrectly, as in the following

example:

int ; /* Error 77 */

Error 78: undefined statement label "name"

A goto statement referred to the named label, but the label does not

exist in the function that referred to it. Check the spelling of your label

and the goto reference. Make sure the label is in the same function as

the goto statement.

224 Appendix 2

Warning 79: duplicate of enumeration value

See line line file "file"

When declaring an enumeration type, more than one enumeration

constant was assigned the same value, as in the following example:

enum COLORS

(RED=1, BLUE=2, GREEN=1); /* RED and GREEN are identical */

Any enumeration constants that are not assigned an explicit value are

assigned values one higher than the previous constant in that

enumeration. If the constant is the first constant in that enumeration, it is

assigned the value zero. Therefore, the following enum generates

warning 79:

enum COLORS (RED, BLUE, GREEN=1); /* Warning 79 */

RED is the first constant, so it is assigned a value of 0. BLUE is assigned

a value of 1. GREEN is explicitly assigned a value of 1, which conflicts

with BLUE.

Error and Warning Messages 225

Warning 80: invalid bit field or misplaced ':'

This warning is commonly produced if you type a colon (:) when a

semicolon (;) was expected. This warning can also be produced if you

are actually declaring a bitfield and give an improper expression for the

number of bits in the bitfield.

Error 81: preprocessor symbol loop; macro expansion too long

or circular

When using the oldpp compiler option, a preprocessor symbol

expanded to a value that contains a circular reference back to the

symbol itself, thereby creating an infinite loop in the preprocessor.

Check the definition of the macro being expanded on the line in

question. This message cannot occur if the oldpp compiler option is

not used because the ANSI Standard prohibits the expansion of

preprocessor macros that occur as a result of expanding a previous

instance of the same macro.

Error 82: maximum object/storage size exceeded

Your code attempted to declare a data item that exceeded the maximum

size of objects in its storage class, or the last object declared caused the

total size of declared objects in that storage class to exceed the

maximum, as in the following example:

char __near a[30000];

char __near b[30000];

char __near c[30000];

Because there is a limit of 32767 bytes on the amount of near data

allowed, the above request for 90000 bytes of near data will not work. If

you are compiling with data=near (the default), the __near keyword

is implied on all data items. Fix this warning by declaring some large

data items with the __far keyword or by compiling with the data=far

option.

226 Appendix 2

Warning 83: reference beyond object size

Your code used an address beyond the size of the object used as the

base for the address calculation. This warning usually occurs when you

refer to an element beyond the end of an array, as follows:

char c[10];

void myfunc(void)

{

c[11] = 0; /* Warning 83 ~/

}

This message can be produced only when the compiler can determine the

value of the subscript at compile time, that is, the subscript is a constant.

Warning 84: redefinition of pragma or preprocessor symbol

"name"

See line number file "filename"

Your code is redefining the preprocessor symbol or #pragma originally

defined at the indicated file and line number.

Warning 85: return value mismatch for function "name"

Expecting "typel", found "type2"

The expression specifying the value to be returned from a function was

not the same type as the function itself. If possible, the value specified is

converted to the appropriate type. You can suppress this warning by

casting the return expression to the appropriate type.

Some pre-ANSI C code produces many of these warnings when

functions declared as int (either explicitly or implicitly) do not return

a value. Before the ANSI committee approved the void keyword,

declaring functions as returning an int was the correct way to handle

functions that returned nothing. You can compile with the

nowarnvoidreturn option to suppress these warnings when a

function that is declared as returning an int actually returns nothing.

For example, the following two functions generate warning 85:

functionl (x)

int x;

{

} /~ Warning 85 ~/

int function2(x)

int x;

Error and Warning Messages 227

{

char *p = NULL;

return(p); /* Warning 85 */

}

You can suppress the warning 85 for functionl by compiling with the

nowvret option. The nowvret option does not affect function2,

which is attempting to return a pointer from a function declared as

returning int.

Warning 86: formal parameters conflict with prototype

See line number file "filename"

The types of the parameters to the function do not match the types

given in the prototype for the function. Check the prototype at the file

and line indicated against your definition.

Warning 87: argument count incorrect, expecting number

arguments

See line number file "filename"

Your code invoked a function with an incorrect number of arguments,

according to that function's prototype. Check the prototype at the

indicated file and line number against your usage of the function and

the actual function definition.

Warning 88: argument type incorrect

Expecting "type 1", found "type2"

Your code invoked a function with an argument whose type conflicts

with the corresponding parameter as declared in the function's

prototype. The type of the argument expected is given as type 1, and

the type of the argument actually provided is type2. If possible, the

argument is converted to the appropriate type as if it were cast to that

type. If the argument cannot be converted, an error message is

produced.

228 Appendix 2

Warning 89: constant converted from "type1" to "type2"

Your code supplied a constant that conflicted with the expected type.

The constant was converted, but the conversion may have caused a loss

of precision or lost values. For example, in the following code, the

prototype for the function f oo specifies an int, but the function is

passed a double constant:

void foo(int);

void myfunc(void)

{

foo(l0.67); /* Warning 89 */

}

The double constant is converted to an integer, resulting in an integer

argument of 10, and the compiler generates warning 89 to inform you of

the conversion.

Error 90: invalid argument type specifier

An error was made in declaring an argument in a function or prototype

declaration. For example, the following declaration does not specify a

type for the parameter y. For example:

void foo(int x, y) /* Error 90 */

{

}

Error 91: illegal void operand

One of the operands in an expression was of type void. The void type

represents no value and is, therefore, illegal in most expressions.

Warning 92: statement has no effect

An expression statement did not produce an assignment, function call,

or other action. Such a statement serves no useful purpose and can be

eliminated. This warning is often generated when a typographical error

has been made in coding the statement. For example, you might enter

Error and Warning Messages 229

the equality (==) operator when you intended to enter the assignment (=)

operator:

int i;

i == 5; /* Warning 92 */

In this example, the user intended to assign the value 5 to the integer

variable i, but because of the extra equals sign, the statement does

nothing.

Warning 93: no reference to identifier "name"

Your code declared an automatic (local) variable but never used the

variable. However, the variable might be used by code that has been

excluded from the object module with #if or #ifdef statements.

Warning 94: uninitialized auto variable "name"

An automatic (local) variable was used in an expression before it was

given a value. Automatic variables are not guaranteed to have any

specific value when a function is entered, so an uninitialized automatic

variable can create seemingly random bugs. It is possible for this

warning to not be produced when appropriate or to be produced

incorrectly because the compiler does not check all possible execution

paths. In rare cases, the message is produced incorrectly if the variable

is used in a loop construct and initialized later in the same loop

construct, as shown:

void myfunc(void)

{

int i, j;

for(i=0; i<10; i++)

{

if(i > 0) printf("%d\n", j); /* Warning 94 */

j = i;

}

Without doing detailed loop analysis, the compiler cannot tell that j is

not referenced by the call to printf until after it is initialized.

230 Appendix 2

Some cases that use uninitialized variables may not produce the

warning. For example, no warning is produced for the following code

even though j is not initialized if x is greater than S:

void myfUnc(int x)

{

int j;

if(Y < 5) j = X;

if(j < 5) /* j might be uninitialized */

{

...

}

warning 95: unrecognized #pragma operand

The keyword following a #pragma statement was not recognized as a

SAS/C pragma keyword. Version 6 of the SAS/C Compiler supports the

libcall, flibcall, syscall, tagcall, andmsg #pragmas.

Error 96: missing name for #pragma

In a libcall, flibcall, syscall, or tagcall #pragma

statement, the name of the routine to be called was omitted or

incorrect.

Error 97: bad library base for #pragma

In a libcall, flibcall, or tagcall #pragma statement, the

library base was omitted or incorrect.

Error 98: invalid data for #pragma

In a libcall, flibcall, syscall, or tagcall #pragma

statement, the offset or magic number fields were invalid. In a #pragma

msg statement, a syntax error was made specifying the message number

or the action to be taken.

Error 99: attempt to change a const lvalue

Your code attempted to modify a variable declared with the const

keyword. Variables declared with the const keyword are read-only and

cannot be modified.

Error and Warning Messages 231

Warning 100: no prototype declared for function "name"

Your code called the named function, but the compiler did not find a

prototype for that function. Without a prototype, the compiler cannot

perform parameter type checking. Remember, a function that takes no

parameters still needs a prototype with void as its parameter list:

int func(void); /* "func" returns "int" and takes no parms */

If the function is a SAS/C function, the SAS/C Development System

Librar,v Reference tells you which header file to #include to get the

correct definition for the function. If the function is an AmigaDOS

function, its prototype is in the include: clib directory in the file for

its library. For more information, you can refer to the Amiga ROM Kernel

Reference Manual: Libraries, 3rd Edition (Commodore-Amiga, Inc. 1992)

or use the grep command to search the header file in the

include: clib directory for the prototype.

Error 101: redundant keywords in declaration

The same storage class keyword was specified multiple times when

declaring a variable, function, or prototype. For example, you may have

specified the const or __chip keyword twice.

However, you can specify a typedef with a storage class keyword.

Any variables declared with this typedef are automatically assigned to

that specified storage class. Therefore, you may get an error 101 for

specifying the keyword explicitly on a variable declared with the

typedef, as in the following example:

typedef int __far farint;

farint x; /* Declares a far integer called "x" */

farint __far y; /* Error 101 */

Error 102: conflicting keywords in declaration

You have specified two mutually incompatible storage class keywords

when declaring a variable, function, or prototype. For example, you

may have specified the __near and __far keywords on a variable

definition.

However, you can specify a typedef with a storage class keyword.

Any variables declared with this typedef are automatically assigned to

that specified storage class. Therefore, you may get an error 102 for

232 Appendix 2

specifying a keyword explicitly on a variable which conflicts with the

keyword declared with the typedef, as in the following example:

typedef int __far farint;

farint x; /* Declares a far integer called "x" */

farint __near y; /* Error 102 */

Warning 103: uninitialized constant "[name]"

The named variable was declared const, indicating that the variable is

read-only, but you have not initialized the variable. If the variable is

declared static or extern, it is initialized to zero for you but is

probably not useful unless explicitly initialized.

Warning 104: conversion from pointer to const/volatile to

pointer to non-const/volatile

A pointer to a const or volatile object is being converted to a

pointer to a normal object. For example, you may be passing the

address of a const variable to a function that takes a normal pointer.

After the pointer has been converted, the const or volatile

attribute is lost. Therefore, your const data might get modified, or

your volatile data might be kept in a register.

Error and Warning Messages 233

In the following example, warning 104 is produced when the function

foo is called with the const array data as an argument.

void foo(char *);

void myfunc(void)

{

const char data [] = "Hello, World!\n";

foo(data); /* Warning 104 */

printf("%s\n", data);

}

void foo(char *p)

{

P[1] = 'a';

}

The function foo actually modifies its data by writing to it. Therefore,

printf prints the value Hallo, World! instead of Hello, World !

because the constant array has been modified.

234 Appendix 2

Warning 105: module does not define any externally-known symbols

The C source file and all of its included headers were compiled, but no

externally-visible functions or data items were defined. In this case, a

valid object file is produced, but it contains nothing that can be

accessed, and the file can removed from your link step if you desire.

Error 106: postfix expression not allowed on a constant

Your code attempted to apply a postfix ++ or--operator to a constant.

This message may be generated because of an incorrect macro

expansion. You can use the pponly option to generate a preprocessed

file and check the macro expansion.

Error 107: too many initializers

A data item was being initialized, but too many initializer elements were

provided, as in the following example:

struct FOO

{

int i, j;

};

struct FOO foo = {10, 20, 30}; /* Error 107 */

Warning 108: zero-length arrays are not an ANSI feature

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn= 108 options. You have declared an array of

size zero, probably as a member of a structure to allow variable-sized

structures. While using zero-length arrays is a common extension to the

ANSI Standard and is supported by the SAS/C Compiler, the ANSI

Standard does not allow the use of zero-length arrays.

Error 109: invalid use of type name or keyword

A type name (possibly a typedef) has been encountered where it was

not expected. You may have attempted to declare a variable with the

same name as a keyword.

Error and Warning Messages 235

Warning 110: enum constant expression is wrong type

Expecting "type1", found "type2"

An enumeration constant value was explicitly assigned that did not

match the type of the enum being declared. For example, specifying a

double constant when defining an enum or specifying a long constant

when the shortint option is active will generate this message.

Example:

enum COLORS { RED=1.0 }; /* Warning 110 */

Warning 111: non-portable enum type specified

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn= 111 options. As an extension to the ANSI

Standard, the SAS/C Compiler supports short, char, and long

enum types with the syntax short enum, char enum, and long

enum. To improve the portability of your code, enable this warning.

Warning 114: negative shift or shift too big for type

shifts for type "type" must be between O and nUmber

bits

Your code attempted to shift an integral value by a constant number of

bits, but the constant was either negative or higher than the number of

bits in the value being shifted, as shown in the following examples:

int i = l;

i = i >> 33; /* Warning 114 */

i = i << -l; /* Warning 114 */

In the first example, i is 32 bits (an int) but is being shifted 33 bits.

Shifting a value by a number of bits higher than the number of bits in

the value generates a zero for the result. In the second example, i is

being shifted by a negative number of bits. Attempting to shift a value

by a negative number of bits usually generates a zero for the result

(although this result is undefined by the ANSI Standard).

Error 115: enum constant value "number~ out of range for enum

type

Your code specified a value for an enum constant while defining an

enumerated type which is out of range for the type of enum being

declared. Remember that enum constants that are not explicitly assigned

a numerical value are given the value of the previous constant defined

236 Appendix 2

in the same enum incremented by one. This increment might place the

constant's value out of the acceptable range, as in the following example:

char enum COLORS

{

RED=254, /* Numeric value is 254 */

GREEN, /* Numeric value is 255 (254+1) */

BLUE /* Numeric value is 256 - too big for char */

}; /* Error 115 is issued */

The enum constant RED is assigned a value of 254. GREEN does not

have an explicit value, so it is assigned 254+1, or 255. BLUE does not

have an explicit value, so its value would normally be 255+1, or 256.

However, the enum is declared as being a char enum, so 256 is too

big and error 115 is issued.

Warning 116: undefined enum tag "name"

A reference was made to an enum that has not yet been declared. The

compiler may generate this message as a warning if only a pointer to

the enum is used, but the compiler generates this message as an error if

any other use is made of the enum.

Error 117: enum contains no members

An attempt was made to define an enumerated type, but no member

names were specified. Use the pponly option to generate a

preprocessed file if you have problems eliminating this message.

Error 118: conflicting use of enum/struct/union tag "name"

An attempt was made to define an enum, struct, or union that has

the same name as a previously defined enum, struct, or union in

the same scope. You cannot define an enum with the same name as a

struct, union, or another enum.

Error and Warning Messages 237

Error 119: identifiers missing from definition of function

"name"

A prototype-style function definition was encountered, but the names of

the parameters were missing. You can omit the parameter names from a

prototype, but the names must be present in the actual function

definition. For example the following code generates error 119:

void func(int, int, double); /* Legal prototype */

void func(int, int, double) /* Illegal function definition */

{ /* Error 119 */

}

Warning 120: Integral type mismatch: possible portability

problem

Expecting "type1", found "type2"

This message is suppressed by default, but you can enable it with the

strict or warn=120 options. The wrong integral type was passed as

a parameter. This error may be a problem on another compiler or

another type of computer if the size of an int is different from the size

of an int on the Amiga computer. This warning is not a problem if

your code needs to run with the SAS/C Compiler only.

In the following example, the SAS/C Compiler promotes the short

integer to a long integer even if you compile with the shortint

option:

#pragma msg 120 warn

void func(long);

void main(void)

{

short s = 10;

func(s); /* Warning 120 */

}

However, pre-ANSI compilers on machines that define the int type to

be the same as short may not perform the conversion or may perform

the conversion and issue a warning message. In addition, if you remove

the prototype, this code will not work on any machine where int is the

same as short.

238 Appendix 2

Warning 121: hex/octal constant "constant" too large for char

High bits may be lost

Warning 121 is generated if a hexadecimal or octal constant specifies

more digits than will fit into a single char.

According to the ANSI Standard, hexadecimal bytes may be specified

in a quoted string using the \xhh escape sequence. The ANSI Standard

also states that the escape sequence consumes all valid hexadecimal

characters in the string following the \x, even if all the characters

consumed will not fit into a single byte, which may not be what you

want. For example, in the case of \xabcdefgh, you may want the

character 0xab first, followed by the string cdefgh. According to the

ANSI Standard, this escape sequence evaluates to the character Oxef

followed by the string gh, because the \x consumes all valid

hexadecimal characters. A single byte cannot hold the hexadecimal

number 0xabcdef, so the top bits are lost and 0xef is the result. The

best way to get the character 0xab followed by the string cdefgh is to

use ANSI string concatenation to terminate the escape sequence:

\xab cdefgh. The two strings are concatenated to form the desired

sequence.

Warning 122: missing ellipsis

A function or function prototype was encountered that attempted to

specify variable arguments with a trailing comma in the argument list.

According to the ANSI Standard, variable arguments must be specified

by a trailing comma followed by an ellipsis (...). The SAS/C Compiler

accepts the form without the ellipsis as if the ellipsis had been specified,

but other ANSI conforming compilers may require the ellipsis, as in the

following example:

void foo(int x, ... ); /* Right */

void bar(int x, ); /* Wrong */

Warning 123: no tag defined for enumeration

Cannot construct prototype

The genproto option was active, but a prototype could not be

generated for a function because an enum was used as a parameter to

the function and that enum had no tag, as shown in the following

example.

void myfunc(colors)

enum (RED, GREEN, BLUE) colors;

{

}

Error and Warning Messages 239

The tag is the name normally appearing immediately after the keyword

enum in the enum declaration. This message is produced only if the

genproto compiler option is used to produce prototypes.

Error 125: invalid number

The numerical constant specified cannot be represented on the Amiga

computer. The constant is probably an integer that is too large or too

small (negative) to be represented in four bytes. This error can also be

produced if a floating-point number is specified incorrectly or if invalid

digits are provided to an octal constant.

The following lines all produce error 125:

double d = 10.3.2; /* Error 125 */

int i = 123456789123456789; /* Error 125 */

int j = 099; /* Error 125 */

In the first line, the value assigned to the floating-point variable has been

incorrectly specified. In the second line, the value contains too many

digits to fit into an int. In the third line, the value begins with a zero,

which makes the value an octal constant, but it contains the digit 9,

which is invalid for octal constants.

Warning 126: #endif, #else, or #elif out of order

A #endif, #else, or #elif was encountered but no #if or #ifdef

was active.

Error 127: operand to # operator must be a macro argument

If a preprocessor macro parameter is preceded with the # operator, that

parameter is replaced with the literal string consisting of the

corresponding argument to the macro. For example, if you pass the

argument FOO to a macro, and that argument in the macro definition is

preceded by the # operator, that argument expands to the string

"FOO". The # operator can be applied only to macro arguments.

Error 128: text-from-#error

This message is the result of a #error preprocessor directive in the

source code being compiled. The text of the message is taken from the

#error line.

Error 129: ambiguous struct or union member "name"

Your code referred to a structure or union member that did not exist.

In an attempt to resolve the name, the compiler examined the names of

all members of substructures or subunions. Two or more members of

subaggregates matched the name you provided, so the compiler was

unable to determine which member you intended to specify.

240 Appendix 2

Suppose you have the following code:

void main(void)

{

struct FOO

{

int x, y, z;

};

struct BAR

{

int a, b, x;

};

struct COMBO

{

struct FOO foo;

struct BAR bar;

}

combo.a = 10; /*Warning 193*/

combo.x = 10; /*Error 129*/

}

The reference to combo.a succeeds, although it generates a warning

193 (implicit reference to structure member), because the

full reference should be combo.bar.a. The reference to combo.x

generates error 129, because both substructures of combo contain a

member called x. The compiler cannot tell whether you mean

combo.foo.x or combo.bar.x, so it issues the error message 129.

See Chapter 11, "Using Amiga Specific Features of the SAS/C

Language," for more information on implicit structure references.

Error l31: maximum temporary or formal storage exceeded

The compiler must allocate stack storage to allow you to pass and

receive structures or other parameters to and from functions.

Parameters are copied onto the stack for each function call, so if you

are passing large structures, your code will run very slowly. Consider

passing a pointer to your structure instead of the entire structure.

Error and Warning Messages 241

Warning 132: extra tokens after valid preprocessor directive

The ANSI Standard does not allow extra text on a preprocessor line,

but this extra text may be allowed by some C compilers. For example,

many programmers put a descriptive word after a #endif directive

indicating the #if to which the #endif belongs. To make your code

ANSI-compatible, you should place such descriptive words in comments,

as shown in the following example:

#ifdef SOMETHING

#endif SOMETHING /* Warning 132 */

#ifdef SOMETHING

#endif /* SOMETHING */ /* No warning */

Error 133: cannot redefine macro "name"

An attempt was made to redefine a built-in preprocessor macro, like

__FILE__ or __LINE__ You cannot redefine built-in preprocessor

macros.

Warning 134: too many arguments

A macro definition was encountered with more than the allowable

number of arguments. The current ANSI limit for macro arguments is

31, and the SAS/C Compiler does not allow more than 31 arguments. If

message 134 is issued, the macro is not successfully defined. Any use of

the macro in your code produces a warning for a function with no

prototype and possibly a linker error when the name of the macro

cannot be resolved by the linker.

Error 135: argument count incorrect for macro "name",

expecting number arguments

See line number file "filename"

Your code invoked a macro with too few or too many arguments. The

macro is defined at the specified file and line number.

Error 136: invalid use of register keyword

Your code used one of the register keywords inappropriately. The

on.

242 Appendix 2

Warning 137: ANSI limits #line numbers to between 1 and 32767

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=137 options. The ANSI Standard states that

line numbers specified with a #line directive should be between 1 and

32767. However, the SAS/C Compiler accepts any number that will fit

into a signed four-byte integer.

Error 138: operation invalid for pointer to void

Your code attempted to perform an operation on a void * pointer that

is not valid for void *. Such operations include addition, subtraction,

array indexing, and dereferencing (unary * operator). For example, the

following code attempts to perform addition on a void * pointer:

void *p = NULL;

p = p + 1; /* Error 138 */

Warning 139: missing #endif

See line number file "filename"

The compiler encountered an #if, #ifdef, or #elif statement for

which there is no matching #endif. The file and line number of the

unmatched directive is specified in the message. This message occurs

only at the end of the source file, so large portions of your program

may have been ignored because of a stray #if or #ifndef with no

matching #endif.

Warning 140: sizeof operator used on array that has been

converted to pointer

Use of the sizeof operator on an array name gives the size of the

array. However, if the array name has been converted (cast) to a

pointer, the resulting size is the size of the pointer (4 bytes), not the

size of the array. Almost any use of an array name in an expression

implicitly casts the array name to pointer. To determine the actual size

of the array, pass only the array name to the sizeof operator.

Error and Warning Messages 243

In the following example, in the first assignment statement, i gets the

value 4 (the size of a pointer to a character). In the second assignment

statement, i gets the value 10.

char ary[10];

int i;

i = sizeof(ary+1); /* Warning 140 */

i = sizeof(ary);

Error 142: array size never given for "name"

You can declare an array as extern and not specify the first subscript.

However, when you define the array, you must specify the subscript.

Storage is allocated when you define an array, not when you declare an

array as extern. For example:

extern char ary1[][10]; /* Legal */

char ary2[][10]; /* Error 142 */

Error 143: object has no address

An attempt was made to take the address of something that has no

address. You may be attempting to take the address of a register

variable or an expression.

Warning 146: case value out of range for switch type

A case value was specified in a switch statement that can never be

taken. For example, if you compile with the shortint option and a

switch statement is switching on a short or int value, case values

too big to be stored in 16 bits will generate this warning:

/* The SHORTINT compiler option is on. */

int i = 10;

switch(i) /* i is a 16-bit integer */

{

case 0x08000000: /* Warning 146 */

break;

case 65000: /* Warning 146 */

break;

}

244 Appendix 2

Warning 147: conversion between function and data pointers

Your code has cast or otherwise converted a pointer that points to a

function to a pointer that points to data. The ANSI Standard states that

this conversion is not legal. This conversion works with the SAS/C

Compiler in most circumstances, but you should use the

absfuncpointer compiler option if your code is larger than 32K.

Warning 148: use of incomplete struct/union/enum tag "name"

See line number file filename

This message is suppressed by default, but you can enable it with the

warn= 148 option. An incomplete tag is one for which no definition has

been seen. The ANSI Standard allows use of an incomplete tag (for

declaring pointers, for example). If you want to know when an

incomplete tag is being used, enable this warning. You may also want to

enable warning 149.

Warning 149: incomplete struct/union/enum tag in prototype scope

"name"

This message is suppressed by default, but you can enable it with the

strict or warn= 149 options. An incomplete tag was discovered in a

prototype. An incomplete tag is one for which no definition has been

seen. The ANSI Standard requires the incomplete tag's scope to end at

the end of the prototype. Therefore, any definition of the function later,

even if the tag in question has been defined, may generate an error

message and terminate the compilation. You may want to turn on

warning 148 for the most information about incomplete tags. If you do

not want to see all the incomplete tag information, you identify most

problem cases by enabling only warning 149.

The following function definition produces an error on many ANSI-

conforming compilers because the structure FOO referred to in the

definition is considered to be a different structure FOO than the one

referred to in the prototype.

Error and Warning Messages 245

void func(struct FOO *); /* Warning 149 */

struct FOO

{

int x, y, z;

};

/* Many compilers issue an error here. */

void func(struct FOO *foo)

{

}

This error could be fixed by moving the definition for the structure FOO

before the prototype.

Warning 150: the keyword "name" is meaningless for itemtype

When declaring a function or data item, you have used a keyword that

is meaningless for that type of item. For example, you cannot specify

the following:

void __chip foo(int); /* Warning 150 */

It is meaningless to say that a function is to be allocated in _ _ chip

memory.

The __near and __far storage class keywords are valid on both

functions and data items, but have slightly different meanings. See the

descriptions of the data=near and code=near options in Chapter 8,

"Compiling and Linking Your Program," for more information.

Some keywords that are valid on functions are also valid on data

items because the data items may be pointers to functions of the

designated type. For example, you may have a function that returns a

pointer to a __regargs function. Keywords in this category include

__stdargs, __regargs, __asm, and __interrupt.

Other keywords need to be present only on the function definition.

You do not need to add them to function pointers and function

prototypes. Keywords in this category include __stackext and

__saveds. If these keywords appear on a data item, warning 150 is

generated and the extra keyword is ignored.

For more information on specifying keywords, see Chapter 11, "Using

Amiga Specific Features of the SAS/C Language."

246 Appendix 2

Error 152: cannot define function via typedef name

Your code attempted to define a function using a typedef, as shown

below:

typedef int foo(int);

foo bar /* Error 152 */

{

}

According to the ANSI Standard, you cannot define a function using a

typedef. The SAS/C Compiler does not accept such a definition.

Warning 154: no prototype declared for function pointer

Function pointers require prototypes just like functions. To declare a

prototype for a function pointer, enter the parameter list instead of the

empty parentheses in the definition, as shown in the following example:

void (*func1)(); /* Warning 154 */

void (*func2)(int, double, long); /* No warning */

Remember that a pointer to a function that takes no parameters still

requires a prototype:

void (*func3)(void); /* Function pointer takes no parms */

Error and Warning Messages 247

Warning 155: no statement after label

The C language does not allow a label immediately before the curly

brace ending a block (}). If you enter a label in this position, the SAS/C

Compiler generates this warning. Enter a semicolon (representing a

NULL statement) after the label to suppress the warning, as shown in

the following example:

void funcl(void)

{

goto foobar;

/* more code */

foobar: /* Warning 155 */

}

void func2(void)

{

goto foobar;

/* more code */

foobar: ; /* No warning */

}

Warning 156: operation/comparison of pointer to "int" and

pointer to "type"

This message is suppressed by default, but you can enable it with the

warn= 156 options. If you compiled with the short int option, your

program has used a pointer to int and a pointer to short in an

operation. If you did not compile with the shortint option, your

program has used a pointer to int and a pointer to long in an

operation.

248 Appendix 2

For example, the following code will work if int and long are the

same length, but the same code will not compile if ints and longs are

different lengths:

/* Assume SHORTINT is not active */

int *ip = NULL;

long *lp = NULL;

int diff;

diff = ip - lp;

Error 158: invalid type name

The compiler expected a type name for a cast or of f setof operation,

but the provided name was not recognized as a valid type name. Check

the preprocessed output to make sure you are providing the correct

information.

Warning 159: use of unary minus on unsigned value

This message is suppressed by default, but you can enable it with the

strict or warn= 159 options. Your code has used the unary minus

operator (-) on an unsigned variable. Using this operator on an

unsigned variable may not produce the expected result because the

result is still a non-negative number.

Warning 161: no prototype declared at definition for function

"name"

An old-style function definition was encountered, and no prototype was

in scope. The prototype must appear in the C file or a header file before

the definition of the function, or the function definition itself must be a

prototype-style definition.

Warning 162: non-ANSI use of ellipsis punctuator

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=162 options. You have declared a function

with the ellipsis punctuator (...) but the function has no arguments. The

ANSI Standard requires functions that take a variable number of

arguments to take at least one fixed argument.

Warning 163: initialization of auto struct, union, or array

This message is suppressed by default, but you can enable it with the

strict or warn=163 options. Your code has initialized an automatic

structure, union, or array. The ANSI Standard allows you to initialize

automatic structures, union, and arrays, but many pre-ANSI compilers

do not.

Error and Warning Messages 249

Warning 164: & applied to array

This message is suppressed by default, but you can enable it with the

strict or warn= 164 options. Your code has used the address (&)

operator on an array name. You should instead take the address of the

first element in the array, or use the array name without the address

operator. For example:

int ary[10];

int *iptr;

iptr = &ary; /* warning 165 */

iptr = ary; /* OK */

iptr = &ary[0]; /* OK */

Warning 165: use of narrow type in prototype

This message is suppressed by default, but you can enable it with the

warn = 165 option. This warning is provided for detecting situations

that may cause problems on other compilers if your code mixes function

prototypes and old-style function definitions. See Chapter 13, "Writing

Portable Code," for information on using narrow types in function

declarations. See also the descriptions of messages 176 and 179.

Error 166: unrecoverable error or too many errors

Terminating compilation

Your program has exceeded the default or specified maxerr or

maxwarn values, or an error has occurred that prevents the compiler

from producing meaningful results.

The default maximum number of errors is 50. By default, any

number of warnings may be generated.

Warning 169: ineompatible operands of conditional operator (?:)

"type1" conflicts with "type2"

The operands of the ?: conditional operator must be of compatible

types. Your code supplied types to the ?: operator that were not

compatible. For example, the following code generates warning 169:

int func(void)

{

int i = 0;

struct FOO *foo = NULL;

return (int)(i > O ? foo : i); /* Warning 169 */

}

250 Appendix 2

The expression following the question mark (?) is of type

struct FOO *. The expression following the colon (:) is of type int.

This message can be an error if it is not possible to convert the types

in question. This can occur if one of the types is a structure or union.

Warning 170: overflow during operation on constants

A constant expression overflowed the limits of the type in which it was

being calculated. Perhaps you have added or multiplied two large

integers, thereby resulting in a number too large to represent in a four-

byte integer.

Warning 176: implicitly promoted formal "name" conflicts with

prototype

See line number file "filename"

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn= 176 options. You are defining a function

using an old-style definition, which means that any narrow types (char,

short, and float) in your definition are implicitly widened to their

non-narrow equivalents (int, int, and double, respectively).

However, a prototype is in scope that gives the narrow version of the

type.

Functions that call your function will not know that your function is

using an old-style definition and, with some compilers, may pass an

incorrect value. An incorrect value is never passed using the SAS/C

Compiler on the Amiga hardware. See Chapter 13, "Writing Portable

Code," for information on using narrow types in function declarations.

See also the descriptions of messages 165 and 179.

Warning 178: indirect call without indirection operator

This message is suppressed by default, but you can enable it with the

strict or warn= 178 options. You called a function using a function

pointer, but did not use the indirection (*) operator to dereference the

pointer first. The SAS/C Compiler generated correct code, but on

pre-ANSI compilers this code may not work. Example:

void (*funcptr)(int);

funcptr(10); /* Warning 178 */

(*funcptr)(10); /* No warning */

Error and Warning Messages 251

Warning 179: narrow type used in old-style definition

This message is suppressed by default, but you can enable it with the

strict or warn=179 options. Your code has used a narrow type

(char, short, or float) in an old-style definition. See Chapter 13,

"Writing Portable Code," for information on using narrow types in

function declarations. See also the descriptions of messages 165 and

176.

Warning 180: no space between macro name and its replacement

list

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=180 options. Your code is defining a

preprocessor macro that takes arguments but does not have at least one

blank after the closing parentheses of the argument list. The ANSI

Standard requires white space after the closing parentheses. For

example:

#pragma msg 180 warn

#define ADD(a,b)(a+b) /* Warning 180 */

Warning 181: "name" was declared both static and external

See line number file "filename"

Your code has declared a function as both static and external at

different places. Both the function and its prototype must agree on

whether the function is static.

Warning 182: static function "name" declared but not defined

See line number file "filename"

Your code had a prototype for a function declared static but never

defined the function. The function definition may be hidden with # i f or

#ifdef statements.

Warning 183: inline function declared but not defined

See line number file "filename"

Your code had a prototype for a function declared __inline but

never defined the function. The function definition may be hidden with

#if or #ifdef statements.

Warning 184: invalid multi-byte character constant

Your code has specified a multibyte character constant (such as ~ ab ' ),

and you did not compile your code with the mccons option; or, if you

compiled your code with the mccons option, the multibyte character is

larger than the permitted four bytes.

252 Appendix 2

Error 185: comma expected

The compiler expected a comma but did not find one. This error may be

produced because of errors in previous statements. Fix all previous

errors before fixing this one.

Warning 186: implicit conversion between pointer and scalar

Your code has converted a pointer to an integer while doing static

initialization. You can suppress this warning by casting the pointer to

the appropriate type.

Warning 187: negative value assigned to unsigned type

This message is suppressed by default, but you can enable it with the

strict or warn=187 options. Your code has assigned a negative

constant to an unsigned variable. In doing so, your code is in effect

assigning a very large positive number to the variable, which may or

may not be the action you intended.

Warning 190: #include ignored because header already included

See line number file "filename"

This message is suppressed by default, but you can enable it with the

warn=190 option. The nomultipleincludes compiler option is

active, and your code included the same header file more than once.

The compiler ignores the additional #include statement. You can use

this message to locate all such multiple includes if you want to modify

your header files to not include the same file more than once.

You can get even more information about which header files were

included by using the listincludes compiler option.

Warning 192: wrong size for enum

An enum variable was declared to be of a different type than the base

enum was when it was defined. Suppose you have the following code:

char enum COLORS = (RED, GREEN, BLUE);

enum COLORS color; /* Warning 192 */

char enum COLORS color2; /* correct */

The enum variable color should be declared the same size as the base

enum type, which is char enum. The base enum type overrides the

enum variable's type definition.

Error and Warning Messages 253

Warning 193: implicit reference to struct/union member

Reference assumed to be "reference"

Your code has referred to a struct or union member name that is

actually a member of a substructure or subunion of the original. The

compiler has searched all substructures and subunions and determined

that exactly one member matches the name you specified, so it is using

that member. The reference printed in the message text is the fully

expanded name of the member that it is using. If you intend to take

advantage of this feature of the SAS/C Compiler, you may disable this

warning with the ignore= 193 option. If you choose to disable this

warning, your code may not work on other compilers.

For more information on using implicit structure references, see

Chapter 11, "Using Amiga Specific Features of the SAS/C Language."

Warning 194: too much local data for NEAR reference,

some changed to FAR

You have declared more than 32K of static data. The compiler can

address up to this amount using 16-bit offsets. Amounts greater than

32K must be addressed using 32-bit offsets. You may have compiled

with the data=f aronly option and declared some data with the

__near keyword. If your entire project is in one source file or is

compiled with data=faronly, you can ignore this warning unless you

get an error later in the compilation or link. Otherwise, you must

eliminate some near data in one of three ways:

[] Compile your program with the strmerge compiler option. This

option moves all string constants to the code section, thereby moving

them out of the near data section.

[] Declare read-only data as static const. When you compile with

the stringmerge option, this data will also be moved to the code

section.

[] Add the __far keyword to some of your larger external or static data

items to move those items from the near section to the far section.

Specify the data=far compiler option to move all data items except

those declared with the _ _ near keyword to the far section.

Note: The second line of message 194 is not printed unless you

compiled with the data=auto option, or you compiled with the

data = faronly option and declared data with the __near keyword.

254 Appendix 2

Warning 195: nested comment detected

This message is suppressed by default, but you can enable it with the

warn= 195 option. The compiler found the start of a comment (/*)

inside of a comment. Some compilers allow comment nesting and others

ignore the start of the second comment. The ANSI Standard does not

allow nested comments. If you choose to use nested comments, you

should specify the comnest compiler option. However, using the

comnest option prevents your code from running on most ANSI-

compliant compilers.

Warning 196: specified include directory not found: "name"

The named directory does not exist or could not be accessed.

Warning 198: __regargs invalid for a varargs function

Functions that take variable numbers of parameters always pass their

parameters on the stack. The __regargs keyword is invalid for these

functions.

Error 199: unbalanced comment

See line number file filename

Your code has a comment open (/*) with no corresponding comment

close (*/). This condition is not detected until the end of the C source

file.

Warning 204: macro invocation not terminated

Your code invoked a macro but did not supply enough closing

parentheses to terminate the invocation. Also, check any of the macros

that are invoked by the macro that you invoked directly in your code.

Warning 209: macro invocction may have multiple side effects

You have passed an expression with a side effect as an argument to a

macro, and that macro has evaluated the argument more than once.

Operators with side effects are ++,--, +=, /=, *=, -=, >>=, <<=, |=,

&=, and =.

For example, the max and min macros evaluate each argument twice.

If you invoke the max macro as MAX ( i ++, j ), the first argument is

evaluated twice, and two post-increments take place. You could define

the max macro as follows:

#define MAX(x,y) ((x) > (y) ? x : y)

int i = 0;

i = MAX(i++, 0); /* Warning 209 */

Error and Warning Messages 255

The macro expands to:

i = ((i++) > (0) ? i++ : 0);

The expansion contains the expression i++ twice, so if that branch of

the ?: operator is executed, the variable i is incremented twice.

This warning may sometimes be produced incorrectly, but you should

examine each case to determine whether there is an error.

Function calls are also considered side effects, but function calls

produce warning 217 instead of warning 209.

Warning 212: item "name" already declared

See line number file "filename"

This message is suppressed by default, but you can enable it with the

warn=212 option. You have declared an item twice. For example, you

may have specified the prototype for a function twice, or you may have

declared an extern twice. The declarations do not conflict, or the

compiler would generate error 72, but code is harder to maintain if it

defines the same item in more than one place. You may want to use the

nomultipleincludes option to suppress multiple #includes of

the same file if you enable warning 212.

Warning 213: empty argument to preprocessor macro

This message is suppressed by default, but you can enable it with the

strict, ansi, or warn=213 options. Your code calls a preprocessor

macro with no argument text. This action is accepted by the SAS/C

Compiler but is not permitted by the ANSI Standard. For example:

#define FOO(a,b) a

FOO(lO,)

Warning 216: symbol "name" found

You have compiled with the fsym compiler option, and the compiler

has found a definition of one of the symbols that you specified as the

parameter to the fsym option.

Warning 217: macro invocation may call function multiple times

You have passed a function call as an argument to a macro that

evaluates its arguments more than once. This action may cause

incorrect results. See also the description of message 209.

256 Appendix 2

Error 218: declaration found in statement block

The compiler found a declaration where it expected a statement. You

may have a statement in the middle of your declaration block, or vice-

versa. Any declarations found after this error are added as external

variables, which suppresses warnings about undefined variables but

may create additional errors later if your code declares a variable of the

same name. In the following example, the variable y is declared after

the first statement of the function:

void func(void)

{

int x;

x = 10;

int y; /* Error 218 */

}

Warning 220: old-fashioned assignment operator

taken as "operators"

This message is suppressed by default, but you can enable it with the

strict or warn=220 options. Older compilers allowed the operators

=-, =+, and so on. In ANSI C, these operators are specified as -=, +=,

and so on. The older specification is ambiguous when assigning certain

expressions (for example, x=-5; and x= - 5; ). To resolve this

ambiguity, newer compilers use =-, and some pre-ANSI compilers use

-=. Therefore, you should enter at least one space between the equals

(=) sign and whatever operator follows it to ensure portability.

Error 223: "filename" is not a valid GST file

The specified filename was supplied using the gst compiler option as a

Global Symbol Table file, but it is not a valid GST file. Delete the bad

file and try re-creating it.

Warning 224: item "name" already defined

See line number file "filename"

This message indicates that a variable, function, or typedef is being

defined for the second time in a given scope. This message is normally

an error, but if the redefinition is harmless, the compiler allows it and

issues the message as a warning instead. As shown in the following

example, the compiler allows redefinition of typedef names in the

same scope if the new type is identical to the old type. The compiler

does not allow redefinition of functions or variables in the same scope.

Error and Warning Messages 257

typedef int foo;

typedef int foo; /* Warning 224 */

void func(void)

{

}

void func(void) /* Error 224 */

{

}

Warning 225: pointer type mismatch

"type1" does not match "type2"

Your code has performed an assignment or some other operation on

two incompatible different pointer types or on a pointer type and an

arithmetic type. For example:

struct FOO

{

int x, y, z;

} foo;

int *ip;

ip = &foo; /* Warning 225 */

Error 226: cannot convert "type1" to "type2"

The compiler was unable to perform a requested or implicit conversion.

For example, if one of the types is an instance of a structure, the

structure cannot be cast to another structure type or to an arithmetic

type. For example:

struct FOO

{

int x, y, z;

} foo;

int i;

i = (int) foo; /* Error 226 */

258 Appendix 2

Explanations of Linker Messages

Error 103: Out of memory!!

slink has run out of memory. By default, slink attempts to cache

the object modules in memory between pass 1 and pass 2. If slink

runs out of memory, it attempts to free the cached object modules. In

some cases, slink cannot find enough continuous memory. Try adding

bufsize 4096 to the slink command. This option turns off object

module caching.

Error 425: Cannot find library library-name

The linker cannot find the specified library. Usually, SAS/C libraries are

located in the LIB: directory. You may have misspelled to library

name in your slink command.

Error 426: Cannot find object name

The linker cannot find the specified object.

Error 443: filename is an invalid file name

The linker found an invalid character in a filename.

Error 444: Hunk_Symbol has bad symbol-type symbol symbol-name

The object module is corrupt. Try recompiling the object module.

Error 445: Invalid HUNK_SYMBOL symbol-name

The object module is corrupt. Try recompiling the object module.

Error 446: Invalid symbol type symbol-type for symbol-name

Either the object module is corrupt, or slink has found a symbol type

that it does not recognize. Try recompiling the object module. For a list

of valid symbol types, refer to the description of object file structure in

The AmigaDOS Manual, 3rd Edition.

Error 447: filename is a load file

The file specified is an executable module instead of an object module.

Error 448: filename is not a valid object file

The file specified is not an object module. The file may be a C source

file or a corrupt object module.

Error 449: No hunk_end seen for filename

The object module is corrupt. Try recompiling the object module.

Error 450: Object file filename is an extended library

A library file was specified as an object module. Add the library

keyword in front of the library name.

Error and Warning Messages 2S9

Error 501: Invalid Reloc 8 or 16 reference

An 8- or 16-bit relocation address cannot reach its destination. The

SAS/C Compiler does not generate 8-bit relocation records, but third

party products may use them. The object module is probably corrupt.

Try recompiling your source file. If recompiling the file does not correct

the error, contact the Technical Support Division.

Error 502: function-name symbol - Distance for Reloc16 greater

than 32768

The distance from the point where the function is called to the function

itself is greater than 32767 bytes. The function cannot be referenced

with a 16-bit address field. Normally, slink tries to insert an ALV

(Automatic Link Vector) at the end of the calling module, but if the

module has more than 32K of code, the relocation may not reach the

ALV. An ALV is the instruction used to reach functions that would

otherwise be too far away. Compile the file with -code=far, or

declare the function with the __far keyword.

Error 503: function-name symbol - Distance for Reloc8 greater

than 128

The distance from the point where the function is called to the function

itself is more than 128 and so the function cannot be referenced with

an 8-bit address field. The SAS/C Compiler does not generate 8-bit

relocation records, but third party products may use them.

Error 504: variable-name symbol - Distance for Data Reloc 16

greater than 32768

The distance for the 16-bit relocation is too far. You may see this

message if a data item (such as a structure or an array) is larger than

64K or if the total amount of data in your program is greater than 64K.

To correct the problem, you can either break the data item down and

make it smaller than 64K, or you can place the __far keyword on the

definitions of one or more data items to force all references to those

items to be 32-bits. Using the __far keyword reduces the amount of

data in the near data section to less than 64K. You can also compile

your program with the data = far option. However, using data=far

increases code size and execution time.

Error 505: variable-name symbol - Distance for Data Reloc8

greater than 128

The distance for the 8-bit relocation is too far. The SAS/C Compiler

does not generate 8-bit relocation, but third party products may use

them.

260 Appendix 2

Error 506: Can't locate resolved symbol symbol-name

If this message appears, please contact the Technical Support Division.

See Chapter 3, "Getting Help," for a complete list of items that you

need to provide to the Technical Support staff.

Error 507: Unknown Symbol type symbol-type , for symbol

symbol-name

Either the object module is corrupt, or a slink has found a symbol

type that it does not recognize. Try recompiling your source file. For a

list of valid symbol types, see the description of object file structure in

The AmigaDOS Manual, 3rd Edition.

Error 508: Symbol type symbol-type unimplemented

Either the object module is corrupt, or a slink has found a symbol

type that it does not recognize. Try recompiling your source file. For a

list of valid symbol types, see the description of object file structure in

The AmigaDOS Manual, 3rd Edition.

Error 509: Unknown hunk type symbol-type in Pass2

If this message appears, please contact the Technical Support Division.

See Chapter 3, "Getting Help," for a complete list of items that you

need to provide to the Technical Support staff.

Error 510: symbol-name symbol - Near reference to a data item

not in near data section

The linker expected the specified symbol to be in the near data section,

but the symbol is located in either the far data section, chip memory, or

the code section.

You may have defined a variable as __far with the __far

keyword in one module and externally declared the same variable in

another module without the __far keyword. If so, the module with

the external declaration attempted to reference the data as near. To

correct the problem, the definition and all declarations of the data item

must be specified with the same keywords.

If you compiled your file with the data=auto option, the compiler

can place variables into the far data section if necessary. The compiler

may have placed a variable in one module in the far section and a

variable in another module in the near section. To correct this situation,

either stop using the data=auto option, and use the __far keyword

(if necessary) on the definition and all declarations of the variable that

causes the error.

Error and Warning Messages 261

Error 512: Invalid branch to function-name in overlay node

module-name

The linker detected a branch in an overlay node that calls another

overlay node at the same level. This type of branch is not supported by

the overlay manager.

Error 513: Multiple NTRYHUNK segments not permitted

The NTRYHUNK is the root overlay node. No other hunks should have

this name.

Error 514: Overlay manager _ovlyMgr is undefined

This _ovlyMgr function is located in SAS/C libraries. To use the

SAS/C overlay manager, link with sc.lib or scs.lib. You can also

write your own overlay manager. See Chapter 8, "Compiling and

Linking Your Program," for information on creating your own overlay

manager.

Error 515: An ALV was generated pointing to data variable-name

symbol

A 16-bit relocation could not reach its destination, so slink inserted

an ALV (Automatic Link Vector) instruction, and then determined that

the destination is not in a code hunk. To correct the problem, make the

reference a 32-bit reference. This error may be generated for object

code produced by third-party assemblers and compilers

Error 516: Attempt to merge BSS with CODE or CODE/DATA

Either you have attempted to merge the far BSS section with the far

data section, or you have attempted to merge the near or far BSS

section with the code section. You can merge a BSS section with the

__MERGED section only. You will see this message if you have assigned

the same name to either the far BSS section and the far data section or

the far BSS section and the code section.

If you get this error in another situation, please call the Technical

Support Division.

Note: Do not name the code section __MERGED.

Error 600: Invalid command command

The option listed is not a valid slink option.

Error 601: option option specified more than once

The option has been specified twice.

262 Appendix 2

Error 602: Unable to open output file filename

slink cannot open the output file for write access. Another program

such as CodeProbe may have left a lock on the file. Alternatively, the

protection bits may prohibit write access to the file, or that the name

specified may be a directory.

Error 603: string is not a valid number

The linker found a non-numerical character in a field where it expected

to find a number.

Error 604: with file is not readable

The with file may contain binary characters or may be locked.

Error 605: Cannot open with file filename

The with file does not exist or may be locked.

Error 607: No FROM/ROOT files specified

You did not specify an object module, or if you are using overlays, the

root node did not contain any objects.

Error 608: Premature EOF encountered

The object module is corrupt. Try recompiling the source file.

Error 609: Error seeking in file filename

The object module is corrupt. Try recompiling the source file.

Error 610: module-name has no parent in overlay tree

The with file specifies an overlay with no parent node.

Error 611: Reloc found with odd address for symbol symbol-

name, file filename

The linker has found a relocation record with an odd address. This

message can only be generated if your program is written in assembler

and is usually caused by placing an odd length character string in the

code section.

Error 612: MERGED Data relocation to non-code section in

Overlay Node

Reference at offset hex-address in module-name, To

Unit module-name

The linker found a relocation from the near data section, which is

placed in the root node, to the data section of an overlay node. This

type of relocation is illegal.

Error and Warning Messages 263

Error 613: MERGED Data relocation to static function is not

resolvable by Overlay Manager.

Reference at offset hex-address in filename , To

Unit filename

The overlay manager cannot resolve an indirect function call from the

root node to a static function in a overlay node. To correct the problem,

remove the static keyword from the function declaration.

Error 614: More than one MERGED data section found

Only one near data section is allowed. This error occurs only when

using slink to strip debug information from an executable generated

by a third party linker. If you get this message, do not use slink to

strip debug information from this executable.

Error 615: Code hunk named __MERGED

slink merges all hunks with the name __MERGED and performs

relocations to this hunk relative to register A4. Do not name the code

hunk __MERGED .

Error 616: ALVs were generated

You have linked with the noalvs linker option, but the linker could

not resolve all relocations without generating ALV instructions. Either

the total code size is greater than 32K, or there are multiple code

hunks. The executable will run, but the code section is not totally PC-

relative.

Error 617: MERGED data greater than 64K

If your program does not generate any additional messages, then the

program will still run. However, a 16-bit data relocation record may

not be able to reach its target, and if this happens, slink will generate

an error.

Error 618: Multiple OVERLAY usage-previous occurrences were

ignored

You can only specify one overlay manager.

Error 619: Ignoring null OVERLAY list

You did not specify any files in the overlay list.

264 Appendix 2

Error 620: Missing '#' at end of OVERLAY list

Enter a pound sign (#) at the end of the overlay tree. For more

information on creating overlay trees, see Chapter 8, "Compiling and

Linking Your Program."

Error 621: Conflicting integer sizes found

Some modules were compiled using short integers and some were

compiled using long integers. You cannot mix integer sizes in an

executable. Alternatively, you may have linked in the wrong version of

the library.

Error 622: Conflicting math types found

You may have compiled the various object modules with conflicting

math options. All object modules must be compiled with the same math

library. Alternatively, you may have linked in the wrong math library.

Error 623: Regargs function function called through overlay

manager. Parameters passed in registers to this

function will be destroyed.

The regargs function passes parameters in scratch registers, but the

overlay manager does not preserve scratch registers. You cannot call a

regargs function across an overlay node.

Error 624: Absolute reference to symbol module: file filename

If you reference far data in a module linked with cres.o or when you

are generating a shared library, your program may function improperly

unless the data are read-only. slink cannot determine if the reference

is read-only, so it generates this warning.

Error 625: Proper math library has not been included

You have not linked in the math library that is needed for the current

math options.

Error 626: Libcode used on module module

You have compiled the module with the libcode compiler option that

was used on the module, but the module is being linked into an

executable. Use the libcode option for generating shared libraries

only.

Error 627: Near references found in executable that has a

module compiled with FARONLY option

You cannot mix modules compiled with data= faronly and modules

that refer to near data.

Error and Warning Messages 265

Enabling Suppressed Messages

Many messages are suppressed by default. The strict and ansi

compiler options turn on some of these messages, but you must use the

warn option to enable the remaining messages. The ansi option enables

the following messages:

18 51 70 108 111 137 162 176 180 213

The strict option enables the following messages:

18 70 111 137 159 163 176 179 187 220

51 108 120 149 162 164 178 180 213

The following messages can be enabled only with the warn option:

22 148 156 165 190 195 212

The following table lists each message that is suppressed by default and

indicates which compiler options enable the message.

Number Message Text ansi strict warn

18 sizeof operator used in preprocessor X X X

condition

22 structure used as function argument X

51 C++ comment detected X X X

70 unrecognized escape sequence X X X

108 zero-length arrays are not an ansi feature X X X

111 non-portable enum type specified X X X

120 Integral type mismatch: possible portability X X

problem

Expecting "type1", found "type2"

137 ansi limits #line numbers to between 1 and X X X

32767

(cont~nued)

266 Appendix 2

Number Message Text ansi strict warn

148 use of incomplete struct/union/enum tag X

"name"

See line number file filename

149 incomplete struct/union/enum tag in prototype X X

scope "name"

156 operation/comparison of pointer to "int" and X

pointer to "type"

159 use of unary minus on unsigned value X X

162 non-ansi use of ellipsis punctuator X X X

163 initialization of auto struct, union, or X X

array

164 & applied to array X X

165 use of narrow type in prototype X

176 implicitly promoted formal "name" conflicts X X X

with prototype

See line number file "filename"

178 indirect call without indirection operator X X

179 narrow type used in old-style definition X X

180 no space between macro name and its X X X

replacement list

187 negative value assigned to unsigned type X X

190 #include ignored because header already X

included

See line number file "filename "

195 nested comment detected X

212 item "name" already declared X

See line number file "filename"

213 empty argument to preprocessor macro X X X

220 old-fashioned assignment operator X X

267

Appendix 3

Implementation-Defined

Behavior

267 Introduction

268 F.3.1 Translation

268 F.3.2 Environment

268 F.3.3 Identifiers

269 F.3.4 Characters

269 F.3.5 Integers

270 F.3.6 Floating-Point

270 F.3.7 Arrays and Pointers

271 F.3.8 Registers

271 F.3.9 Structures, Unions, Enumerations, and Bit-Fields

272 F.3.10 Qualifiers

272 F.3.11 Declarators

272 F.3.12 Statements

272 F.3.13 Preprocessing Directives

273 F.3.14 Library Functions

278 F.3.15 Locale-Specific Behavior

Introduction

The American National Standard for Information Systems--Programming

Language-C (ANSI Standard X3J11/90-013) allows an implementation

to define its own behavior in certain areas. Implementation-defined

behavior is defined by the ANSI Standard as "behavior, for a correct

program construct and correct data, that depends on the characteristics of

the implementation. . ." (p.3). This appendix describes the SAS/C

Compiler behavior for those areas listed in Section F.3,

"Implementation-Defined Behavior," of the ANSI Standard.

This appendix is organized like Section F.3.

268 Appendix 3

F.3.1 Translation

[] Diagnostics consist of a line printed to the standard output stream

containing the following elements:

filename line class number: text

where:

filename is the name of the file that caused the diagnostic

line is the number of the line that caused the diagnostic

class is either Error or Warning

number is an integer identifying the diagnostic

text is the diagnostic text.

Some diagnostics contain additional information in a second line. If

present, this second line is indented to the same position as the text

portion of the first line.

F.3.2 Environment

[] The compiler conforms to the ANSI Standard for a hosted environment

as documented in Section 2.1.2.2 of the ANSI Standard, plus the

extension of accepting a WBStartup structure as described under

main in the SAS/C Development System Library Reference, Version 6.0.

[] The compiler recognizes the streams stdin, stdout, and stderr as

interactive devices.

F.3.3 Identifiers

[] By default, the number of significant characters for identifiers without

external linkage is 31. However, this number can be changed to any

value up to 255 with the idlen compiler option.

[] The number of significant characters for identifiers with external

linkage is the same as the number for identifiers without external

linkage.

[] Case distinctions are significant in identifiers with and without external

linkage.

Implementation Defined Behavior 269

F.3.4 Characters

[] The source and execution character sets consist of the characters

required by the ANSI Standard. In addition, national characters

(characters with accents) are accepted as valid alphabetic characters

unless the ansi compiler option is used. See The AmigaDOS Manual,

3rd Edition (Commodore-Amiga, Inc. 1991) for a complete definition of

the Amiga character set.

[] No shift states are used for encoding multibyte characters.

[] Each character in the execution character set consists of 8 bits.

[] The source character set maps 1-to-1 to the execution character set.

[] All wide character constants map directly into the execution character

set. Thus, all wide character constants have the same value as their

corresponding character in the execution character set.

[] The C locale is used as the current locale.

[] A plain char item is by default signed, but this default can be

changed to unsigned with the unschar compiler option.

F.3.5 Integers

[] Integers are represented by two's-complement numbers. The range of

possible values are specified in the header file limits .h and in

Chapter 12, "How Does the Compiler Work?" The most-significant bit

in the representation of signed integers is the sign bit and determines

whether the number is positive or negative.

[] When an integer is converted to a shorter signed integer, the high-

order bytes are discarded. The bit pattern of the remaining bytes is

unchanged. The bit pattern of an unsigned number is not changed

when it is converted to a signed integer of equal length.

[] The following list covers the results of bitwise operations on signed

integers:

~ (bitwise NOT)

The bits are inverted; that is, 1 bits are set to 0, 0 bits are

set to 1.

>> (shift right)

The bits are shifted to the right. The sign bit (uppermost bit) is

used to fill the vacated bit positions on the left.

<< (shift left)

The bits are shifted to the left. The vacated bit positions on the

right are filled with zeroes.

& (bitwise AND)

If the corresponding bits in both operands are 1, then the

corresponding bit in the result is set to 1; otherwise, it is set to 0.

270 Appendix 3

| (bitwise OR)

If either of the corresponding bits in the operands are 1, then the

corresponding bit in the result is set to 1; otherwise, it is set to 0.

^ (bitwise XOR)

If the corresponding bits in the operands are not alike, then the

corresponding bit in the result is set to 1; otherwise, it is set to 0.

[] In integer division, the remainder is either 0 or has the same sign as

the dividend.

[] In a right shift of a negative-valued signed integral type, the sign bit is

used to fill the vacated bit positions on the left. That is, the result

retains the sign of the left operand.

F.3.6 Floating-Point

[] Floating-point numbers are represented using the IEEE standard

representation, unless the math= ffp option is on. In the latter case,

the Motorola Fast Floating Point representation is used. The range of

possible values for floating-point numbers is specified in the header file

float.h and in Chapter 12, "How Does the Compiler Work?"

[] If an integral number is converted to a floating-point number that

cannot exactly represent the original value, the number is rounded for

all math options except math=coprocessor. For

math=coprocessor, the number is truncated. You can change the

behavior for the math=coprocessor option by modifying the source

code to the __fpinit.c function, located in sc:source/_fpinit.

However, choosing another rounding mode affects the conversion from

floating-point to integer such that the conversion does not adhere to the

ANSI Standard. Specifically, the following statement might assign the

integer value 6 to i if you specify math=coprocessor, and the

coprocessor's rounding mode is not set to truncate:

int i = (int)5.5;

[] Conversions from double to float round or truncate in the same

manner as conversions from integral types to floating-point types.

F.3.7 Arrays and Pointers

[] The type of integer required to hold the maximum size of an array is

unsigned int.

[] When a pointer is converted to integer, the resulting bit pattern is

as if an object of type unsigned long with the same bit pattern as

the pointer had been converted to the integer type.

Implementation Defined Behavior 271

[] When an integer is converted to a pointer, the resulting bit pattern is

the same as if the integer had been converted to an unsigned long.

F.3.8 Registers

[] Under normal circumstances, there can be up to 4 integer register

variables, 3 pointer register variables, and 5 floating point register

variables. Using the cover compiler option, the stackext compiler

option, the __stackext keyword, or __aligned keyword on a

function definition costs one pointer register variable. Using the

data=faronly compiler option adds an additional pointer register

variable. The reg i s ter keyword is ignored when the global optimizer

is used because registers are allocated to variables by the global

optimization phase. If you specify the autoreg option, the code

generator selects additional register variables for you if registers are

available after assigning your choices to registers.

F.3.9 Structures, Unions, Enumerations, and

Bit-Fields

[] If a member of a union is accessed using a member of a different type,

the result is undefined. If optimization is used, the compiler may

attempt to keep the value stored in one member of a union in a

value.

[] Structure members of type char can appear at any byte offset.

Structure members of other simple types must be aligned on an even

byte boundary, and padding is inserted if necessary. Any structure or

union member declared with the __aligned keyword is aligned on a

four-byte boundary, relative to the start of the structure or union, with

padding inserted as necessary. Substructures and subunions have the

same alignment requirements as their most restrictive members.

Structures and unions are padded at the end to the boundary of their

most restrictive member. For more information on structure padding,

see Chapter 13, "Writing Portable Code."

[] int bitfields are treated as unsigned int bitfields.

[] The order of allocation of bitfields for an int is from left to right.

Bitfields never cross storage unit boundaries.

[] The values of an enumeration type are normally of type int. However,

the SAS/C Compiler allows the declaration of char enum, short

enum, and long enum types. Enumeration types so declared are of

the specified type. For more information on using enumerated types,

272 Appendix 3

see Chapter 11, "Using Amiga Specific Features of the SAS/C

Language."

F.3.10 Qualiflers

[] Any reference to an object whose type is qualified by the keyword

volatile is considered an access to that object.

F.3.11 Declarators

[] There is no limit on the number of declarators that can modify an

arithmetic, structure, or union type.

F.3.12 Statements

[] There is no limit to the number of case values in a switch

statement.

F.3.13 Preprocessing Directives

[] The value of a single-character constant in a constant expression that

controls conditional inclusion matches the value of the same character

constant in the execution character set. Such a character can have a

negative value unless the unschar compiler option is active.

[] The compiler defines a search path for # include files that are

included with angle brackets (<>) around their names. This path is

defined as follows:

1. directories specified with the includedirectory compiler

option

2. the logical assignment INCLUDE:.

[] The compiler uses a slightly different search path for #include files

that are included with double quotes ("") around their names. This

path is defined as follows:

1. the current directory

2. the directory of the file containing the #include statement

3. directories specified with the includedirectory compiler

option

4. the logical assignment INCLUDE:.

[] Source file character sequences are not mapped. The string between the

angle brackets (<>) or double quotes ("") is passed to the file system.

Implementation Defined Behavior 273

[] The behavior of the libcall, syscall, and tagcall #pragma

directives is described in the SAS/C Development System Library

Reference. The behavior of the msg and flibcall #pragma

directives is described in Chapter 11, "Using Amiga Specific Features

of the SAS/C Language."

[] The definitions for the __DATE __and __TIME __preprocessor

macros contain the date and time as specified by the DateStamp

AmigaDOS function. This function always returns a value, so the date

and time are always available.

F.3.14 Library Functions

[] The NULL pointer constant to which the macro NULL expands is OL.

[] The diagnostic printed by the assert function is of the form:

Assertion (condition) failed in file filename at line number

where:

condition is the condition passed to the assert macro

filename is the current value of __FILE__

number is the current value of__ LINE__.

The assert function calls abort after printing the above line. For

more information, refer to the description of the assert function in

the SAS/C Development System Library Reference.

[] The sets of characters tested for by the isalnum, isalpha,

iscntrl, islower, isprint, and isupper functions is defined by

the entries in the external array __ctype. The following table lists

the hexadecimal values for each of the characters tested for by these

functions.

Function Name Character Type Hexadecimal Values

isalnum alphabetic or 0x30 to 0x39, 0x41 to 0x5a,

numeric 0x61 to 0x7a

isalpha alphabetic 0x41 to 0x5a, 0x61 to 0x7a

iscntrl control 0x00 to 0x1f, 0x7f

(continued)

274 Appendix 3

Function Name Character Type Hexadecimal Values

islower lowercase 0x61 to 0x7a

isprint printable 0x20 to 0x7e

isupper uppercase 0x41 to 0x5a

[] The mathematics functions return zero on domain errors.

[] On underflow range errors, the mathematics functions set the integer

expression errno to the macro ERANGE.

[] Zero is returned when the fmod function has a second argument of

zero.

[] The set of signals for the signal function are the minimum set

defined by the ANSI Standard: SIGABRT, SIGFPE, SIGILL, SIGINT,

SIGSEGV, and SIGTERM.

[] Refer to the description of the signal function in the SAS/C

Development System Library Reference for the semantics of the signals.

[] By default, the SIGINT signal results in calling the _ CXBRK function,

which terminates the program. Also by default, the SIGFPE signal

results in calling the _ CXFPE function, which sets errno and returns

to the caller causing the exception. By default, all other signals are

ignored.

[] The default handling is reset if the SIGILL signal is received by a

handler specified to the signal function.

[] The last line of a text stream does not require a terminating newline

character. No newline character is generated if one is not explicitly

written.

[] Space characters that are written out to a text stream immediately

before a newline character appear when read in.

[] The implementation does not append any NULL characters to data

written to a binary stream.

[] The file position indicator of an append mode stream is initially

positioned at the beginning of a file.

[] A write on a text stream does not cause the associated file to be

truncated beyond that point (see Section 4.9.3 of the ANSI Standard).

However, some of the modes truncate the file upon open. The following

table lists whether a file is truncated after a write.

Implementation Defined Behavior 275

File

Mode Truncated? Comments

"r" or "ra" N/A No writes allowed.

"w" or "wa" No The file is truncated at open

time only.

"a" or "aa" No All data are written after EOF.

"r+" or "ra+" No

"w+" or "wa+" No

"a+" or "aa+" No All data are written after EOF.

"rb" N/A No writes allowed.

"wb" No The file is truncated at open

time only.

"ab" No All data are written after EOF.

" rb+ " No

"wb+ " No

"ab+" No All data are written after EOF.

[] A call to the fopen function opens a buffered I/O stream. For writes,

data are stored into the buffer until it is full, and then the data are

written out. A call to the fflush function forces a write of any

buffered data.

You can use the library routines setbuf and setvbuf to change

between buffered, unbuffered, and line buffered modes. For more

information, refer to the description of these functions in the SAS/C

Development System Librar,v Reference.

[] A zero-length file can be created by either creating a file and not

writing anything to it or by truncating an existing file.

[] In general, a file can be opened multiple times as long as a previous

call to open the file did not physically create the file. However, some

devices or file-handlers may prevent multiple opens. Refer to the

documentation for the device or file handler that you are using.

[] A file cannot be deleted if there are any outstanding locks or file

handles on the file. In this case, the remove function sets errno and

OSERR and returns a nonzero value.

[] The output for %p conversion specification for the fprintf function

is the pointer's value in hexadecimal.

276 Appendix 3

[] The input for the %p conversion specification for the fscanf function

is a hexadecimal pointer, optionally preceded by 0x or 0x.

[] A minus (--) character that is neither the first nor the last character in

the scanlist for a % [ conversion specification in the fscanf function is

treated as a subrange specifier. That is, %[a-d] is equivalent to

%[abcd].

[] The functions fgetpos and ftell set the variable errno to the

value of EBADF for a bad file handle. Otherwise, errno is set as

described in the SAS/C Development System Library Reference for the

function lseek.

[] The perror function generates the following messages:

errno

Value Description

__________________________________

0 Unknown error code

EPERM User is not owner

ENOENT No such file or directory

ESRCH No such process

EINTR Interrupted system call

EIO I/O error

ENXIO No such device or address

E2BIG Arg list is too long

ENOEXEC Exec format error

EBADF Bad file number

ECHILD No child process

EAGAIN No more processes allowed

ENOMEM No memory available

EACCES Access denied

(continued)

Implementation Defined Behavior 277

errno

Value Description

___________________________

EFAULT Bad address

ENOTBLK Bulk device required

EBUSY Resource is busy

EEXIST File already exists

EXDEV Cross-device link

ENODEV No such device

ENOTDIR Not a directory

EISDIR Is a directory

EINVAL Invalid argument

ENFILE No more files (units) allowed

EMFILE No more files (units) allowed for this process

ENOTTY Not a terminal

ETXTBSY Text file is busy

EFBIG File is too large

ENOSPC No space left

ESPIPE Seek issued to pipe

EROFS Read-only file system

EMLINK Too many links

EPIPE Broken pipe

EDOM Math function argument error

ERANGE Math function result is out of range

[] If the functions calloc, malloc, or realloc are passed a size of

zero, the allocation fails, and the function returns a NULL pointer.

errno is set to the value of EINVAL.

[] The abort function closes all open and temporary level 2 I/O files.

The value passed to the exit function is the value that is passed back

to the system. For EXIT _ SUCCESS, the value returned is 0. For

EXIT _ FAILURE, the value returned is 20.

278 Appendix 3

[] The list of environment names are in the system file-handler ENV:.

Environment name values are modified through the putenv function.

[] The contents and mode of execution of the string passed to the

AmigaDOS system by the system function is as follows:

[] Under AmigaDOS Version 1.3, the AmigaDOS function Execute is

called.

[] Under AmigaDOS Version 2.0 or higher, the AmigaDOS function

System is called.

[] The system function returns the value returned from the AmigaDOS

Execute or System function. If the command processor cannot be

invoked, system returns a -1.

[] The strerror function returns the same error messages as the

perror function. The messages returned by the perror function are

listed above.

[] The default time zone is CST6, and the default for Daylight Savings

Time is 0.

[] The era for the clock function is based on the first call to the clock

function. The first call returns a value of zero, and subsequent calls

measure the processor time from that starting point. For more

information, refer to the description of the clock function in the

SAS/C Development System Library Reference.

F.3.15 Locale-Specific Behavior

[] The execution character set contains all ASCII characters in all locales.

[] The direction of printing is from left to right.

[] The period (.) is the decimal-point character.

[] Refer to the description of the i s ..functions in the SAS/C

Development System Library Reference for information on the

implementation-defined aspects of character-testing and case-mapping

functions.

[] The collation sequence for ASCII characters is used as the collation

sequence of the execution character set.

[] The SAS/C Development System uses the normal U.S. time and date

conventions for the C locale.

Implementation Defined Behavior 279

Type Values

____________________________________________

Weekday name Sun Mon Tue Wed Thu Fri Sat

Month name Jan Feb Mar Apr May Jun

Jul Aug Sep Oct Nov Dec

Date/Time DDD MMM dd hh:mn:ss YYYY

format Tue Jun 16 14:12:22 1992

280

281

Appendix 4

Converting From Aztec C

Options to SAS/C Options

Table A4.1 lists each of the Aztec 5.0 options and their equivalent SAS/C

options (if available). Some Aztec C options do not have equivalent SAS/C

options. Also, for some SAS/C options listed in this table, you must

specify additional options before the ones listed in this table will take

effect. For example, you must specify the genprotos option before the

genprotoparms option will take effect.

Table A4.1 Converting From Aztec C Options to SAS/C Options

Aztec C

Option SAS/C Option Comments

__________________________________________________________________________________________

-3 no equivalent

-5 no equivalent

-a disasm=filename These options generate assembly output.

noobjname

-at disasm=filename The debug option adds C source to the

debug = line assembly output.

noobj name

-bd stackcheck stackcheck is the default setting. You can

turn off stack checking with nostackcheck.

-bs debug=level You can specify one of five levels of debug

information.

-c2 cpu=68020

-d define symbol=value

-fa math=ieee You must also link with the appropriate math

library.

-ff math=ffp You must also link with the appropriate math

library.

-fm math=standard You must also link with the appropriate math

library.

(continued)

282 Appendix 4

TableA4.1 (continued)

Aztec C

Option SAS/C Option Comments

____________________________________________________________________________________________

-f8 math=68881 You must also link with the appropriate math

library.

-hi gst=gst-filename

-ho makegst=gst-filename

-i includedirectory=filename

-k no equivalent

-ma This option is on by default.

-mb no equivalent

-mc code=far

-md data=far

-me no equivalent

-mm stringmerge stringmerge forces the compiler to have only

one copy of identical strings and places these

strings in the code section. stringmerge also

places data declared static const into the

code section.

-ms nostringmerge

-o objectname=filename

-pa ansi

trigraph

-pb Bitfields are unsigned by default. Use the

signed keyword to declare a signed bitfield.

-pc ignore= 132 This option suppresses the warning for tokens

after #endif.

-pe no equivalent

-pl noshortint

-po oldpp

-pp unsignedchar

(continued)

Converting From Aztec C Options to SAS/C Options 283

TableA4.1 (continued)

Aztec C

Option SAS/C Option Comments

_____________________________________________________________________________________________

-ps shortintegers

-pt trigraph

-pu no equivalent

-qa genprotoparms

-qf errorrexx

-qp nogenprotostatics

-qq noverbose

noversion

-qs nogenprotoexterns

-qv no equivalent

-r4 data = faronly This option uses register A4 for register

variables. Do not use the __near or __chip

keywords if you use this option.

-sa This option is always on.

-sb no equivalent Include string.h in your source code.

-sf optimize

-sm no equivalent Include the appropriate header file in your

source code.

-sn This option is always on.

-so optimize

-sp The cleanup overhead reduction enhancement is

always on unless you specify debug=sf or

debug=ff.

-sr optimize

-ss stringmerge

-su This option is the default setting. You can

disable this option with the noautoreg option.

(continued)

284 Appendix 4

Table A4. 1 (continued)

Aztec C

Option SAS/C Option Comments

__________________________________________________________________________________________

-wa This option is the default setting. You can

disable this option with the ignore=88 option.

-wd

-we error=all This option turns all warnings into errors. To

make a specific message n an error message,

specify error=n.

-wl This option is the default setting.

-wn ignore=225

-wo This option is the default setting.

-wp This option is the default setting. You can

disable this option with the ignore= 100

option.

-wq no equivalent Use command line redirection.

-wr This option is the default setting. You can

disable this option with the

nowarnvoidreturn or ignore=85 option.

-ws ignore=all This option turns off all warnings.

-wu This option is the default setting. You can

disable this option with the ignore=93 option.

-ww maxerr=n The number n specifies the new error limit.

285

Appendix 5

Converting from Version 5

to Version 6

285 Introduction

285 Upgrading from Previous Versions

286 Converting Compiler Options

294 Specifying Version 6 Libraries

Introduction

This appendix lists the Version 6 options and libraries that are equivalent

to the Version 5 options and libraries.

Upgrading from Previous Versions

You should install Version 6 in a separate location from previous

versions of the compiler. Modify your startup sequence files to either

remove the LC: directory from your path or ensure that the directory

SC: C is on your search path before LC: .

In addition, make sure that include: and lib: get assigned to the

correct include and link library directories for Version 6. The compiler

for Version 6 does not use the QUAD: device used by previous versions.

In general, it is a good idea to recompile all your code when you

convert to Version 6. However, because the Version 6 libraries are ANSI-

compliant, your old programs may not compile or may generate many

warning messages. Appendix 1, "Solving Common Problems," provides

solutions to some of the problems you may encounter in converting to

Version 6.

You may want to use the sc5 command to convert older, seldom-used

projects. The sc5 command accepts Version 5 options and reads default

options from the file sascopts. However, it is recommended that you

become familiar with and begin using Version 6 as soon as possible.

You can use the lctosc conversion utility to convert your Version 5

sascopts file to a Version 6 scoptions file and to determine quickly

the Version 6 equivalent of a Version 5 option. The lctosc utility reads

the sascopts file in the current directory, reads any command-line

286 Appendix 5

options, converts the options to Version 6 options, and writes the results

to standard output. For example, to convert the sascopts file in the

current directory to a Version 6 scoptions file, enter the following

command at the Shell prompt:

lctosc >scoptions

To determine the Version 6 equivalent of the Version 5 option -cs, enter

the following command:

lctosc -cs

For code compiled with previous versions of the compiler, the new

version of CodeProbe can read the line number information but cannot

read the symbol information from the executables. Recompile your code

with the Version 6 compiler to produce usable debugging information for

symbols.

If you get unresolved symbols when you link your application, you may

be referring to symbols whose name has changed so as to make the

compiler conform to the ANSI Standard. In this case, look up the symbol

name in the SAS/C Development System Library Reference, Version 6.0 to

determine the new name, and change any references to the symbol name

in your code to the new name. Alternatively, you can choose to use the

define linker option to force all references to the old name to refer

instead to the new name.

Converting Compiler Options

Table A5.1 lists each of the Version 5 options and the equivalent

Version 6 option (if available). Some Version 5 options do not have

equivalent Version 6 options. Also, for some Version 6 options listed in

this table, you must specify additional options before the ones listed in

this table will take effect. For example, you must specify the link option

before any of the math=type options will take effect, and you must

specify the genprotos option before the genprotoparms option will

take effect.

Converting from Version 5 to Version 6 287

Table A5.1 Converting Version 5 Options to Version 6 Options

Version 5

Option Version 6 Option Description

____________________________________________________________________________________

-+ verbose Display commands as executed

-. noversion Suppress execution message

-ab bss=chip Force all uninitialized data (BSS) to chip memory

-ac code=chip Force all code to chip memory

-ad data=chip Force all initialized data to chip memory

-b data=near Base relative data (16-bit offsets)

-b0 data=far Non-base relative data (32-bit offsets)

-b1 data=near Base relative data (same as -b)

-ba data=auto Automatic non-base relative on data overflow

-c+ idlen=100 Allow longer identifiers for C++

-ca ansi Maximize ANSI compatibility

-cc commentnest Allow nested comments

-cd ignore=77 Allow $ in identifiers

-ce noerrorsource Suppress source line printing for errors

-cf Require function prototypes [1]

-ci nomultipleincludes Suppress multiple includes of same file

-ck ansi Suppress non-ANSI keywords (chip, far, near)

-c1 Use __aligned keyword [2] Align all externs on longword boundary

-cm multiplecharconstants Allow multiple character constants

-co oldpp Enable old style preprocessor

-cp Allow #if to span files

-cq structequivalence Allow passing of equivalent structure silently

(continued)

[1]sc5 did not require function prototypes. By default, Version 6 requires function prototypes. To suppress the Version 6

messages dealing with prototypes, specify ignore=100+161+154.

[2]Use the __aligned keyword to force individual objects to longword boundaries.

288 Appendix 5

TableA5.1 (continued)

Version 5

Option Version 6 Option Description

______________________________________________________________________________________________

-cr Disallow __asm keyword on function definitions

-cs stringmerge Create only one copy of identical strings

-ct Obsolete - does nothing

-cu unsignedchar Force all char declarations to unsigned char

-cw nowarnvoidreturn Shut off warning for return without a value

-cx noexternaldefs Treat all global declarations as externs

-C onerror = continue Continue on error

-d debug=line Enable debugging

-d0 nodebug Disable debugging

-d1 debug=line Enable debugging - dump line table

-d2 debug=symbol Generate symbol information

-d3 debug=symbolf lush Generate symbol information and flush registers

at every line

-d4 debug=full Generate full symbol information

-d5 debug= fullflush Generate full symbol information and flush

registers at line

-dsym=val define sym=val Define preprocessor symbol to a value

-E errorrexx Invoke Editor on error

-Efilename Invoke Editor on error, filename is an errorfile

name

-e Enable Asian character set (default is Japanese)

-e0 Enable Japanese character set (same as -e)

-e1 Enable Chinese character set

-e2 Enable Korean character set

-f math=ffp Use Motorola FFP (forces -fs)

-f8 math=68881 Generate code for Motorola 68881

(continued)

Converting from Version 5 to Version 6 Z89

TableA5.I (continued)

Version 5

Option Version 6 Option DescFiption

_____________________________________________________________________________________________

-fd precision=double Use double precision for both float and double

-ff math=ffp UseMotorolaFFP

-fi math=ieee Generate code for IEEE libraries

-f1 math= standard Use standard SAS/C floating point library

-fm precision=mixed Use single precision for float, double for double

-fs Use single precision for both float and double

-gc xref system Cross-reference compiler-provided files

-gd xrefmacros Cross-reference defined symbols

-ge List excluded lines

-gh listheaders List header files

-gi listsystem List included files

-gm listmacros List macro expansions

-gn listnarrow Print narrow lines

-go errorlisting Put errors and warnings to both stderr and

errorconsole listing file

-gs list List source

-gx xreference Produce cross reference listing

-g=filename listfile=filename Generate listing file with name filename

-Hname gst=gst-filename Read in precompiled header file name

-hb bss=fast Force all uninitialized data (BSS) to fast RAM

-hc code=fast Force all code to fast RAM

-hd data=fast Force all initialized data to fast RAM

-ix incdirectory=filename Specify directory to search for includes

-jn ignore=n Disable message number n

(conhnued)

290 Appendix 5

Table A5.1 (continued)

Version 5

Option Version 6 Option Description

__________________________________________________________________________________________

-jne error=n Make message number n an error instead of a

warning

-j*e error =all Turn all warnings into errors

-jni ignore=n Disable message number n (same as - jn)

-j*i ignore=all Disable all warnings

-jnw warn=n Enable message number n as a warning

-ja noerrorhighlight Suppress ANSI escape codes from error line

output

-L+ ob ject=object-file Specify additional linker objects

library = link-library

-La addsym Add symbol information when linking

-Lc smallcode Use small code memory model (16bit jumps)

-Ld smalldata Use small data memory model (16-bit data offsets)

-Lf math=ffp LinkwithFFPmathlibrary

-Lh maphunk Produce linker hunk map

-Li stdio Link with _ tinymain instead of _ main

-L1 maplib Produce linker library map

-Lm math=math-type Link with appropriate math library

-Ln stripdebug Suppress debugging information in executables

-Lo mapoverlay Produce linker overlay map

-Ls mapsym Produce linker symbol map

-Lt smallcode Use typical link options (same as -Lc, -Ld, -Lv,

smalldata or -Lcdv)

verbose

-Lv verbose Print verbose linking information

-Lx mapxref Produce linker cross-reference

(continued)

Converting from Version 5 to Version 6 291

TableA5.1 (conhnued)

Version 5

Option Version 6 Option Description

_______________________________________________________________________________________

-l Use __aligned keyword. [1] Align objects on longword boundaries

-M modified Compile only modified source files

-m cpu=any Generate code for Motorola 68000

-mO cpu=68000 Generate code for Motorola 68000 (same as -m)

-m1 cpu=68010 Generate code for Motorola 68010

-m2 cpu=68020 Generate code for Motorola 68020

-m3 cpu=68030 Generate code for Motorola 68030

-ma cpu=any Generate code for all Motorola processors (same

as -m)

-mc Disable cleanup overhead reduction enhancement

-ml libcode Generate code for resident library use

-mp absfuncpointer Generate 32bit references to functions

-mr noautoregister Disable automatic registerization

-ms optsize Generate code optimized for space

optimize

-mt opttime Generate code optimized for time

optimize

-N Disable linking from editor

-n identifierlength=8 Retain only 8 characters for identifiers

-nn identifier length=n Specify maximum length for identifiers

-O optimize Invoke global optimizer

-ox objectname=filename Place object file in filename

-Px programname=filename Use filename as the name of the final executable

module

(continued)

[1] Use the __aligned keyword to force individual objects to longword boundaries.

292 Appendix 5

TableA5.1 (continued)

Version 5

Option Version 6 Option Description

_________________________________________________________________________________________

-p preprocessonly Preprocess only

-pe nogenprotostatics Generate prototypes for external functions

-ph makegst=filename Generate precompiled header file

-pi Include identifier names in generated prototypes

-pp genprotoparms Generate prototypes with __PARMS for

portability

-pr genproto Generate prototypes for external and static

functions

-ps nogenprotoexterns Generate prototypes for static functions only

nogenprotodataitems

-pt nogenprototypedefs Suppress use of typedefs when generating

prototypes

-qx Place quad file in location x

-qne maxerr=n Quit compilation after n error/warnings

-qnw maxwarn=n Quit compilation after n warnings

-q maximumwarn= 1 Quit after 1 error or 1 warning (same as

maximumerrors=1 -q1e1w)

-r code=near Default function calls to near (PC-relative)

-r0 code=far Default function calls to far (Absolute)

-r1 code=near Default function calls to near (Same as -r)

-rr parms=register Pass and receive parameters in registers

-rs parms=stack Pass and receive parameters on the stack

-rb parms=both Generate code for both register and stack

conventions

-Rfilename objectlib=filename Place compiled objects into library filename

(continued)

Converting from Version 5 to Version 6 293

Table A5.1 (conhnued)

Version 5

Option Version 6 Option Description

_____________________________________________________________________________________________

-s Use default segment names text, data, and

udata

-sb=name bssname=name Specify a name for uninitialized data (BSS)

segment

-sc=name codename=name Specify a name for code segment

-sd=name dataname=name Specify a name for data segment

-t startup= cback Link with cback.o instead of c.o

-tb startup=cback Link with cback.o instead of c.o (same as -t)

-tc startup= catch Link with catch.o instead of c.o

-tcr startup=catchres Link with catchres.o instead of c . o

-tr startup=cres Link with cres.o instead of c.o

-t=x startup=filename Link with filename instead of c.o

-u Undefine all preprocessor symbols

-v nostackcheck Disable stack checking code

-w shortintegers Default to short integers

-x noexternaldefs Treat all global declarations as externals (same as

-cx)

-y saveds Load A4 with base address at start

-znnn ppbuf=nnn Set preprocessor expansion buffer size to nnn

294 Appendix 5

Specifying Version 6 Libraries

Table A5.2 lists each of the Version 5 libraries and the equivalent

Version 6 library. In Version 6, the standard libraries provide support

for registered parameters. To use registered parameters, you must

compile with the params=registers option, but you do not need a

special library.

Table A5.2

Version 5 Library Version 6 Library

_____________________________________________

lc.lib sc.lib

lcm.lib scm.lib

lcmieee.lib scmieee.lib

lcmffp.lib scmffp.lib

lcmr.lib scm.lib

lcms.lib scms.lib

lcmsr.lib scms.lib

lcm881.lib scm881.lib

lcmr881.lib scm881.lib

lcnb.lib scnb.lib

lcr.lib sc.lib

lcs.lib scs.lib

lcsnb.lib scsnb.lib

lcsr.lib scs.lib

295

Index

A __ aligned keyword 155-156

__ asm keyword 157-158

.a filename extension 78 __ chip keyword 156-157

abbreviated menus 50 __ far keyword 156-157

abort function 277 __ Inline keyword 159

absfuncpointer compiler option 85, 177 __ interrupt keyword 157

accelerator keys 50 __ near keyword 156-157

addressing data 176-177 __ regargs keyword 157-158

chip data 176 __ saveds keyword 158-159

modifying access to program code and __ stackext keyword 160-161

data 176-177 __ stdargs keyword 157-158

reentrant and non-reentrant programs amigaguide.se, AREXX macro 69

176 AmigaGuide, invoking 28

addsym linker option 121 ANSI compiler option 85, 181

addsymbols compiler option 85 ANSI Standard

__ aligned keyword 155-156 See also implementation defined

affecting definitions of functions 155 behavior

automatic variable problems 156 See also portable code, v.~riting

ensuring stack alignment 156 default argument promotion rules 187

example 156 format for incoming command line 140

pointer register variables 161 ANSI compliant C compilers 182

Alt keys AREXX interface 65-73

equivalence 60 AREXX port 68

independent operation 60 command summary 70-73

Amiga keys commands without keystroke equivalents

caution against redefining 60 70-73

Amiga-specific features of SAS/C language communicating with external programs

153-169 68-69

C++ style comments 168 definition 73

comma (,) operator 168 executing a series of editor commands

common model external data 168-169 65-68

enumerated types 167 keystroke equivalents for commands

equivalent structures 164-166 70-73

implicit structure references 164 AREXX macros

managing stack space 160-161 amigaguide.se 69

national characters in variable names assigning to keys 66

168 definition 73

nested comments 168 deletetabs.se 69

#pragma statements 161 163 examples 66-68, 69

sizeof operator 168 findsym.se 69

special keywords 154 159 indent.se 70

unnamed unions 163-164 newline character (\n) 65

zero-length arrays 163-164 provided with the compiler 69-70

296 Index

AREXX macros (conhnued) autotermination function 145-147

.se suffix required 65 definition 145

tolower.se 70 example 146

toupper.se 70 level 1 or 21/O functions not used 147

unindent.se 70 order in which modules called 147

argc and argv _STD preceding function name 145

ANSI Standard requirement 140 __dtors array 146, 147

Shell environment 135-136 Autowrap option 61-62

Workbench environment 136 Aztec C options, converting 281-284

arguments

raising argument limits 140-141

argumentsize= compiler option 85-86 B