PCjs Machines
Home of the original IBM PC emulator for browsers.
QuickC 2.5 Tool Kit
The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.
Microsoft QuickC Compiler - TOOL KIT
────────────────────────────────────────────────────────────────────────────
Microsoft(R) QuickC(R) Compiler - TOOL KIT
VERSION 2.5
────────────────────────────────────────────────────────────────────────────
MICROSOFT CORPORATION
Information in this document is subject to change without notice and does
not represent a commitment on the part of Microsoft Corporation. The
software described in this document is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to copy
the software on any medium except as specifically allowed in the license or
nondisclosure agreement. No part of this manual may be reproduced or trans-
mitted in any form or by any means, electronic or mechanical, including
photocopying and recording, for any purpose without the express written
permission of Microsoft.
(C) Copyright Microsoft Corporation, 1988, 1990. All rights reserved.
Printed and bound in the United States of America.
Microsoft, MS, MS-DOS, CodeView, QuickC, and XENIX are
registered trademarks and Windows is a trademark of Microsoft Corporation.
COMPAQ is a registered trademark of Compaq Computer Corporation.
Hercules is a registered trademark and InColor is a trademark
of Hercules Computer Technology.
Intel is a registered trademark of Intel Corporation.
IBM is a registered trademark of International Business
Machines Corporation.
Document No. SY10425-0290
OEM D703-2Z
10 9 8 7 6 5 4 3 2 1
Table of Contents
────────────────────────────────────────────────────────────────────────────
Introduction
About This Manual
Elsewhere in This Package
Key to Document Conventions
PART I Tool Kit Tutorial
────────────────────────────────────────────────────────────────────────────
Chapter 1 Creating Executable Programs
1.1 Compiling and Linking: An Overview
1.2 Using the QCL Command
1.3 Specifying File Names
1.4 Controlling Compiling and Linking with QCL Options
1.4.1 Compiling without Linking
1.4.2 Compiling Only Modified Functions
1.4.3 Optimizing Programs
1.4.4 Naming Output Files
1.4.5 Turning Off Language Extensions
1.4.6 Debugging and Syntax Checking
1.4.7 Controlling the Preprocessor
1.4.8 Compiling for Specific Hardware
1.4.9 Choosing Memory Models
1.4.10 Controlling the Linking Process
1.4.11 Other QCL Options
1.5 Invoking the Linker Directly: The QLINK Command
1.5.1 Giving Input to the QLINK Command
1.5.2 QLINK Options
Chapter 2 Maintaining Software Libraries with LIB
2.1 Why Use a Library?
2.2 The LIB Command
2.3 Listing the Contents of a Library
2.4 Modifying the Contents of a Library
2.4.1 Modifying the Library
2.4.2 Adding a Module
2.4.3 Deleting a Module
2.4.4 Replacing a Module
2.4.5 Copying and Moving Modules from a Library
2.5 Creating a New Library
2.6 Other Ways of Using LIB
Chapter 3 Maintaining Programs with NMAKE
3.1 How NMAKE Works
3.2 Building a Simple Description File
3.2.1 Description Blocks
3.2.2 The CC Macro
3.3 Invoking NMAKE
3.3.1 Invoking NMAKE from the DOS Command Line
3.3.2 Invoking NMAKE with a Response File
3.4 NMAKE Options
3.4.1 Controlling Input
3.4.2 Controlling Execution
3.4.3 Controlling Output
3.5 Building Complex Description Files
3.5.1 Using Special Characters to Modify Commands
3.5.2 Using Macros
3.5.3 Using Inference Rules
3.5.4 Using Directives
3.6 Other NMAKE Features
PART II Reference to QuickC Tools
────────────────────────────────────────────────────────────────────────────
Chapter 4 QCL Command Reference
4.1 The QCL Command Line
4.2 How the QCL Command Works
4.3 QCL Options
4.3.1 /A Options (Memory Models)
4.3.2 /batch (Compile in Batch Mode)
4.3.3 /c (Compile without Linking)
4.3.4 /C (Preserve Comments during Preprocessing)
4.3.5 /D (Define Constants and Macros)
4.3.6 /E (Copy Preprocessor Output to Standard Output)
4.3.7 /EP (Copy Preprocessor Output to Standard Output)
4.3.8 /F (Set Stack Size)
4.3.9 /Fe (Rename Executable File)
4.3.10 /Fm (Create Map File)
4.3.11 /Fo (Rename Object File)
4.3.12 /FP Options (Select Floating-Point-Math Package)
4.3.13 /G0, /G1, /G2 (Generate Instructions for 8086, 80186,
or 80286 Processor)
4.3.14 /Gc, /Gd (Use FORTRAN/Pascal or C Calling Convention)
4.3.15 /Ge, /Gs (Turn Stack Checking On or Off)
4.3.16 /Gi (Use Incremental Compilation)
4.3.17 /Gr (Register Calling Convention)
4.3.18 /Gt (Set Data Threshold)
4.3.19 /Gw,
/GW (Generate Code for Windows(tm) Function Calls)
4.3.20 /HELP (List the Compiler Options)
4.3.21 /I (Search Directory for Include Files)
4.3.22 /J (Change Default char Type)
4.3.23 /Lc, Lr (Compile for Real Mode)
4.3.24 /Li (Link Incrementally)
4.3.25 /Ln (Link without C Run-Time Startup Code)
4.3.26 /ND, /NT (Name the Data or Code Segments)
4.3.27 /nologo (Suppress Display of Sign-On Banner)
4.3.28 /O Options (Optimize Program)
4.3.29 /P (Create Preprocessor-Output File)
4.3.30 /Ta, /Tc (Specify Assembly Language or C Source File)
4.3.31 /U, /u (Remove Predefined Names)
4.3.32 /V (Set Version String)
4.3.33 /W, /w (Set Warning Level)
4.3.34 /X (Ignore Standard Include Directory)
4.3.35 /Ze, /Za (Enable or Disable Language Extensions)
4.3.36 /Zi, /Zd (Compile for Debugging)
4.3.37 /Zl (Remove Default-Library Name from Object File)
4.3.38 /Zp (Pack Structure Members)
4.3.39 /Zr (Check Pointers)
4.3.40 /Zs (Check Syntax Only)
4.3.41 Giving Options with the CL Environment Variable
4.4 Controlling Stack and Heap Allocation
Chapter 5 QLINK
5.1 Overview
5.2 Invoking QLINK
5.2.1 Command Line
5.2.2 Prompts
5.2.3 Response File
5.2.4 How QLINK Searches for Libraries
5.3 QLINK Memory Requirements
5.4 QLINK Options
5.4.1 /BA (Running in Batch Mode)
5.4.2 /CO (Link for Debugging)
5.4.3 /CP (Set the Maximum Allocation Space)
5.4.4 /DO (Order Segments)
5.4.5 /DS (Load Data at High Address)
5.4.6 /E (Pack Executable Files)
5.4.7 /F (Optimize Far Calls)
5.4.8 /HE (View the Options List)
5.4.9 /HI (Place Executable in High Memory)
5.4.10 /INC (Prepare for ILINK)
5.4.11 /INF (Display Linker-Process Information)
5.4.12 /LI (Include Line Numbers in Map File)
5.4.13 /M (List Public Symbols)
5.4.14 /NOD (Ignore Default Libraries)
5.4.15 /NOE (Ignore Extended Dictionary)
5.4.16 /NOF (Disable Far-Call Optimization)
5.4.17 /NOG (Preserve Compatibility)
5.4.18 /NOI (Employ Case Sensitivity)
5.4.19 /NOL (Suppress Sign-On Banner)
5.4.20 /NON (Order Segments without Nulls)
5.4.21 /NOP (Disable Segment Packing)
5.4.22 /O (Set the Overlay Interrupt)
5.4.23 /PACKC (Pack Contiguous Segments)
5.4.24 /PACKD (Pack Contiguous Data)
5.4.25 /PADC (Pad Code Segments)
5.4.26 /PADD (Pad Data Segments)
5.4.27 /PAU (Pause during Linking)
5.4.28 /SE (Set Maximum Number of Segments)
5.4.29 /ST (Set Stack Size)
5.4.30 /T (Create a .COM File)
5.5 Linker Operation
5.5.1 Alignment of Segments
5.5.2 Frame Number
5.5.3 Order of Segments
5.5.4 Combined Segments
5.5.5 Groups
5.5.6 Fixups
5.6 Using Overlays
5.6.1 Restrictions on Overlays
5.6.2 Overlay-Manager Prompts
Chapter 6 LIB
6.1 Invoking LIB
6.1.1 Command Line
6.1.2 Prompts
6.1.3 Response File
6.2 LIB Commands
6.2.1 Creating a Library File
6.2.2 Add Command (+)
6.2.3 Delete Command (-)
6.2.4 Replace Command (- +)
6.2.5 Copy Command (*)
6.2.6 Move Command (- *)
Chapter 7 NMAKE
7.1 Overview of NMAKE
7.1.1 Using a Command Line to Invoke NMAKE
7.2 NMAKE Description Files
7.2.1 Description Blocks
7.2.2 Comments
7.2.3 Macros
7.2.4 Inference Rules
7.2.5 Directives
7.2.6 Pseudotargets
7.3 Command-Line Options
7.4 Using a Response File to Invoke NMAKE
7.5 The TOOLS.INI File
7.6 In-Line Files
7.7 NMAKE Operations Sequence
Appendix A Exit Codes
A.1 Exit Codes with NMAKE
A.2 Exit Codes with DOS Batch Files
A.3 Exit Codes for Programs
A.3.1 QLINK Exit Codes
A.3.2 LIB Exit Codes
A.3.3 NMAKE Exit Codes
Appendix B Working with QuickC Compiler Memory Models
B.1 Near, Far, and Huge Addressing
B.2 Using the Standard Memory Models
B.2.1 Creating Tiny-Model Programs
B.2.2 Creating Small-Model Programs
B.2.3 Creating Medium-Model Programs
B.2.4 Creating Compact-Model Programs
B.2.5 Creating Large-Model Programs
B.2.6 Creating Huge-Model Programs
B.3 Using the _near, _far, and _huge Keywords
B.3.1 Library Support for _near, _far, and _huge
B.3.2 Declaring Data with _near, _far, and _huge
B.3.3 Declaring Functions with the _near and _far Keywords
B.3.4 Pointer Conversions
Appendix C Hardware-Specific Utilities
C.1 Fixing Keyboard Problems with FIXSHIFT
C.2 Using Hercules Graphics
C.2.1 Support for Cards and Display Characteristics
C.2.2 The MSHERC Driver
C.2.3 Using a Mouse
C.2.4 Setting Hercules Graphics Mode
C.3 The Mouse Driver
Appendix D Error Messages
D.1 Compiler Errors
D.1.1 Fatal Error Messages
D.1.2 Compilation Error Messages
D.1.3 Warning Messages
D.1.4 Compiler Limits
D.2 Command-Line Errors
D.2.1 Command-Line Error Messages
D.2.2 Command-Line Warning Messages
D.3 Run-Time Errors
D.3.1 Math Error Messages
D.3.2 Run-Time Error Messages
D.4 QLINK Error Messages
D.4.1 Fatal Error Messages
D.4.2 Error Messages
D.4.3 Warning Messages
D.5 LIB Error Messages
D.5.1 LIB Fatal Error Messages
D.5.2 LIB Warning Messages
D.6 NMAKE Error Messages
D.6.1 Fatal Error Messages
D.6.2 Compilation Error Message
D.6.3 Warning Messages
Glossary
Index
Introduction
────────────────────────────────────────────────────────────────────────────
The Microsoft(R) QuickC(R) Compiler Tool Kit is a set of utility programs
that you can use to develop your own programs outside the QuickC integrated
environment. These tools include
■ QCL, the Microsoft QuickC compiler, which compiles QuickC source
programs and invokes QLINK (see below) to link object files
■ QLINK, the QuickC linker, which combines object files that you've
created with the Microsoft QuickC compiler (or any other Microsoft
language product) into executable programs
■ LIB, the Microsoft Library Manager, which combines object files into
libraries
■ NMAKE, the Microsoft Program-Maintenance Utility, which maintains
large programs that consist of separate modules
■ The special-purpose utilities, including MSHERC (which provides
support for Hercules(R) graphics adapters) and FIXSHIFT (which fixes a
bug in certain keyboards that makes them incompatible with QuickC and
some other programs)
The Tool Kit provides an alternative to the QuickC environment by letting
you compile and link from the command line. You may find that it's easiest
to use the integrated environment during the early stages of program
development, when you're still tinkering with programs and you need to
compile, run, and debug programs fast. Then, when you're fine-tuning and
maintaining your code, use the tools from the Tool Kit for additional
control and flexibility.
────────────────────────────────────────────────────────────────────────────
NOTE
Microsoft documentation uses the term "OS/2" to refer to the OS/2
systems─Microsoft Operating System/2 (MS(R) OS/2) and IBM(R) OS/2.
Similarly, the term "DOS" refers to both the MS-DOS(R) and IBM Personal
Computer DOS operating systems. The name of a specific operating system is
used when it is necessary to note features that are unique to that system.
────────────────────────────────────────────────────────────────────────────
About This Manual
If you're new to Microsoft language products, this book will teach you how
to get the most out of the tools provided in this package. Experienced users
of Microsoft languages will be able to find information about existing
utilities quickly, as well as learn about the utilities provided with QuickC
(including the NMAKE utility and the hardware-specific support utilities
documented in Appendix C, "Hardware-Specific Utilities").
Part 1 of the manual is a tutorial that illustrates the ways you'll use the
QCL, QLINK, LIB, and NMAKE utilities for everyday programming work. Each
chapter describes the most common options of each utility.
Part 2 is a reference to the Tool Kit. Each chapter describes a tool in
detail, showing the syntax of the command line and describing all of the
tool's options and their effects.
Appendixes of this manual list the exit codes returned by each tool, explain
the use of QuickC memory models, describe the MSHERC and FIXSHIFT utilities,
and describe the error messages associated with each tool.
Following the appendixes is a glossary, which defines the terms introduced
in this manual, as well as other C-specific terms you may find helpful.
Elsewhere in This Package
As you're reading this manual, you may want to refer to other manuals or
online documentation for information about other parts of the product. This
manual assumes that you've installed the QuickC compiler software as
described in Up and Running. If you haven't yet installed the software,
install it now.
Read C for Yourself if you're new to C programming and want to learn how to
write C programs. That manual includes an appendix that summarizes the C
language and common C library routines.
Insert the disk titled "Learning the QuickC Environment" and type learn if
you want to learn how to use the QuickC integrated environment. The lesson
titled "Basic Skills" shows how to get online help for any command or option
within the environment or for any part of the C language or run-time
library.
Key to Document Conventions
This book uses the following document conventions:
Examples Description
────────────────────────────────────────────────────────────────────────────
STDIO.H, PATH, C:\BIN, QCL, Uppercase letters indicate file names,
NMAKE, DX, _TEXT segment names, registers, and terms used
at the DOScommand level.
_cdecl, int, printf, alloc_text, Boldface letters indicate C keywords,
#undef, DosCreateThread operators,
language-specific characters, and
library functions, as well as OS/2
functions.
QCL A.C B.C C.OBJ This font is used for examples, user
input, program output, and error
messages in text.
if (expression) Italic letters indicate placeholders for
statement1 information you must supply, such as a
file name. Italics are also occasionally
used for emphasis in the text.
«option» Items inside double square brackets are
optional.
#pragma pack {1 | 2} Braces and a vertical bar indicate a
choice among two or more items. You must
choose one of these items unless double
square brackets surround the braces.
QCL options «file...» Three dots following an item indicate
that more items having the same form may
appear.
while() A column of three dots tells you that
{ part of the example program has been
. intentionally omitted.
.
.
}
CTRL+ENTER Small capital letters are used for the
names of keys on the keyboard. When you
see a plus sign (+) between two key
names, you should hold down the first
key while pressing the second. The
carriagereturn key, sometimes appearing
as a bent arrow on the keyboard, is
called ENTER.
Color Graphics The first time an acronym is used, it is
Adapter (CGA) often spelled out.
"argument" Quotation marks enclose a new term the
first time it is defined in text.
PART I Tool Kit Tutorial
────────────────────────────────────────────────────────────────────────────
The Microsoft QuickC Compiler Tool Kit is divided into two parts. Part 1 is
a tutorial designed to get you started with the QuickC tools. It does not
cover the tools in detail, but instead gives you a "quick start" on the
options and procedures that you are most likely to need. If you are new to
the QuickC Compiler, consult Part 1 to learn how to use the Tool Kit and to
become familiar with the most useful options of each tool. After you've
gained some experience with the tools, turn to Part 2, "Reference to QuickC
Tools," for the "nuts and bolts" of each tool.
Part 1 starts with QCL and LINK, the fundamental tools you must use to
create executable programs outside the QuickC environment. It goes on to the
Library Manager (LIB), with which you can create libraries of compiled code.
The part concludes with NMAKE, a program-maintenance utility that helps you
automate the process of rebuilding software.
Chapter 1 Creating Executable Programs
────────────────────────────────────────────────────────────────────────────
Version 2.5 of the Microsoft QuickC Compiler environment is designed for
maximum convenience and efficiency. If you prefer, however, you can also
create programs from the DOS command line. The QuickC Compiler provides two
programs for this purpose: QCL and QLINK.
This chapter introduces the basic concepts and the most common options of
the QCL and QLINK commands. See Chapter 4, "QCL Command Reference," in Part
2 of this manual for a complete description of all the QCL options (listed
alphabetically). See Chapter 5, "QLINK," also in Part 2, for a complete
explanation of how QLINK works.
1.1 Compiling and Linking: An Overview
The first step in creating a QuickC program is to enter the source code
using an editor and save it in a file. This file is known as a C "source
file." You can enter separate parts of the program in different source files
and compile these source files separately.
Once you've saved your C source file(s), two steps are required to convert
it to an executable file:
1. Compiling. During this step, the QuickC compiler converts the C source
files to object files. An object file contains binary code but is not
yet in execut-able form.
2. Linking. During this step, the linker takes the object files created
during compilation, combines them with standard libraries plus any
other object files and libraries you specify, and creates an
executable file that can be run under DOS.
You can use the QCL command to perform both compiling and linking. On the
QCL command line, give the names of any C source files that you want to
compile and the names of any additional object files or libraries that you
want to link. As an example, consider the following simple command:
QCL SAMPLE.C EXAMPLE.C
This command tells QCL to compile and link the source files SAMPLE.C and
EXAMPLE.C. The QCL command performs these two steps:
1. QCL compiles the source files SAMPLE.C and EXAMPLE.C and creates
object files. The object files created by QCL have the same base name
as the source files, plus the extension .OBJ.
2. The linker links the object files that were created in the compiling
step with the default library, SLIBCE.LIB. (QLINK uses this particular
library because there are no command-line options that specify
otherwise. See Section 4.3.1, "/A Options," for the names of the other
possible libraries.) QLINK then creates the final executable file,
SAMPLE.EXE, giving it the base name of the first source file specified
on the command line (SAMPLE), plus the extension .EXE.
The two steps described above are illustrated in Figure 1.1.
(This figure may be found in the printed book.)
Figure 1.1 and the command it illustrates give a simple demonstration of
what QCL can do. You can also use QCL to compile and link any combination of
source files, object files, and additional libraries. The following section
explains the syntax of the QCL command, which you can use to control more
complex compile/link operations.
1.2 Using the QCL Command
The QCL command, which you'll use for most compiling and linking operations,
has the following format:
(This figure may be found in the printed book.)
The items in italics are different pieces of input (described below) that
you must give on the QCL command line:
■ The options are QCL options, which control some aspect of the
compiling or linking process. They may appear anywhere on the command
line and in most cases affect any files that appear later on the
command line. The most commonly used QCL options are described in
Section 1.4, "Controlling Compiling and Linking with QCL Options." See
Chapter 4, "QCL Command Reference," for complete information on all
QCL options.
■ The sourcefiles are the names of the C source files that you are
compiling. Normally, these file names have .C extensions.
■ The objfiles are the names of additional object files that you want to
link into your program. QCL compiles the source files, then links the
resulting object files with objfiles. For example, given the command
QCL MAIN.C AUX.OBJ
QCL compiles MAIN.C, creating the object file MAIN.OBJ. QCL then tells
the linker to link MAIN.OBJ and AUX.OBJ to create the executable file
named MAIN.EXE.
If you give a file name with any extension other than .C or .LIB, or
with no extension, QCL assumes you are giving it the name of an object
file. For example, in the command
QCL OBJECT1 OBJECT2.OBJ
the QCL command assumes OBJECT1 has the .OBJ extension and tells the
linker to link OBJECT1.OBJ and OBJECT2.OBJ.
■ The libraries are the names of libraries that you want to link with.
These names must have .LIB extensions.
Ordinarily, you don't need to give a library name unless your program
calls functions that are stored in libraries other than the standard
combined C libraries (which you created during installation). If you
use libraries created
by a company other than Microsoft, or if you have created a private
library of functions and your program calls functions in this library,
you must give the private-library name on the QCL command line. For
example, the command
QCL MAIN.C MYLIB.LIB
tells QCL to compile MAIN.C, creating the object file MAIN.OBJ. Then
QCL tells the linker to link MAIN.OBJ with functions in the default
combined library SLIBCE.LIB and the MYLIB.LIB library given on the
command line.
■ The linkoptions are linker options, which control some aspects of the
linking process. Linker options are described in Section 1.4.10,
"Controlling the Linking Process."
■ If you're not sure that your program will fit in available memory, you
can indicate that certain parts of the program will become "overlays."
That is, they will be stored on disk and read into
memory─overlaid─only when needed. To specify overlays, enclose the
modules you want to overlay in parentheses on the QCL command line.
For example, the command
QCL RESIDNT.C (ONCALL.C) MAIN.C
creates a program named RESIDNT.EXE with an overlay module named
ONCALL.OBJ. Whenever control passes to ONCALL.OBJ, it is read into
memory from disk. (See Section 5.6, "Using Overlays," for more
information about overlays and restrictions on their use.)
1.3 Specifying File Names
A DOS file name has two parts: the "base name," which includes up to eight
characters before the period (.), and the "extension," which includes the
period and up to three characters following the period. The extension
identifies the type of the file. The QCL command uses the extension of each
file name to determine how to process the corresponding file, as explained
in Table 1.1.
Uppercase and lowercase
In file names, any combination of uppercase and lowercase letters is legal.
For example, SHUTTLE.C and Shuttle.c represent the same file.
Path names
Any file name can include a path name. When a file name includes a path
name, QCL assumes the file to be in that path. You can supply either a full
path name or a partial path name. A full path name includes a drive name and
one or more directory names. A partial path name is the same as a full path
name but omits the drive name, which QCL assumes to be the current drive.
If you don't give a path name, QCL assumes that all source and object files
given on the command line are in the current directory.
Examples
QCL MAIN.C AUX.C OBJECT1.OBJ OBJECT2 OBJECT3.MOD
This command line compiles the files MAIN.C and AUX.C, creating object files
named MAIN.OBJ and AUX.OBJ. These object files are then linked with the
object files OBJECT1.OBJ, OBJECT2.OBJ, and OBJECT3.MOD to form an executable
file named MAIN.EXE (since the base name of the first file on the command
line is MAIN). Note that QCL assumes the extension .OBJ for OBJECT2 because
no extension is given on the command line.
QCL TEAPOT.C \MSG\ERROR C:\GRAPHICS\GRAPHICS.LIB
This command line tells QCL to compile the file TEAPOT.C and to link the
resulting object file with \MSG\ERROR.OBJ and the library GRAPHICS.LIB. QCL
assumes the extension .OBJ for the file \MSG\ERROR because none was
specified. It looks for the library in the \GRAPHICS directory on drive C:.
Table 1.1 Interpretation of File Extensions
╓┌──────────────────────────────┌─────────────┌──────────────────────────────╖
Extension Assumed Type Processing
────────────────────────────────────────────────────────────────────────────
.C C source QCL compiles the file.
.OBJ Object QCL tells the linker to link
the file.
.LIB Library The linker links this library
with the object files QCL
created from source files and
the object files given on the
command line.
Any other extension or none Object QCL tells the linker to link
the file. You must end the
file name with a period (.)
if the file name has no
Extension Assumed Type Processing
────────────────────────────────────────────────────────────────────────────
if the file name has no
extension. Otherwise, QCL
assumes the extension .OBJ.
────────────────────────────────────────────────────────────────────────────
1.4 Controlling Compiling and Linking with QCL Options
The QCL command offers a variety of options that control the compiling and
linking processes and modify the files created during each stage. For
example, you can specify QCL options to rename output files, to control the
operation of the QuickC preprocessor, to take advantage of an 80286
processor or a math coprocessor, or to optimize your program for speed or
size.
QCL options can begin with either a forward slash ( / ) or a dash (-). In
this book, the slash is used.
────────────────────────────────────────────────────────────────────────────
Important
Except as noted, QCL options are case sensitive, so you must use the exact
combination of uppercase and lowercase letters shown in this book.
────────────────────────────────────────────────────────────────────────────
Some QCL options require arguments. For example, you may be required to give
a number or a file name as part of a QCL option. For some options, you must
put a space between the option and the argument; for others, you must place
the argument immediately after the option. The description of each option
gives its exact syntax.
The following sections list the most commonly used QCL options by type. See
Chapter 4, "QCL Command Reference," for a complete list of QCL options or
for more information about the effects of an option described in this
chapter.
Help with QCL options
If you need help with QCL options, use the following command:
QCL /HELP
This command displays a list of commonly used QCL options with a brief
description of each option. Unlike other QCL options, /HELP is not case
sensitive; you can type any combination of lowercase and uppercase letters.
1.4.1 Compiling without Linking
When you compile with the /c option, QCL compiles the source files you give
on the command line but ignores any object files or libraries that you give
on the command line. Because QCL does not invoke the linker when you give
this option, it does not create an executable file.
You can use this option in the following cases:
■ To compile separate modules that you want to put in a library using
the LIB utility (described in Chapter 2 of this book)
■ To link in a separate step as described later in this chapter (for
example, in an NMAKE file)
Example
QCL /c SPELL.C THESRS.C
The example above compiles the C source files SPELL.C and THESRS.C, creating
the object files SPELL.OBJ and THESRS.OBJ. Because the /c option keeps QCL
from invoking the linker, this command doesn't create an executable file.
1.4.2 Compiling Only Modified Functions
The /Gi option allows you to compile programs much faster than usual. It
speeds compilation by telling QCL to compile only the parts of each C source
file that have changed since the file was last compiled. This process is
called "incremental compilation."
Information about the incremental compilation of each source file is
maintained in an MDT (Module Description Table) file. One MDT file can
contain this information for more than one source file.
If you give a file-name argument following the /Gi option, the compiler
writes the change information for all the source files into that single MDT
file. Do not put spaces between the /Gi option and the file name.
If you specify the /Gi option without a file name, the compiler creates an
MDT file for each C source file that you give on the command line. Each MDT
file has the base name of the source file and the .MDT extension.
Generally, when you compile with /Gi, only the changed functions in each C
source file are recompiled. The entire file is recompiled only if a change
affects the entire program.
See Section 4.3.16 in Part 2, "Reference to QuickC Tools," for details about
incremental compilation and the /Gi option.
Example
QCL /GiASC.MDT alpha.c num.c
The example above compiles the changed portions of the files ALPHA.C and
NUM.C. It creates a single .MDT file named ASC.MDT into which it writes
change information for both source files.
1.4.3 Optimizing Programs
"Optimizing" a program is the process of making the program, or a part of
the program, as fast or as small as possible. The following QCL options can
help with this process:
Option Effect
────────────────────────────────────────────────────────────────────────────
/O, /Ot Optimizes the program for execution time
rather than code size. The compiler
makes the executable file faster, but it
does not make the file size as small as
possible.
/Ol Optimizes loops in your program. This
option makes the executable file run
faster.
/Gs Turns off stack-checking routines in
your program. This option reduces the
size of the executable file, but it may
cause stack-overflow errors to go
undetected.
/Ox Performs all possible speed
optimizations. This option combines the
effects of the /Ot, /Ol, and /Gs
options.
/Od Does not optimize your program. This
option speeds compilation, although it
may result in a slightly slower
executable file.
You may combine the /O options on the command line, specifying more than one
letter following /O. For instance, /Olt optimizes loops and execution time.
If the letters conflict, QCL uses the last one in the list.
1.4.4 Naming Output Files
Use the following options to name the object and executable files that QCL
creates. Note that file names must immediately follow the options, with no
intervening spaces.
Option Effect
────────────────────────────────────────────────────────────────────────────
/Foobjfile Gives the name objfile to the object
file. You can give more than one /Fo
option; each option applies to the next
C source-file name on the command line.
For example,
QCL /FoOBJ1 SRC1.C SRC2.C
compiles SRC1.C, creating an object file
named OBJ1.OBJ, then compiles SRC2.C,
creating an object file named SRC2.OBJ.
If you give objfile without an extension,
QCL automatically appends the .OBJ
extension to the file name. If you give
a complete path name with objfile, QCL
creates the object file in that path.
For example,
QCL /Fo\MODS\OBJ1.OBJ SRC1.C
compiles SRC1.C, creating an object file
named OBJ1.OBJ in the \MODS directory.
If you give only a drive or directory
specification, the specification must
end with a backslash ( \ ) so that QCL
can distinguish it from a file name.
/Feexefile Gives the name exefile to the executable
file. If you give exefile without an
extension, QCL automatically appends the
.EXE extension to the file name. If you
give a complete path name with exefile,
QCL creates the executable file in that
path. If you give a path specification
without a file name, the path
specification must end with a backslash
( \ ) so that QCL can distinguish it
from a file name.
If you don't tell it otherwise, QCL names output files as follows:
Type of File Default
────────────────────────────────────────────────────────────────────────────
Object Same base names as the original C source
files with extensions of .OBJ. For
example, if you compile a C source file
named LEX.C, QCL creates an object file
named LEX.OBJ.
Executable Same base name as the first file name on
the command line plus an extension of
.EXE. For example,
QCL LEX.C GENCOD.OBJ OPTIMIZ
creates an executable file named LEX.EXE
by compiling LEX.C (creating LEX.OBJ),
then linking LEX.OBJ, GENCOD.OBJ, and
OPTIMIZ.OBJ.
1.4.5 Turning Off Language Extensions
QuickC supports keywords and syntax that are additions to the standard C
language. The /Za option tells the compiler to treat such Microsoft-specific
keywords as ordinary identifiers and to display error messages if your
programs use any other extended-language features.
Compile with the /Za option if you plan to port your programs to
environments that don't recognize Microsoft extensions to the C language, or
if you want to ensure that your programs are strictly compatible with the
ANSI (American National Standards Institute) definition of the C language.
Microsoft extensions include the _near, _far, _huge, _cdecl, _fortran, and
_pascal keywords, as well as several usages of standard C constructs that
are not defined in the ANSI standard. (See Section 4.3.35, "/Ze, /Za," in
Part 2 for more information about these extensions.)
1.4.6 Debugging and Syntax Checking
Several QCL options are useful when you want the compiler to check the
syntax of your program, or when you want to track down logic errors using
the debugger built into the QuickC environment (or other Microsoft
debuggers). These options fall into three categories:
1. Checking syntax
2. Setting warning levels
3. Compiling for a debugger
1.4.6.1 Checking Syntax
If you want to make sure that your program is free from syntax errors
without compiling and linking the program, compile it with the /Zs option.
This option tells the QCL command to display error messages if your program
has syntax errors. QCL doesn't create object or executable files.
1.4.6.2 Setting Warning Levels
You may get warning messages during compilation if your program has problems
that aren't serious enough to stop the compiling process. You can easily
identify a warning message because it begins with the word "warning" and has
"C4" as the first two characters in the error number.
The "warning level" options, /w and /W0 through /W4, allow you to suppress
warning messages for certain classes of problems. In general, the lower the
warning level, the less strict the compiler is about flagging possible
errors in your program. You might want to use a lower warning level if
you're intentionally using the flexibility of C in some operations and you
want to suppress warnings about these operations.
The warning-level options are described below:
Option Effect
────────────────────────────────────────────────────────────────────────────
/W0, /w Turns off all warning messages.
/W1 Displays severe warning messages. (This
is the level of warnings you get by
default.)
/W2 Displays all /W1 warnings plus warnings
for problems such as functions without a
declared return type, functions that
have a return type other than void and
don't have a return statement, and data
conversions that cause loss of precision.
/W3 Displays all /W2 warnings, plus warnings
for function calls that precede their
function prototypes in the source code.
/W4 Displays all /W3 warnings, plus warnings
for any non-ANSI constructs. The /W4
option is similar to the /Za option,
which gives error messages and aborts
the compilation if non-ANSI features are
used.
/WX Treats all warnings as fatal errors. If
there are any warning messages, the
compilation aborts and no object file is
produced.
Appendix D lists all warning messages in order of error number. The
description of each message indicates the warning level that must be set in
order for the message to appear.
1.4.6.3 Compiling for a Debugger
You must compile your program with one or more of the following QCL options
if you plan to debug it within the QuickC environment or with another
Microsoft debugger:
Option Effect
────────────────────────────────────────────────────────────────────────────
/Zi Puts information needed for debugging
into the program. Use /Zi if you plan to
debug your program with the QuickC
debugger or with the Microsoft
CodeView(R) window-oriented debugger
provided with other Microsoft language
products.
/Zd Puts limited symbolic information in the
object file. Use /Zd if you plan to
debug your program with SYMDEB, the
Microsoft Symbolic Debug Utility that
was shipped with earlier versions of
Microsoft language products.
/Zr Checks for null or out-of-range pointers
in your program. Optional if you plan to
debug with the QuickC debugger.
1.4.7 Controlling the Preprocessor
The QCL command provides several options that control the operation of the
QuickC preprocessor. These options allow you to define macros and manifest
(symbolic) constants from the command line, change the search path for
include files, and stop compilation of a source file after the preprocessing
stage to produce a preprocessed source-file listing.
1.4.7.1 Defining Constants
The C preprocessor directive #define defines a name for a constant or for C
program text. Wherever the name appears in your program, the preprocessor
substitutes the text you've defined for that name.
You can use the /D option to define constants from the QCL command line.
This option has the form
/Didentifier=string
or
/Didentifier=number
The identifier is the name you're defining; string or number is the text or
numeric value that is substituted for the name. The string must be in double
quotation marks if it includes spaces.
You can leave off the equal sign and the string or number. If you do, the
identifier is defined and its value is set to 1. You can use this format
when you need to define an identifier but do not care what its value is. For
example, /DCREATE defines an identifier named CREATE and sets it equal to 1.
If you've defined a number for identifier, you can "turn off" the definition
by using the following form of the /D option:
/Didentifier=
When you compile with this form, the identifier is no longer defined within
your program and no value is substituted for it.
QCL allows you to define up to 15 constants using the /D option for each
constant. You may be able to define as many as 20, depending on the other
options you specify. (See Section 1.4.7.4, "Removing Predefined
Identifiers," for more information about the number of constants you are
allowed to define.)
1.4.7.2 Searching for Include Files
The QuickC preprocessor directive
#include filename
tells the QuickC preprocessor to insert the contents of filename in your
source program, beginning at the line where the directive appears. Include
files pro-vided with Microsoft QuickC contain prototypes of standard C
library functions and the constants used by these functions. If filename is
enclosed in angle brackets (< >), the preprocessor looks for the file in the
directories given by the INCLUDE environment variable. If filename is
enclosed in quotation marks (" "), the preprocessor looks for the file first
in the current directory and then in the directories specified by the
INCLUDE variable. (Enter the SET command at the DOS prompt to see the
INCLUDE variable and the directories it specifies.)
Use the following options to override the usual search order without
changing the value of the INCLUDE variable:
Option Effect
────────────────────────────────────────────────────────────────────────────
/X Tells the preprocessor not to search for
include files in the directory given by
the INCLUDE variable.
/I directory Tells the compiler to search the given
directory for include files before it
searches the directories given by the
INCLUDE environment variable. You can
give more than one /I option, each
specifying a directory. Directories are
searched in the order in which they
appear on the command line.
1.4.7.3 Creating Preprocessor Listings
If you want to see output from the QuickC preprocessor, give one or more of
the following options on the QCL command line:
Option Effect
────────────────────────────────────────────────────────────────────────────
/E Writes preprocessor output to the
standard output device (your screen,
unless you redirect output to another
device or to a file). The /E option also
inserts #line directives in the output.
The #line directives renumber the lines
of the preprocessed file so that, if you
recompile the preprocessed file, the
errors generated during later stages of
processing refer to the original source
file rather than to the preprocessed
file.
/P Writes preprocessor output to a file and
inserts #line directives in the output
file. The preprocessor gives the file
the base name of your C source file and
an extension of .I.
/EP Writes preprocessed output to the
standard output device but does not
insert #line directives.
/C Leaves comments in the preprocessed
output. Normally, the preprocessor
strips comments from the source file.
This option has an effect only if you
also give the /E, /P, or /EP option.
1.4.7.4 Removing Predefined Identifiers
The QuickC compiler automatically defines certain identifiers, which
represent conditions such as the current operating system or memory model.
Your programs may use these identifiers along with the QuickC preprocessor
directives #if, #ifdef, #ifndef, #else, #elif, and #endif to tell the
compiler to "conditionally compile" portions of the program. For example,
the #ifdef directive tells the compiler to compile subsequent code only if a
given identifier is defined. Similarly, the #ifndef directive tells the
compiler to compile subsequent code only if a given identifier is not
defined. (For more information about preprocessor directives, see Chapter 7,
"Preprocessor Directives," in C For Yourself.)
The predefined identifiers are as follows: _QC, MSDOS, M_I86, M_I86mM,
M_I8086, M_I286, NO_EXT_KEYS, and _CHAR_UNSIGNED. (For more information on
how and when these identifiers are defined, see Table 4.5, "Predefined
Names," in Section 4.3.31.) If you don't use these identifiers for
conditional compilation, you might want to remove their definitions from the
program. For each predefined identifier that you remove, you can define an
additional identifier (over the default limit of 15) with the /D option on
the QCL command line.
The following options turn off predefined identifiers:
Option Effect
────────────────────────────────────────────────────────────────────────────
/U identifier Turns off the definition of identifier
/u Turns off the definition of all
predefined identifiers
1.4.8 Compiling for Specific Hardware
QuickC creates executable programs that run on any processor in the 8086
family, including the 8086/8088, 80186, 80286, 80386, and 80486.
If your programs will always run on machines with 80186 or 80286 or higher
processors, or on machines with coprocessors, you can compile your programs
with the following options to take advantage of the specific hardware
configuration:
Option Effect
────────────────────────────────────────────────────────────────────────────
/G1 Uses the 80186 instruction set for your
program. You cannot run the program on
machines with 8088 or 8086 processors.
/G2 Uses the 80286 instruction set for your
program. You cannot run the program on
machines with 8088, 8086, or 80186
processors.
/FPi87 Handles math for floating-point types (
float and double) by generating
instructions for an 8087 or 80287 math
coprocessor. This reduces the size of
your program; however, the program must
be run on a system with a coprocessor
present.
The /G2 and /FPi87 options are the most commonly used options for
hardware-specific compilation, but others are available. See Sections 4.3.12
and 4.3.13 for details.
1.4.9 Choosing Memory Models
The "memory model" your program uses determines how many 64K (kilobytes)
segments the compiler allocates for its data and code. Ordinarily, you don't
need to choose the memory model explicitly if your program's code can fit
into one 64K segment and your program's data can fit into one 64K segment.
This memory allocation, called the small memory model, is the default used
by the QCL command.
If your program exceeds the default limit for code or data, you must use one
of the other memory models. The following list summarizes the options for
the memory model:
Option Effect
────────────────────────────────────────────────────────────────────────────
/AT Tiny model: provides one 64K segment for
both data and code. The compiler
produces a .COM file instead of a .EXE
file.
/AS Small model: provides one 64K segment
for data and one 64K segment for code.
No one data item can exceed 64K. This is
the most efficient model for QuickC
programs. QCL uses this option
automatically if you don't give a
memory-model option, so you never need
to give this option explicitly.
/AM Medium model: provides one 64K segment
for data and multiple 64K segments for
code. No one data item can exceed 64K.
This is the most efficient model if your
program exceeds the 64K default limit
for code.
/AC Compact model: provides multiple 64K
segments for data and one 64K segment
for code. No one data item can exceed
64K. This is the most efficient model if
your program exceeds the 64K default
limit for data.
/AL Large model: provides multiple 64K
segments for data and for code. No one
data item can exceed 64K.
/AH Huge model: same as large model, except
that individual data items can be larger
than 64K.
Although memory models give you additional flexibility in dealing with large
programs, you must use them with care to avoid problems in your programs.
See Section 4.3.1 or Appendix B for further information about the use of
memory models.
1.4.10 Controlling the Linking Process
Several QCL options control the linking process rather than the compiling
process. You've already encountered one of these options: the /Fe option,
which renames the executable file. Here are the others:
Option Effect
────────────────────────────────────────────────────────────────────────────
/Fm «mapfile» Creates a map file showing program
segments in order of appearance in the
program. If you give mapfile without an
extension, QCL automatically appends the
.MAP extension to the file name. If you
give a complete path name with mapfile,
QCL creates the map file in that path.
For example,
QCL /Fm\MODS\MAP1.MAP SRC1.C
compiles and links SRC1.C, creating a
map file named MAP1.MAP in the \MODS
directory. If the path specification
lacks a file name, it must end with a
backslash ( \ ) to distinguish it from a
file name.
The mapfile argument is optional; if you
don't specify a new name, the linker
gives the map file the same base name as
the executable file, with an extension
of .MAP. For example,
QCL /Fm MOD1.C MOD2.C
creates an executable file named
MOD1.EXE and a map file named MOD1.MAP.
/F number Sets the stack size to the given number
of bytes. The number may be in decimal,
octal, or hexadecimal. (As in C programs,
octal numbers start with the prefix 0
and hexadecimal numbers with the prefix
0x.) If you don't give this option, the
executable file uses a 2K stack. Use
this option if your program gets
stack-overflow errors at run time.
See Sections 4.3.8 - 4.3.10 for detailed information on these options and on
map files.
The /link option
Another way of controlling the linking process is to use the /link option on
the QCL command line. The /link option allows you to specify QLINK command
options─not QCL options─without invoking the linker separately. On the QCL
command line, the /link option must follow the source and object files and
all QCL options. QCL passes directly to the linker the options that follow
/link. These options are described in Section 1.5.2, as well as in Section
5.4.
Example
QCL /FPi87 /Fm SRC1.C SRC2 /link /INF
In the example, the /Fm and /FPi87 options apply to the QCL command and the
/INF option applies only to the linker. As a result of this command line,
QCL compiles SRC1.C to run on an 8087 or 80287 processor, then passes
SRC1.OBJ and SRC2.OBJ to the linker. The /Fm option to QCL causes the linker
to create a map file named SRC1.MAP. The /INF option, which applies only to
the linker and not to QCL, causes the linker to display information about
the linking process.
1.4.11 Other QCL Options
QCL supports a large number of options besides the ones already described,
which control all aspects of the compilation process. Some of the more
commonly used options are described below:
Option Effect
────────────────────────────────────────────────────────────────────────────
/Gc Calling-convention option. Uses the
FORTRAN/Pascal naming and calling
conventions for functions in the program.
Compile with this option if you want to
call routines that use the Microsoft
Pascal or Microsoft FORTRAN calling
conventions or if you need to save space
in the executable file. (See Section
4.3.14 for more information about the
effects of this option.)
/Gt«number» Threshold option. Tells the compiler to
allocate data items larger than number
in a new data segment. If you give this
option with no number, QCL allocates
items larger than 256 bytes in their own
segment. If you don't give this option,
QCL allocates items larger than 32,767
bytes in their own segment.
This option applies if you compile with
the compact (/AC), large (/AL), or huge
(/AH) memory model. See Appendix B for
more information about memory models and
allocation.
/NTtextsegname Name-text-segment option. Assigns the
given name to the text segment. The
space is optional between /NT and
textsegname. The text segment contains
the program code for the entire program
(if you compile with the /AS option, the
/AT option, the /AC option, or no
memory-model option) or for the module
you are compiling (if you compile with
the /AM, /AL, or /AH option).
/Zl Library options. Tells the compiler not
to put the name of the appropriate
combined library in the object file. Use
this option to compile modules that you
want to put in a library with the LIB
utility.
/Zp«number» Pack option. Stores structure members
after the first on number-byte
boundaries. The number argument, if
given, may be 1, 2, or 4; if it isn't
given, QCL assumes a value of 2. This
option may reduce the size of executable
files, although it may also slow program
execution.
See Section 4.3 for descriptions of all the QCL options.
1.5 Invoking the Linker Directly: The QLINK Command
If you are building a large program composed of many source files, you may
prefer to compile the source files in one step, and then link the resulting
object files in a separate step. For example, in the first step, you would
compile your C source files as shown below:
QCL /c SOURCE1.C SOURCE2.C
Then, in the second step, you would link the resulting object files, plus
any additional object files or libraries, as shown below:
QCL SOURCE1 SOURCE2 GRAPHICS.LIB
As illustrated in the second step, if you give only object files or
libraries on the QCL command line, the QCL command simply passes the object
files and libraries to the linker.
Instead of using the QCL command to link, you can invoke the linker directly
by entering the QLINK command. Because the linker prompts you for any input
it needs, using QLINK makes it easier to specify file names and options; you
don't need to enter everything on the command line, although you may do so
if you wish.
The remainder of this section explains how to use the QLINK command to link
object files and libraries.
1.5.1 Giving Input to the QLINK Command
The simplest way to invoke the linker directly is to give the command
QLINK
If you don't give any other information on the command line, QLINK prompts
you for input. The following list shows how to respond to each prompt:
Prompt Response
────────────────────────────────────────────────────────────────────────────
Object Modules: The names of all object files that you
want to link, separated by plus signs.
If all the names do not fit on one line,
type a plus sign as the last character
on the line. QLINK repeats the prompt on
the next line, and you can type
additional object-file names.
Type a library name in response to this
prompt if you want to include the entire
library in the executable file. Make
sure the library name has an extension
of .LIB. (If you type the library name
in response to the "Libraries:" prompt
below, QLINK places in the executable
file only the library modules that are
called in your source files.)
Run File: The name of the executable file that you
want to create. If you press ENTER
without typing a name, QLINK uses the
base name of the first object file you
gave plus the extension .EXE. This name
is shown in brackets in the prompt.
List File: The name of the map file, which shows
segments in your program. If you press
ENTER without typing a name, QLINK
doesn't create a map file. If you enter
a name without an extension, QLINK adds
the .MAP extension automatically.
Libraries: The names of libraries other than the
standard combined libraries that you
want to link with the object files. If
you enter a library name without an
extension, QLINK assumes the extension
.LIB. If you enter more than one library
name, put a plus sign between each
library name and the next.
You can supply linker options as part of the response to any prompt. See
Section 1.5.2, "QLINK Options," for a list of commonly used options.
Input on the command line
If you prefer, you can give all your input to QLINK on the command line. The
QLINK command line has the form shown below:
(This figure may be found in the printed book.)
Commas must appear as shown above to separate the names of the different
files. You may type a semicolon to terminate the command line anywhere after
the list of object files. The semicolon tells QLINK to use defaults for the
remaining files. QLINK options may appear anywhere on the command line.
The prompts previously described correspond to the command line as follows:
"Object Modules" is equivalent to objfiles, "Run File" to exefile, "List
File" to mapfile, and "Libraries" to libraries.
Input in a response file
QLINK allows you one other alternative for providing input. You can enter
responses for all prompts in a file, then invoke QLINK with the following
command:
QLINK @responsefile
Replace responsefile with the name of the file that contains your responses.
The responses should look the same as if you were typing them in response to
prompts. For example, type all object-file names on the first line, the
executable-file name on the second line, and the map-file name on the third
line. Use a plus sign at the end of a line to continue a response on the
next line. Leave a blank line in the file if you want QLINK to use the
default for a prompt. Place QLINK options at the end of any response or
place them on one or more separate lines.
1.5.2 QLINK Options
QLINK options allow you to control the operation of the linker. If you're
using the QCL command to link, give these options after the /link option on
the command line. If you're using the QLINK command to link, these options
may appear anywhere on the command line. QLINK options must be preceded by a
slash.
Not all QLINK options are applicable to QuickC programs. Some options are
useful only for assembly-language programs. This section describes only the
options that are useful for QuickC programs. See Chapter 5, "QLINK," for a
complete list of options.
Case sensitivity
QLINK options are not case sensitive, so you can type any combination of
uppercase and lowercase letters for each option.
Abbreviations
Because some QLINK options have long names, QLINK allows you to abbreviate
each name. The abbreviation must include enough continuous letters to
distinguish the option from others. Letters that you can leave off are
surrounded by brackets in the following sections. In general, this book
refers to QLINK options by their shortest possible abbreviations.
Numerical parameters
Some QLINK options take numbers as parameters. You may specify the numbers
in decimal, hexadecimal, or octal. As in C programs, hexadecimal numbers are
identified by the prefix 0x and octal numbers by the prefix 0.
Help with QLINK options
If you need help with QLINK options, use the following command:
QLINK /help
The linker responds by displaying a list of all the available options.
1.5.2.1 Controlling the Linking Process with Options
Use the QLINK options described below to control the linking process:
Option Effect
────────────────────────────────────────────────────────────────────────────
/BA«TCH» Tells the linker to continue processing
if it can't find one of the files you've
given, rather than stop processing and
prompt you. Also prevents QLINK from
displaying its program banner and
echoing the contents of response files
on standard output.
Use this option in batch files or NMAKE
description files if you're building
large executable files and don't want
the linker to stop processing if it
can't find a file it needs.
/INC«REMENTAL» Prepares the program for subsequent
incremental linking, which links only
the object files that have changed since
the last link. This is significantly
faster than regular linking. The /PADC
and /PADD options, used for padding code
and data, should also be specified when
you use this option. This option is
incompatible with the tiny memory model
and with the /E (Pack .EXE file) option.
/INF«ORMATION» Tells the linker to display information
about the linking process, including the
linking phase and the name of each
object file being linked.
/M«AP» Includes a full public-symbol listing in
the map file.
/NOD«EFAULTLIBRARYSEARCH» «: Tells the linker not to search the
filename» standard C combined libraries to find C
library functions. If you use this
option, you should explicitly specify
the name of a standard combined library.
/PAU«SE» Tells the linker to pause before it
creates the executable file and to
display a message. This allows you to
insert a new disk to hold the executable
file.
If you're running on a machine without a
hard disk, you might want to create the
executable file on a different removable
disk. In this case, you would swap the
current disk for the new disk before
creating the executable file. If QLINK
displays the message
Temporary file tempfile has been
created.
Do not change diskette in drive letter.
you should terminate your link session,
copy the temporary file named tempfile
to the disk where you want to create the
executable file, and enter the QLINK
command again.
1.5.2.2 Optimizing the Executable File
The following QLINK options make the executable file faster, smaller, or
both:
Option Effect
────────────────────────────────────────────────────────────────────────────
/E«XEPACK» Compresses the executable file. This
option reduces the program's size and
load time. However, you cannot use the
QuickC or CodeView debugger to debug the
program.
/F«ARCALLTRANSLATION» Reduces the size of the executable file
and increases its speed by optimizing
far calls to procedures in the same
segment as the calling procedure.
/PACKC«ODE»«:number» Given with the /F option, improves the
efficiency of medium-, large-, and
huge-model programs by grouping
neighboring code segments.
/PACKD«ATA»«:number» Improves the efficiency of compact- and
large-model programs by grouping
neighboring data segments.
1.5.2.3 Modifying the Executable File
You can use the following QLINK options to modify the executable file (for
example, to specify the maximum number of segments or set the stack size):
Option Effect
────────────────────────────────────────────────────────────────────────────
/CP«ARMAXALLOC»:number Sets the maximum number of 16-byte
paragraphs needed by the program to
number. The number may be any decimal,
octal, or hexadecimal number in the
range 1- 65,535 decimal.
/SE«GMENTS»:number Sets the maximum number of segments a
program can have to number. The number
may be any value in the range 1-3,072
decimal. If you don't give this option,
a program may have no more than 128
segments.
/ST«ACK»:number Sets the stack size to number bytes. The
number may be any decimal, octal, or
hexadecimal number in
the range 1- 65,535 decimal. If
you don't give this option, the stack
is 2K.
1.5.2.4 Other QLINK Options
The QLINK options described in this chapter are those most typically used
when linking QuickC programs. The linker supports additional options,
including several that apply only to assembly-language programs. For
complete information on all QLINK options, see Chapter 5, "QLINK," in Part 2
of this manual.
Chapter 2 Maintaining Software Libraries with LIB
────────────────────────────────────────────────────────────────────────────
The Microsoft Library Manager (LIB) lets you create and maintain object-code
libraries. You can use the library manager to
■ List the contents of a library
■ Modify the contents of an existing library
■ Copy object code from the library
■ Create a new library
This chapter gives you an introduction to libraries and then explains how to
perform each of the tasks listed above.
2.1 Why Use a Library?
Object modules
An "object-code library" is an organized collection of object code; that is,
a library contains functions and data that are already assembled or compiled
and are ready for linking. The structure of a library supports the mass
storage of common procedures─procedures called by a variety of programs.
Each library consists of components. These components, called "object
modules" (or sometimes just "modules"), can be added, deleted, changed, or
copied. When you give the linker a library as input, the linker efficiently
scans the library and uses only the modules needed by the program.
Object-code libraries are typically used for one of three purposes:
1. To support high-level languages. Languages, including C, BASIC, and
FORTRAN, perform input/output and floating-point operations by calling
standard support routines. Because the support routines are available
in a library, the compiler never needs to regenerate code for these
routines. Libraries that contain standard support routines are called
"standard libraries."
2. To perform complex and specialized activities, such as data-base
management or advanced graphics. Libraries containing such routines
are often sold by third-party software vendors or are provided by the
makers of the compiler (in the case of graphics libraries for the
Microsoft QuickC Compiler).
3. To support your own work. If you have created routines that you find
useful for a variety of programs, you may want to put these routines
in a library. That way, these routines do not need to be recoded or
recompiled. You save development time by using work you have already
done.
2.2 The LIB Command
The LIB command has the form shown below:
(Please refer to the printed book.)
(This figure may be found in the printed book.)
The items in italics are different pieces of input (described below) that
you must give on the LIB command line:
■ The oldlibrary field gives the name of a library. Object-code
libraries typically have names that end with .LIB. You specify a
library in this field whenever you use LIB.
■ The options field specifies one or more LIB options. For most tasks,
you won't need to use any of these options. The options are described
in Chapter 6, "LIB," in Part 2 of this manual.
■ The commands field gives the commands that modify the contents of the
library. Commands are described in Section 2.4, "Modifying the
Contents of a Library."
■ The listfile field specifies a file into which LIB puts a list of the
library's contents. The next section tells how to list the contents of
a library.
■ The newlibrary field specifies a name for the modified library if the
commands you give change an existing library. See Section 6.1.1.5,
"Output Library," for more information on this field.
2.3 Listing the Contents of a Library
You can use LIB to obtain a symbol listing for any object-code library.
Listings are useful because they give the exact names of modules and of
"public symbols," which are names of functions and global variables that can
be referenced throughout the program. You may need a listing if you want to
modify a library, as described in the next section.
To list the contents of a library, you need to use only the oldlibrary field
and the listfile field. Use a semicolon (;) to terminate the command so that
LIB does not prompt you for additional input.
In the oldlibrary field, give the name of the library you want to examine.
You can enter a full path name or a file name without a path. If you do not
include a file extension, LIB assumes the default .LIB extension. Typically,
object-code libraries have a .LIB extension.
In the listfile field, give the name of the file in which you want the
listing to be placed. If you enter the name of a file that does not yet
exist, LIB creates the file. If you enter the name of a file that already
exists, LIB replaces the current contents of the file with the new listing.
For example, the following command line directs LIB to place a listing of
the contents of MYLIB.LIB into the file LISTING.TXT:
LIB MYLIB, LISTING.TXT;
The listing file summarizes the contents of the entire library. Each listing
file contains two kinds of information, in this order:
1. A list of public symbols with corresponding modules for each
2. A list of modules with corresponding symbols for each
Modules, which are basic to the operation of LIB, are discussed in the next
section. For a more detailed description of listing files, see Section
6.1.1.4, "Cross-Reference-Listing File," in Part 2 of this manual.
2.4 Modifying the Contents of a Library
You can use LIB to alter the contents of any object-code library. There are
a number of reasons why you might want to do so. For example, if you work
with higher-level-language libraries, you may want to replace a standard
routine with
your own version of the routine. Or you may want to add a new routine to the
standard library so your routine is available along with the standard
routines.
LIB operations involve "object files" and object modules:
Item Description
────────────────────────────────────────────────────────────────────────────
Object file An independent file containing object
code corresponding to one source file.
An object file normally has a .OBJ file
extension.
Object module A self-contained unit within a library,
consisting of one or more routines. An
object module in a library is in almost
all respects identical to the
corresponding object file. The object
module, however, has no file extension
or path because it is not a separate
file.
The sections that follow discuss both items extensively. Remember: a unit of
object code in a library is called an object module; the corresponding unit
of code outside a library is stored in a file called an object file.
2.4.1 Modifying the Library
To modify an object-code library, carry out the following steps:
1. To add or replace an object module, first compile or assemble the new
code. If the procedure you want to add is part of a program, copy the
source code into its own file and compile or assemble it separately.
2. Add, delete, or replace the module with the command line
LIB oldlibrary commands;
in which commands consists of one or more LIB commands that use the
syntax shown later in this section.
Note that in step 2 above, the command line does not use all the LIB fields.
You can, however, include a listfile if you want a file listing. You can
also use the newlibrary field to preserve old library contents. If you enter
a newlibrary, LIB places the updated library contents in newlibrary and
leaves the contents of oldlibrary unchanged. Otherwise, LIB updates the
contents of oldlibrary and saves the old contents in the file
oldlibrary.BAK.
You can use the library as input to the linker once the contents change. Any
routines you have added or replaced become part of the library and can be
called by your programs.
2.4.2 Adding a Module
To add an object file to a library, use the command
+file
in which file is the name of the object file you want to add as a module.
You can specify a complete path name for file if the object file is not in
the current directory. If the file-name extension is .OBJ, you can leave off
the extension; LIB assumes the .OBJ extension by default. LIB adds the
object module at the end of the library. The library contains only the base
name of the module without the .OBJ extension.
For example, the following command line adds the module PRINTOUT to the
library MYLIB.LIB, by copying the contents of the object file
\SOURCE\PRINTOUT.OBJ:
LIB MYLIB +\SOURCE\PRINTOUT;
You can also add the entire contents of one library to another by specifying
a library name for file. Remember to enter a complete file name (including
extension) because LIB assumes that files in the commands field have the
.OBJ extension. For example, the following command line adds the complete
contents of the library SMALL.LIB to the library SUPER.LIB:
LIB SUPER +SMALL.LIB;
2.4.3 Deleting a Module
To delete an object module from a library, use the command
-module
in which module is the name of a module already stored in the library. For
example, the following command deletes the module DELETEME from the library
BIGLIB.LIB:
LIB BIGLIB -DELETEME;
2.4.4 Replacing a Module
To replace an object module within a library, use the command
- +module
in which module is the name of a module that is currently stored in the
library. The old copy of module is deleted from the library. The current
contents of module.OBJ are copied into the library. For example, to replace
the QuickC small-model library version of printf() with your own version,
execute these steps:
1. Write your own version of printf(), and compile or assemble it.
2. Make sure that the resulting object file is named PRINTF.OBJ and that
PRINTF.OBJ is located in the current directory. (If you look at a
listing of the library, you will see that the public symbol for the
printf() function is _printf(). The name of the module, however, is
printf(). If you have any doubt about the exact name of an object
module, get a listing of the library before trying to modify the
library.)
3. Issue the following command line:
LIB SLIBCE -+PRINTF;
You can combine any number of operations in the commands field. Spaces
between the commands are acceptable but not necessary. For example, the
following command line adds a new module (NEWFUN), replaces a current module
(OLDFUN), and deletes another current module (BYENOW):
LIB MYLIB +NEWFUN -+OLDFUN -BYENOW;
In the example above, the files NEWFUN.OBJ and OLDFUN.OBJ serve as input for
the modules NEWFUN and OLDFUN, respectively.
2.4.5 Copying and Moving Modules from a Library
You can extract any object module from a library. The extracted object
module is copied into a .OBJ file with the same name as the module. For
example, if you extract a module named OLDFUN, LIB copies it into the object
file named OLDFUN.OBJ. If a file with that name already exists, its contents
are overwritten.
To copy a module into a .OBJ file, use the command
*module
in which module is the name of the module you wish to copy from the library.
The module is placed in the file module.OBJ.
For example, the following command line copies the printf() module from the
Microsoft QuickC small-model library and places the contents of this module
into the object file PRINTF.OBJ:
LIB SLIBCE *PRINTF;
You can move a module out of a library with the following command:
-*module
Moving a module is similar to copying a module, in that LIB copies the
contents of the module into a file named module.OBJ. The move command (-*),
however, deletes the module from the library after copying it.
2.5 Creating a New Library
When you use LIB, creating a new object-code library is easy. You simply
combine two techniques:
1. In the oldlibrary field, enter the name of a file that does not yet
exist.
2. In the command field, use the add command (+file) to list entries for
the new library. (Technically, this step is not required; however, if
you do not use the add command, the library will be empty.)
For example, if the file NEWLIB.LIB does not yet exist, the following
command line creates this file:
LIB NEWLIB +MYPROC +MYFUN +PRINTIT;
The object files MYPROC, MYFUN, and PRINTIT provide the input for the new
library.
2.6 Other Ways of Using LIB
This chapter has covered the basic operations of the LIB utility so that you
can quickly begin to create and maintain your own libraries. For a complete
description of LIB, see Chapter 6, "LIB," in Part 2 of this manual. Some
additional features described in that chapter include the following:
■ How to make LIB case sensitive so that it treats Print and PRINT as
two different module names.
■ How to specify alignment of modules within a library.
■ How to let LIB prompt you for command fields, rather than requiring
you to enter them all on a single command line.
■ How to use a response file to give input to LIB. Response files are
useful for giving unusually long command lines or for giving the same
command line repeatedly.
Chapter 3 Maintaining Programs with NMAKE
────────────────────────────────────────────────────────────────────────────
The Microsoft Program-Maintenance Utility (NMAKE) helps to automate software
development and maintenance. Following instructions that you supply, NMAKE
determines whether a program is out-of-date and, if so, how to update it.
Your instructions list all the sources, include files, and libraries the
program depends on and specify the commands to update the program.
NMAKE, however, is not limited to updating programs. It can also perform
other actions, such as building distribution disks, cleaning up directories,
and so forth. Any procedure that requires the latest version of several
files is a good candidate for NMAKE. By using NMAKE for these operations
instead of performing them manually, you can avoid the headaches of invalid
source modules, old libraries, and forgotten include files.
You can use NMAKE in the following situations:
■ In program development, to update an executable file whenever any of
the source or object files has changed
■ In library management, to rebuild a library whenever any of the
modules in the library has changed
■ In a networking environment, to update the local copy of a file that
is stored on the network whenever the master copy has changed
This chapter describes what NMAKE does, defines the terms you need to
understand, and tells you how to use NMAKE to manage your QuickC Compiler
projects. For detailed information, see Chapter 7, "NMAKE," in Part 2 of
this manual.
3.1 How NMAKE Works
NMAKE relies on a "description file" (sometimes called a "makefile") to
determine which files to update, when to update them, and what operations to
perform. The description file for a QuickC program lists the source and
header files needed to build each object file, and all the object files
needed to build the executable program. The description file tells NMAKE
whether changes have been made to source, header, or object files. If source
or header files have been changed, NMAKE recompiles the object file; if any
object files have been changed, NMAKE relinks the program. The description
file also contains the QCL commands that must be executed to build the
object files and the program.
Description files are made of several elements:
■ Description blocks, which tell NMAKE how to build files. See Section
3.2.1, "Description Blocks," for further information.
■ Macros, similar to C macros, which provide a shorthand notation that
allows you to change certain values when the file is processed. See
Section 3.5.2, "Using Macros," for further information.
■ Inference rules, which tell NMAKE what to do in the absence of
explicit commands. See Section 3.5.3, "Using Inference Rules," for
further information.
■ Directives, which provide conditionals and other structuring
techniques. See Section 3.5.4, "Using Directives," for further
information.
A simple description block
All of these elements need not be present in every description file. For
many applications, a description file consisting of a single description
block is adequate. The example below shows a description file with only one
description block:
program.exe : program.obj sub1.obj #update program
QCL program.obj sub1.obj
The first line of the description block is called the "dependency line." It
identifies the "target" to be updated (PROGRAM.EXE) and the "dependents"
that make up the target (PROGRAM.OBJ, SUB1.OBJ). If any of the dependents
has changed since the target was last modified, NMAKE rebuilds the target.
When NMAKE executes this description, it checks the date on which each of
the object files was last modified. If either has been modified since the
executable program was created, NMAKE executes the second line, which is
called the "command line." The QCL command in the above example relinks the
program.
What about the C source files?
Note that the target is an executable file (.EXE) and its dependents are
object files (.OBJ). You might wonder why the C source files PROGRAM.C and
SUB1.C do not appear in the description block. The reason is that NMAKE
assumes that .OBJ files depend on C source files and knows that it must
compile PROGRAM.C and SUB1.C to create PROGRAM.OBJ and SUB1.OBJ. How and why
NMAKE works this way are advanced topics covered in Section 3.5.3, "Using
Inference Rules." You don't need to understand inference rules to create
description files and use NMAKE.
Of course, if you prefer, you can make your target-executable files depend
on the C source files and use the QCL command to compile and link the
sources. It is usually preferable, however, to list the object files as
dependents.
The next section in this chapter, "Building a Simple Description File,"
shows how to construct description files, such as the one above, that
consist of a single block.
3.2 Building a Simple Description File
Before you invoke NMAKE, you need to create a description file. Since a
description file is simply a text file, you can use any text editor
(including the one in the QuickC environment) to create one. NMAKE places no
restrictions on the name of the description file, but always looks for a
file named MAKEFILE in the current directory unless you tell it otherwise.
See Section 3.3, "Invoking NMAKE," for more information on how NMAKE
identifies the description file.
Depending on the size of the project you are maintaining, your description
file may contain one or more description blocks. This section describes the
components of a description block and shows you how to build description
files that consist only of description blocks.
3.2.1 Description Blocks
Description blocks are the basic elements of description files. A
description block tells NMAKE how to update a target from a group of
dependents. Every description block consists of a dependency line, any
number of command lines, and optional comments. Figure 3.1 shows the
components of a description block.
(This figure may be found in the printed book.)
3.2.1.1 Dependency Lines
A dependency line typically lists one target and one or more of its
dependents. A colon (:) separates the target from the dependents.
Targets
The name of the target goes at the beginning of the line, with no tabs or
spaces preceding it. NMAKE creates the target in the current directory
unless you include a drive and path specification in its name. A dependency
line may contain more than one target, but at least one space must separate
each pair of names. Below are some example target names:
test1.exe :
c:\cprogs\test1.exe :
test1.exe test2.exe :
The first example specifies the target TEST1.EXE in the current directory.
In the second, the target is built in the directory C:\CPROGS. The last
example lists two targets to be built from the same set of dependents.
Pseudotargets
All the targets shown above are executable files. A target, however, need
not be an executable file; in fact, it need not be a file at all. NMAKE
allows you to specify the following:
UPDATE :
In this case, UPDATE is considered a "pseudotarget" because it is not a file
but simply a label for a set of dependents and commands. Pseudotargets are
useful for updating directories and copying groups of files. NMAKE always
considers pseudotargets out-of-date.
Specifying dependents
List the names of the dependent files on the same line as the target but
after the colon. Separate the dependent names by one or more spaces. A
target can have any number of dependents. If the names of all the dependents
do not fit on one line, use a backslash ( \ ) to end the line and continue
the list on the next line. This is NMAKE's standard method of line
continuation.
Dependent names, like target names, can contain drive and path
specifications. If you do not include a drive or path specification, NMAKE
looks for the dependents in the current directory. For example:
mycprog.exe : mycprog.obj \public\src\graphics.obj
UPDATE : *.c \inc\*.h
The first example shows two dependents for MYCPROG.EXE. One of them is
MYCPROG.OBJ, for which NMAKE searches the current directory. The other is
GRAPHICS.OBJ, for which NMAKE searches the \PUBLIC\SRC directory. The second
example shows that the pseudotarget UPDATE depends on all the .C files in
the current directory and all the header files in the /INC directory.
Search paths for dependents
You can direct NMAKE to search for dependents in a sequence of other
directories by adding a search path enclosed in braces. NMAKE searches the
directories specified by the path if it cannot find the file in the current
directory. Separate each pair of directories in the path with a semicolon.
The backslash at the end of the path is optional. Consider the following:
program.exe : program.obj {\me\cwork; q:\src\}tables.obj
This line lists two dependents for PROGRAM.EXE. The first, PROGRAM.OBJ, is
assumed to be in the current directory. For TABLES.OBJ, a search path is
specified. The search path causes NMAKE to look first in the current
directory, then in \ME\CWORK, and then in Q:\SRC until it finds the file. If
it cannot find the file, all is not lost; it relies on its inference rules
to build the file. (See Section 3.5.3 in this chapter for more information
on inference rules. For a more detailed description, see Section 7.2.4,
"Inference Rules.")
3.2.1.2 Command Lines
The command lines in a description block give the commands to be carried out
if a target is out-of-date with respect to any of its dependents. Commands
can be the names of programs, batch files, or any DOS commands─in short, any
command that can be issued on the DOS command line.
Rules for specifying commands
In the typical format of a description file, the commands are on separate
lines from the target and its dependents, one command per line. Each line
must start with one or more spaces or tab characters. If you forget the
space or tab, NMAKE assumes you are specifying a dependency line (or a
macro) and displays an error message. You may find it helpful to use a tab
to indent the line, making it easy to identify the commands that apply to
each target. (This book uses that convention.) For example:
program.exe : program.obj sub.obj
qcl program.obj sub.obj
The command line in the example above invokes QCL to link the two dependent
files into a single executable image.
If you prefer, however, you can put your commands on the same line as the
target and dependents. In that case, a semicolon must precede each command
to separate it from the previous item on the line, whether that item is a
dependent or another command. The following has the same effect as the
previous example:
program.exe : program.obj sub.obj ; qcl program.obj sub.obj
If a command is too long to fit on one line, you can split it across two or
more lines with a backslash ( \ ), in the same way that you split a long
dependency list. For example:
program.exe : program.obj sub1.obj sub2.obj sub3.obj
qcl program.obj sub1.obj sub2.obj \
sub3.obj
Be sure that every line that is part of a command begins with a space or
tab.
3.2.1.3 Comments
You can put comments in your description files by using the number sign (#).
NMAKE ignores all the text between the number sign and the beginning of the
next line. Comments may appear anywhere in an NMAKE description file except
on a command line. You can place comment lines between the command lines,
but the number sign that starts the comment must be the first character on
the line with no spaces or tabs preceding it. The following example shows
the use of comments:
#makefile for program.exe
program.exe : program.obj sub1.obj sub2.obj
qcl program.obj sub1.obj sub2.obj
# program
The first comment documents the purpose of the file. The second causes NMAKE
to treat the word program as a comment. When NMAKE executes this
description, it will rebuild PROGRAM.EXE but will not run it.
3.2.1.4 Escape Characters
Some characters, such as the number sign (#), have a special meaning when
they appear in an NMAKE description file. If you want NMAKE to interpret a
character literally, and not with its special NMAKE meanings, you must
precede the character with the caret (^). The caret is an "escape
character," which means that when it immediately precedes a special
character, it causes the character to lose its special meaning.
For example, the number sign (#) denotes the start of a comment. To use it
in a file name, you must precede it with a caret to "escape" its special
meaning, as follows:
winning^#.txt
NMAKE interprets the example as the file name winning#.txt .
The following characters have special significance to NMAKE, so you must
precede them with a caret whenever you want NMAKE to interpret them
literally:
# ( ) $ ^ \ { } ! @
NMAKE ignores a caret that precedes any other character. In addition, carets
that appear within quotation marks are not treated as escape characters.
Examples
Assume you are developing a program named HANDLE. Your directories are
organized so that all your source files and object files are stored under
the current directory and your include files are in the \INC directory.
Consider the following description file:
handle.exe : main.obj comm.obj \inc\comm.h
QCL /Fehandle.exe main.obj comm.obj
handle
The dependency line say that HANDLE.EXE should be updated if any of three
files change. Two of these files (MAIN.OBJ and COMM.OBJ) are object files;
the third (COMM.H) is an include file. If NMAKE determines that it must
create a new version of the target, it executes the QCL command. The QCL /Fe
option specifies the name HANDLE.EXE for the executable program. NMAKE
executes the new version of HANDLE.EXE after creating it.
If the current directory contains only the files for HANDLE.EXE, and none
for any other programs, the description file could be rewritten as follows:
handle.exe : *.obj \inc\comm.h
QCL /Fehandle.exe *.obj
handle
NMAKE expands the wild cards in the dependent names when it starts to build
the target.
3.2.2 The CC Macro
The sample description files presented so far have contained only
description blocks─no macros, directives, or inference rules. For the most
part, you can get by without any of these features.
Before you use NMAKE with QuickC, however, you need to know about one
particular macro, CC. The predefined macro CC tells NMAKE which C compiler
to use when it tries to create .OBJ files from .C files. Recall that NMAKE
knows that .OBJ files depend on .C files, which is why only .OBJ files
appear in the examples up to this point. NMAKE implicitly compiles .C files
into .OBJ files, using the compiler specified by the CC macro.
As you may be aware, NMAKE is provided with both Microsoft C Professional
Development System and QuickC. For that reason, CC is predefined to invoke
the C compiler included with the Professional Development System, CL. You
must redefine CC to invoke QCL, the QuickC compiler.
To redefine the CC macro, add this line at the top of your description file:
CC = qcl
No spaces or tabs can precede CC; it must be the first item on the line. The
spaces around the equal sign are optional.
Continuing with the example in Section 3.2.1.4, the description file would
look like the following:
CC = qcl
handle.exe : *.obj \inc\comm.h
QCL /Fehandle.exe *.obj
handle
This description block has the same effect as the earlier ones, except that
if any .OBJ files in the current directory must be updated from .C files, it
ensures that NMAKE will use the QuickC compiler to do it. The QCL command in
the example is independent of the CC macro; the command line explicitly
invokes QuickC to link the object files into an executable file.
Redefining CC in the TOOLS.INI file
As an alternative, you can redefine CC in TOOLS.INI, the
tools-initialization file. The TOOLS.INI file contains environment variables
and initial (default) settings for various utility programs. You may already
have a TOOLS.INI file; if not, you can create one with any text editor.
Items that apply to NMAKE appear in the file following the [nmake] tag. To
change the definition of the CC macro, add the following line after the tag:
CC=qcl
Whenever you invoke NMAKE, the utility looks for TOOLS.INI first in the
current directory and then in the directory specified by the INIT
environment variable. To see what INIT is set to, type the SET command at
DOS command level.
3.3 Invoking NMAKE
You can invoke NMAKE in either of two ways:
1. By giving the NMAKE command and all options, macros, and targets on
the DOS command line
2. By giving the NMAKE command and the name of a response file that
contains all the options, macros, and targets
This section describes both methods.
3.3.1 Invoking NMAKE from the DOS Command Line
Under most circumstances you'll probably issue the NMAKE command from the
DOS command line. The command has the following format:
(This figure may be found in the printed book.)
The items in italics are optional arguments and are described below:
■ The options modify the action of the NMAKE command. The most commonly
used NMAKE options are described in the section titled "NMAKE
Options"; the complete set is covered in Chapter 7.
■ The macrodefinitions give text to replace macro names in the
description file. Section 3.5.2, "Using Macros," introduces macros and
explains how and when to use them. See Section 7.2.3, "Macros," for
details.
■ The targets field lists one or more targets for NMAKE to build. If you
do not specify a target, NMAKE builds only the first one in the file.
You can find more information on targets in Section 3.2.1,
"Description Blocks," and in Section 7.2.1. Because all the arguments
are optional, the simplest form of the NMAKE command is just
NMAKE
The default file MAKEFILE
When you invoke NMAKE with the preceding command, it looks in the current
directory for a file named MAKEFILE to use as the description file. If no
such file exists, it displays an error message.
You can specify an alternate description file by using the /F option,
described below in Section 3.4.1, "Controlling Input."
3.3.2 Invoking NMAKE with a Response File
For more complicated updates, and whenever the NMAKE command line exceeds
the DOS limit of 128 characters, you will need to create a response file.
The response file contains the options, targets, and macros you would type
on the DOS command line. It is not the same as the NMAKE description file;
instead, it is comparable to a QLINK or LIB response file.
To invoke NMAKE with a response file, issue the following command:
NMAKE @responsefile
For responsefile, use the name of the file that contains the options,
targets, and macros you would otherwise type on the NMAKE command line.
3.4 NMAKE Options
NMAKE provides a rich set of options that control the descriptions it reads
as input, the details of its execution, and the messages it displays on
output. The following sections describe some of the most useful NMAKE
options. Section 7.3 covers all the options in detail.
Options immediately follow the NMAKE command on the DOS command line and
precede the name of the description file, if you supply one. NMAKE accepts
options in uppercase or lowercase letters, with either a slash ( / ) or a
dash (-) to introduce each option. For example, -F, /F, -f, and /f all
represent the same option. In options that take file-name arguments, for
example, /F and /X, the file name and the option must be separated by a
space.
3.4.1 Controlling Input
You can specify the description file from which NMAKE will take its input
with the /F option. This option has the following form:
/F filename
If you specify the /F option, NMAKE uses filename as the name of the
description file. The space separating /F and filename is required. In place
of a file name, you can enter a dash (-) to tell NMAKE to read the
description from standard input, typically your keyboard.
If you omit the /F option, NMAKE looks for a file named MAKEFILE in the
current directory. If no such file exists, it displays an error message.
────────────────────────────────────────────────────────────────────────────
NOTE
Unless you use the /F option, NMAKE always searches for the file MAKEFILE in
the current directory. Therefore, you should explicitly specify /F to avoid
unintentionally using MAKEFILE.
────────────────────────────────────────────────────────────────────────────
The following is an example of the /F option:
NMAKE /F hello.mak
This command invokes the NMAKE utility and specifies HELLO.MAK, in the
current directory, as the description file.
3.4.2 Controlling Execution
The following options change the way NMAKE interprets the description file:
Option Effect
────────────────────────────────────────────────────────────────────────────
/A Builds all of the targets requested,
even if they are not out-of-date.
/I Ignores exit codes returned by commands
executed within a description file.
NMAKE continues processing the
description file despite the errors.
/N Displays the commands from the
description file but does not execute
them. Use this option to determine which
targets are out-of-date without
rebuilding them. You can also use it in
debugging description files.
/T "Touches" any target files that are
outdated. Touching a file causes its
date of modification to be changed to
the current date. It has no effect on
the contents of the file.
3.4.3 Controlling Output
As NMAKE runs, it displays each command that it executes. It displays a
diagnostic message if it cannot find a file or command needed to complete a
description block or if any command returns an error. You can change the
type and number of messages that NMAKE returns by using the options below:
Option Effect
────────────────────────────────────────────────────────────────────────────
/C Suppresses the Microsoft copyright
message and all nonfatal or warning
messages.
/D Displays the modification date of each
target or dependent file when it checks
the date.
/P Prints all macro definitions and target
descriptions.
/S Executes "silently"; does not display
commands as they are executed.
/X filename Sends all error output to filename. A
space must separate /X from filename.
Specifying a dash (-) instead of a file
name sends error output to the standard
output device.
Examples
The following command invokes NMAKE with PHYSICS.MAK as the description
file:
NMAKE /F physics.mak /N
The /N option tells NMAKE to read, but not to execute, any of the commands
within the file PHYSICS.MAK. NMAKE checks the modification dates on the
files and displays the commands it would execute if the /N option were not
present. Use this option to find out ahead of time what files are
out-of-date so you can estimate how long a build might take. You can also
use it in debugging description files.
After using the /N option to check what NMAKE would do, you might invoke it
with the command line below:
NMAKE /F physics.mak /C /S
The /C option suppresses the NMAKE copyright message and any warning
messages. The /S option suppresses the display of commands. You will,
however, still see the copyright messages for any commands that NMAKE
invokes and the output those commands generate.
3.5 Building Complex Description Files
Most software projects can be maintained using the features already
described. However, description files for large projects may become
complicated and cumbersome, especially if each module is dependent on many
source and include files. Using NMAKE's advanced features, you can shorten
your description files and make them more powerful at the same time.
This section covers several of NMAKE's advanced features:
■ Special characters on command lines
■ Macros
■ Inference rules
■ Directives
Figure shows a more complicated description file than those presented so
far.
(This figure may be found in the printed book.)
3.5.1 Using Special Characters to Modify Commands
NMAKE recognizes three special characters that modify its treatment of
commands. These characters give you additional control over the execution of
individual commands, whereas NMAKE's options apply to all the commands in
the description file.
The characters go before the command name and can be separated from the name
by one or more spaces, though they need not be. At least one space or tab
must precede the character on the line. To use two or three special
characters with a single command, put them one after the other on the
command line. The special characters are as follows:
Character Action
────────────────────────────────────────────────────────────────────────────
Dash (-) Turns off error checking for the command
it precedes so that NMAKE continues
executing if an error occurs. A dash
followed by a number suspends error
checking for error levels at the number
and below.
At sign (@) Suppresses display of the command when
it is
executed.
Exclamation point (!) Causes the command to be executed
iteratively, once for each dependent
file, if it uses one of the macros for
dependent names. (The macros are
described in the Section 3.5.2.)
Note that the dash (-) has the same effect as the /I option. Also, the "at"
sign (@) is similar to the /S option.
Examples
beatles.exe : john.asm paul.c george.c ringo.c
-QCL /c paul.c george.c ringo.c
MASM john
QLINK john paul george ringo, beatles.exe;
In the example above, the dash preceding the QCL command means that NMAKE
will attempt to execute the MASM and QLINK commands even if errors occur
during compilation.
beatles.exe : john.asm paul.c george.c ringo.c
-@QCL /c paul.c george.c ringo.c
MASM john
@QLINK john paul george ringo, beatles.exe;
The description in this example has the same effect as that in the previous
example, except that neither the QCL nor the QLINK command is displayed when
it is executed.
3.5.2 Using Macros
You can use macros to streamline your description files. A "macro" is a name
that replaces other text in the description file in the same way that a
macro defined in a QuickC #define directive replaces other text in a
program. Wherever the name appears in the description file, NMAKE
substitutes the text associated with it. To change the meaning of the name,
you simply change the text assigned to it in the macro definition.
Macros are most useful in two situations:
1. To replace all or part of a file name so that a single NMAKE
description file can be used to update more than one program.
2. To supply options for commands within the NMAKE description file. For
example, you might define a macro to represent your usual debug
options for the QCL command. Then, to compile with a different set of
options, you need not edit the description file. You merely change the
macro definition.
NMAKE provides two types of macros: predefined macros and macros you define.
This section shows how to use them.
3.5.2.1 Defining Your Own Macros
A "macro definition" tells NMAKE what text to substitute for a macro. You
can put macro definitions in the description file, on the NMAKE command
line, or in your TOOLS.INI file. In the description file, each macro
definition must be on a separate line. On the command line, macro
definitions follow any NMAKE options and precede any targets. In the
TOOLS.INI file, macro definitions appear in a section following the [nmake]
tag, each on a separate line, as described previously in Section 3.2.2, "The
CC Macro."
No matter where you put them, macro definitions take the following form:
macroname = string
The macroname is the name you use in the description file. A macro name can
consist of any alphanumeric characters and the underscore ( _ ) character.
The string is the text that replaces the macro name when the description
file is processed.
Macros on the command line
On the NMAKE command line, white space cannot appear on either side of the
equal sign because it causes DOS to treat the macro name and its definition
as separate tokens. In addition, if string contains any embedded white
space, you must enclose it in double quotation marks, as follows:
my_macro="this string"
Alternatively, you can enclose the entire macro definition─macroname and
string─in double quotation marks. In that case, spaces can surround the
equal sign because DOS treats all the characters within quotation marks as a
single token. Thus, the following is also acceptable:
"my_macro = this string"
Macros in the description file
In a description file, define each macro on a new line. The definition must
start at the beginning of the line with no preceding white space. NMAKE
ignores any white space surrounding the equal sign. Quotation marks are
unnecessary as well; if you use them, they will become part of the string.
This example defines a macro named pname and another named t:
pname = mycprog.exe
t = this
To use a macro within a command or dependency line, specify its name in
parentheses preceded by a dollar sign ($), as follows:
$(macroname)
If you need to use a literal dollar sign in a description file, type it
twice ($$) or use the caret (^) escape character.
The lines below show how to refer to the macros defined in the previous
example. Note that if the name of a macro is only one character long, you
can omit the parentheses.
$(pname)
$t
Once you've defined a macro, the only way to remove its definition is to use
the !UNDEF directive. See Section 3.5.4, "Using Directives," for more
information.
Examples
A common use of macros is to specify the options for a command. For example,
the following description block uses the macro copts to represent QCL
options.
picture.exe : picture.c graphics.c fileio.c
qcl $(copts) picture.c graphics.c fileio.c
Assuming the description file is named PICTURE.MAK, the command line might
be the following:
NMAKE /F picture.mak copts="/C /P"
At execution time, NMAKE substitutes /C /P wherever $(copts) appears in
the description file. The result is the same as if the following description
were used:
picture.exe : picture.c graphics.c fileio.c
qcl /C /P picture.c graphics.c fileio.c
Note that the /P option causes QuickC to create a preprocessor listing, and
the /C option retains the comments from the source files in the preprocessor
listing.
3.5.2.2 Predefined Macros
Some macros are predefined by NMAKE. You have already seen one of these, CC.
Some of the other predefined macros are described below. For a complete
list, see Section 7.2.3.3.
Macros for Program Names (CC, AS, MAKE) - The CC macro, already
introduced, represents the C compiler command that NMAKE executes to create
object files from C source files. The AS macro is similar. It stands for the
name of the assembler that NMAKE executes when it needs to create object
files from .ASM sources. Both of these macros are predefined by NMAKE. You
can change their definitions in the description file, in the TOOLS.INI file,
or on the NMAKE command line. Their default definitions are
CC = cl
AS = masm
These two macros are primarily used in inference rules. (See Section 3.5.3,
"Using Inference Rules," or Section 7.2.4, "Inference Rules," for more
information.)
The MAKE macro is defined as the command you use to invoke NMAKE. Use this
macro, rather than the NMAKE command itself, to invoke NMAKE recursively
within a description file. Recursion is typically used in building large
software projects, such as compilers, and frequently involves the use of
conditional directives. (An example of the recursive use of NMAKE appears
later in this chapter in Section 3.5.4.2, "Conditional Directives.")
Macros for Target Names ($@, $*) - The $@ macro represents the full name of
the target, and the $* macro represents the base name of the target, which
is the full name with the extension deleted. These two macros are typically
used in inference rules, but for the sake of discussion, this section will
show their use in description files.
Consider the following description block:
$(target) : picture.obj graphics.obj fileio.obj
QLINK picture.obj graphics.obj fileio.obj, $@;
$*
Assume NMAKE is invoked with the following command:
NMAKE target=trees.exe
The command line supplies text for the macro target, which sets the full
name of the target to trees.exe. At execution time, NMAKE substitutes the
text for the macro as explained in Section 3.5.2. However, this file goes
one step further. Instead of repeating the user-defined $(target) macro as
the output of the QLINK command, it uses the predefined $@ macro. This macro
stands for the full name of the target and therefore has the same meaning as
$(target). Thus, the QLINK command links the object files into trees.exe.
In the last line of the file, the $* macro stands for the base name of the
target. This line causes trees.exe to be executed as a program.
NMAKE automatically substitutes for these macros. It picks up the target
name from its position on the dependency line in the description file. You
cannot assign a value to a predefined macro on the command line.
NMAKE provides additional predefined macros that you can use to specify
target names. See Section 7.2.3.3, "Predefined Macros," for details.
Macros for Dependent Names ($**, $?) - These macros signify the names of one
or more dependents. The $** macro represents the complete list of dependent
files for the target. The $? macro represents only the dependents that are
out-of-date relative to the target. These two macros are commonly used with
the special characters that modify commands to prevent NMAKE from doing any
more work than necessary.
The example below shows the description file from the previous section using
macros for the dependent names:
$(target) : picture.obj graphics.obj fileio.obj
QLINK $**, $@;
$*
The first line of the example defines all the dependents for the target. On
the next line, the QLINK command links all the dependents, represented by
$**, into a single executable image. Finally, the target is run as a
program.
NMAKE provides additional predefined macros that you can use to specify
dependent names. See Section 7.2.3.3, "Predefined Macros," for details.
3.5.2.3 Precedence of Macro Definitions
Because macros can be defined in so many places, it is quite possible to
give a macro more than one definition. Sometimes this is desirable. For
instance, you may wish to override a macro definition for a single execution
of the description file.
NMAKE's precedence rules determine which macro definition it uses.
Precedence depends on where the macro is defined. Listed below is the order
of precedence from highest to lowest priority:
1. Macros defined on the NMAKE command line.
2. Macros defined in the description file and in files included in the
description file with the !INCLUDE directive (see Section 3.5.4,
"Using Directives").
3. Macros inherited from environment variables.
4. Macros defined in the TOOLS.INI file.
5. Macros defined by NMAKE, such as CC and AS.
Figure shows how macros defined on the command line take priority over
those in the description file.
In addition, you can force environment variables to override assignments in
the description file, using the /E option.
3.5.3 Using Inference Rules
Most of the description blocks shown so far in this chapter contain commands
to update the target from its dependents. Under certain conditions, however,
NMAKE will follow a set of rules, called "inference rules," to create the
target. Like macros, several inference rules are predefined, and NMAKE
allows you to define your own.
(This figure may be found in the printed book.)
If you supply a description block that does not contain any commands, or if
the dependents of your target do not exist, NMAKE relies on inference rules.
Whether predefined or user defined, inference rules are based on the
file-name extensions of the target and dependent files. In short, they tell
NMAKE how to create a file with a particular extension from a file with the
same base name and a different extension.
Below is a simple inference rule:
.c.exe :
QCL $*.c
This rule defines how to make a file with the .EXE extension from a file
with the same base name and the .C extension. The first line says that the
rule tells how to go from a file with the .C extension to a file with the
.EXE extension. The second line gives the command that creates the .EXE
file─in this case, the QCL command. The $* macro represents the base name of
the target with the extension deleted.
An inference rule looks very similar to a description block, with two
exceptions:
1. An inference rule lists two file-name extensions instead of target
names.
2. Inference rules do not list dependents.
If the inference rule shown in the example above were in effect, NMAKE would
use it for the following description block:
zfile.exe : zfile.c
NMAKE applies the inference rule for three reasons:
1. The description block does not contain any commands.
2. The file-name extensions of the target file and its dependent match
those in the rule.
3. The base name of the target and dependent are the same.
The combination of the inference rule and the description block above has
the same effect as the following description block:
zfile.exe : zfile.c
QCL zfile.c
3.5.3.1 Predefined Inference Rules
NMAKE has three predefined inference rules. The predefined rules make use of
the default macros CC and AS, along with several of the predefined macros
that have already been presented.
From .C to .OBJ
One predefined rule builds .OBJ files from .C files:
.c.obj:
$(CC) $(CFLAGS) /c $*.c
When NMAKE applies this rule, it substitutes the current values of the
macros CC and CFLAGS for $(CC) and $(CFLAGS). (The CFLAGS macro lists
options for the C compiler.) It then looks for a C source file with the same
name as the target and compiles the source file without linking. This is the
rule NMAKE uses for the examples in this chapter that list .OBJ files─not C
source files─as dependents.
With the description block below, NMAKE would use this inference rule if it
needed to create or update one or more of the .OBJ files listed in the
dependency list:
menu.exe : menu.obj funcs.obj draw.obj
QLINK menu funcs draw;
If the current directory contains .C source files with the same base names
as the .OBJ files in the example, NMAKE compiles them according to the
inference rule.
From .C to .EXE
Another predefined rule, shown below, builds .EXE files from .C files:
.c.exe:
$(CC) $(CFLAGS) $*.c
This rule causes NMAKE to use the same files as the previous rule but to
link the output into an executable image. Continuing with the example, NMAKE
would use this rule if the description file contained the following:
menu.exe : menu.c
Note that the files FUNCS.C and DRAW.C are not shown here. NMAKE would not
create .EXE files for them because their base names are different from that
of the .EXE file that NMAKE is trying to create.
From .ASM to .OBJ
The third predefined rule builds .OBJ files from .ASM files:
.asm.obj:
$(AS) $(AFLAGS) $*;
This rule tells NMAKE to look for an assembly-language source file with the
same name as the target file and to invoke the Macro Assembler to create an
object file. (The AFLAGS macro lists options for the assembler command.)
NMAKE would use this inference rule under the same conditions as the first
rule. For example:
menu.exe : menu.obj funcs.obj draw.obj
QLINK menu funcs draw;
If the current directory contains .ASM files with the same base names as any
of the .OBJ files, NMAKE uses this final inference rule.
3.5.3.2 Defining Inference Rules
The predefined inference rules are adequate for most situations.
Nevertheless, NMAKE allows you to define your own inference rules in the
description file or in your TOOLS.INI file . You can also define them in a
separate file that you include in your description file. (See Section
3.5.4.1 for information on the !INCLUDE directive.) Inference rules cannot
be defined on the NMAKE command line.
To define an inference rule, use a statement in the following form :
.fromext.toext: command .
The first line defines the types of files to which the rule applies. It
contains the extension of the "from" file first, and then the extension of
the "to" file. The second and subsequent lines give the commands that NMAKE
must execute to create a file with the "to" file extension from a file that
has the same base name and the "from" file extension. You can specify one or
more commands, just as in a description block.
Specifying a path for .fromext or .toext
Sometimes you may want to associate a directory with each type of file. For
instance, some programmers organize all their source files in one directory
and their object files in another. NMAKE allows you to precede each of the
extensions with a path, as follows:
{frompath}.fromext{topath}.toext
The example below shows a rule that starts with source files in one
directory and creates object files in a different directory:
{\usr\graphics\source}.c{\usr\graphics\obj}.obj
You can specify only one path for each extension. If you need to pull source
files from several different directories and place all the object files in
one directory, you must define a separate inference rule for each source
directory.
3.5.3.3 Precedence of Inference Rules
Like macros, inference rules can be defined in several places; the location
of an inference rule's definition establishes its precedence. NMAKE applies
inference rules in the following order, from highest to lowest priority:
1. Inference rules defined in the description file or in files included
in the description file by the !INCLUDE directive (described in
Section 3.5.4.1)
2. Inference rules defined in the TOOLS.INI file
3. Predefined inference rules
3.5.4 Using Directives
Directives provide additional control over the execution of commands, beyond
what you can do with macros and inference rules. Using directives, you can
■ Include the contents of another file in your description file
■ Conditionally execute a command or group of commands
■ Issue error messages from within a description file
In effect, directives let you build description files that act like DOS
batch files. Such description files are especially useful for large software
projects in which the work is divided among several people. A description
file can compile each source file, build any necessary libraries, and link
the entire program. If errors occur anywhere in the process, the description
file can issue diagnostic messages, possibly take corrective action, or
terminate execution.
Each directive begins on a new line in the description file. A directive
starts with an exclamation point (!) as the first character on the line.
NMAKE allows, but does not require, spaces between the name of the directive
and the exclamation point.
The sections that follow describe several of the NMAKE directives. For
information on all the directives, see Section 7.2.5.
3.5.4.1 The !INCLUDE Directive
The !INCLUDE directive is similar to the #include preprocessor directive in
QuickC. When NMAKE encounters !INCLUDE, it reads the contents of another
description file before continuing with the current description file. Use
the !INCLUDE directive to include a standard set of inference rules or
macros in your description files. For example:
!INCLUDE rules.mak
The !INCLUDE directive in this example tells NMAKE to begin reading from the
file RULES.MAK in the current directory and to evaluate the contents of
RULES.MAK as part of the current description file.
If you enclose the file name in angle brackets (<>), NMAKE searches for the
file in the directories specified by the INCLUDE environment variable.
3.5.4.2 Conditional Directives (!IF, !ELSE, !ENDIF)
The conditional directives allow you to specify blocks of commands to be
executed depending on the value of a constant expression. A conditional
block has the following form:
!IF expression statements !ELSE statements !ENDIF
If the value of expression is nonzero (true), NMAKE executes the statements
between the !IF directive and the !ELSE directive. If the value of the
constant expression is zero (false), NMAKE executes the statements between
the !ELSE directive and the !ENDIF directive.
Expressions
The expression may consist of integer constants, string constants, or
program invocations that return constants. Integer constants can use the C
unary operators for numerical negation (-), logical negation (!), and one's
complement arithmetic (~); or the C binary operators, including arithmetic
operators, bitwise operators, and logical operators. (See Table for a
complete list.) For string constants, only the equality (==) and inequality
(!=) operators are valid. You can use parentheses to group expressions
wherever necessary. Program invocations, when used in conditionals, must be
enclosed in square brackets.
Recursion
Conditional directives are commonly used to test whether a program executed
successfully. The program can be a DOS command, a program you have written,
or even NMAKE itself. In the following description block, note the use of
the $(MAKE) macro to invoke the program recursively:
$(target) : picture.obj fileio.obj error.obj
# Try to build pix.lib
!IF ![$(MAKE) /f pix.mak]
QLINK $**,$(target),,pix.lib;
COPY pix.lib \mylibs
!ELSE
#Build didn't work, so link with old version
QLINK $**,$(target),,\mylibs\pix.lib;
!ENDIF
In this case, the expression is the value returned by another invocation of
NMAKE. NMAKE, like many programs, returns the value 0 if it executes
successfully and a nonzero errorlevel code otherwise. This is the opposite
of the usual conditional test, which considers zero to be true and nonzero
to be false. Therefore, the !IF directive must test the logical negation of
the expression; that is, it uses the exclamation-point operator outside the
square brackets.
If the library pix.lib is built successfully, NMAKE executes the QLINK and
COPY commands on the two lines immediately following the !IF directive.
If the library cannot be built successfully, NMAKE executes the command
following the !ELSE directive. This command links all the dependents (named
by the special $** macro) with an old version of the library.
3.5.4.3 Testing for Macro Definitions (!IFDEF, !IFNDEF, !UNDEF)
The !IFDEF and !IFNDEF directives test whether a macro is defined and
execute a block of statements depending on the result. You use these two
directives with the !ELSE and !ENDIF directives to construct conditional
blocks, as described in the previous section.
The description block below shows the use of !IFDEF and !IFNDEF directives:
$(target) : picture.obj fileio.obj error.obj
# Macro $(newlib) is defined to use new pix.lib
!IFDEF newlib
QLINK $**,$(target),,pix.lib;
!ELSE
# Just link with existing version
QLINK $**,$(target),,\mylibs\pix.lib;
!ENDIF
When NMAKE encounters the !IFDEF directive, it checks whether or not newlib
has been defined. If so, it executes the QLINK command on the next line. If
not, it executes the QLINK command following the !ELSE directive.
NMAKE considers a macro to be defined if its name appears to the left of an
equal sign anywhere in the description file or on the NMAKE command line.
So, if the MAKEFILE file contains the above description, both of the
commands below would result in execution of the statements following the
!IFDEF directive:
NMAKE newlib=true target=eliot.exe
NMAKE newlib= target=eliot.exe
Even though the second command line sets newlib to the null string,
newlib is still considered defined because its name appears to the left of
the equal sign.
The !IFNDEF directive acts in exactly the same way as !IFDEF, except that
the statements following it are executed only if the macro is not defined.
Once you have defined a macro, the only way to remove its definition is to
use the !UNDEF directive. You might want to remove a macro definition before
including another file, as in the following example:
!UNDEF opts
!INCLUDE newlib.mak
The !UNDEF directive ensures that the macro opts is not defined when the
file NEWLIB.MAK is processed.
3.5.4.4 The !ERROR Directive
The !ERROR directive causes NMAKE to print some text, then quit processing
the description file. This directive is commonly used in conditionals to
terminate execution when fatal errors occur. For example, when NMAKE comes
across the conditional
!IF "$(continue)" == "n"
!ERROR Could not continue because of errors.
!ELSE
QLINK $**, $@;
!ENDIF
it tests the value of the continue macro. If continue holds the string
"n", NMAKE displays the text that follows the !ERROR directive then stops
execution. If continue holds any other value, NMAKE executes the QLINK
command that follows the !ELSE directive.
3.6 Other NMAKE Features
This chapter has covered a subset of NMAKE designed to get you started. In
addition to having the features described in this chapter, the NMAKE utility
lets you
■ Specify additional command-line options
■ Specify more than one set of dependents for a target
■ Create description files that build more than one target, and specify
the target to build at invocation
■ Use additional predefined macros
■ Substitute text within macros
■ Use additional directives
■ Generate response files for use with other programs
■ Use predefined pseudotargets, which provide special rules and
information
As you become more familiar with NMAKE, and as your software projects grow,
you will probably need to use some of these features. See Chapter 7 for more
information.
PART II Reference to QuickC Tools
────────────────────────────────────────────────────────────────────────────
Part 2 of the QuickC Tool Kit is a reference to the tools. Here you will
find complete information on all the options of the utilities. Refer to Part
2 when you have a specific question about one of the tools or when you've
gained experience with the utilities and need to know more about them.
The QCL, LINK, LIB, and NMAKE utilities are covered in greater detail in
Part 2 than in Part 1. In particular, these chapters describe additional
options that work with programs written in other languages (such as Pascal,
FORTRAN, and assembler) or with special hardware.
Chapter 4 QCL Command Reference
────────────────────────────────────────────────────────────────────────────
This chapter describes in detail the QCL command, which you can use to
compile and link QuickC Compiler programs. It explains the rules for giving
input on the QCL command line, describes the options to QCL in alphabetical
order, and shows how to change the stack space allocated to a program.
The chapter provides reference material for programmers who are familiar
with the Microsoft QuickC Compiler in general and the QCL command in
particular. If you are new to the QuickC Compiler, see Chapter 1, "Creating
Executable Programs," in Part 1 of this manual for an introductory approach.
4.1 The QCL Command Line
The QCL command line has the following format:
QCL «option...» file... «option|file»... «/link «lib... link-opt...» »
The following list describes input to the QCL command:
Entry Meaning
────────────────────────────────────────────────────────────────────────────
option One or more QCL options; see Section 4.3,
"QCL Options," for descriptions.
file The name of one or more source files,
object files, or libraries. You must
specify at least one file name. QCL
compiles source files and passes the
names of the object files and libraries
to the linker.
lib One or more library names. QCL passes
the names of these libraries to the
linker for processing.
link-opt One or more of the linker options
described in
Chapter 5, "QLINK." The QCL command
passes
these options to the linker for
processing.
Maximum command-line length
You can specify any number of options, file names, and library names, as
long as the length of the command line does not exceed 128 characters.
Specifying file names
Any combination of uppercase and lowercase letters is legal in file names.
Any file name can include a full or partial path name. A full path name
includes a drive name and one or more directory names. A partial path name
omits the drive name, which QCL assumes to be the current drive. If you
don't specify any path name, QCL assumes the file is in the current
directory.
QCL determines how to process each file depending on its file-name
extension, as follows:
Extension Processing
────────────────────────────────────────────────────────────────────────────
.C QCL assumes the file is a C source file
and compiles it.
.OBJ QCL assumes the file is an object file
and passes its name to the linker.
.LIB QCL assumes the file is a library and
passes its name to the linker. The
linker links this library with the
object files QCL created from source
files and the object files given on the
command line.
Any other extension QCL assumes the file is an object file
or no extension and passes its name to the linker.
4.2 How the QCL Command Works
The QCL command follows the procedure described below to create an
executable file from one or more C source files:
1. QCL compiles each source file, creating an object file for each. In
each object file, QCL places the name of the appropriate standard
combined library. The memory model and floating-point-math package
used to compile the program determine this library name. See Section
4.3.1, "/A Options," for more information on the library names.
2. QCL invokes the linker, passing the names of the object files it has
created plus any object files or libraries given on the command line.
QCL also specifies the options listed in the LINK environment
variable. If you use /link to specify linker options on the QCL
command line, these options apply as well. If conflicts occur, options
that follow /link override those in the LINK environment variable.
3. The linker links the object files and libraries named by QCL to create
a single executable file.
Before it creates the executable file, the linker resolves "external
references" in the object files. An external reference is a function
call in one object file that refers to a function defined in another
object file or in a library. To resolve an external reference, the
linker searches for the called function in the following locations in
the order shown:
a. The object files passed by QCL
b. The libraries given on the QCL command line, if any
c. The libraries named in the object files
Example
Assume that you are compiling three C source files: MAIN.C, MOD1.C, and
MOD2.C. Each file includes a call to a function defined in a different file:
■ MAIN.C calls the function named mod1() in MOD1.C and the function
named mod2() in MOD2.C.
■ MOD1.C calls the standard-library functions printf and scanf.
■ MOD2.C calls graphics functions named myline() and mycircle(),
which are defined in a library named MYGRAPH.LIB.
First, compile with a command line of the following form:
QCL MAIN.C MOD1.C MOD2.C /link MYGRAPH.LIB
QCL first compiles the C source files and creates the object files MAIN.OBJ,
MOD1.OBJ, and MOD2.OBJ. QCL then places the name of the standard library
SLIBCE.LIB in each object file.
Next, QCL passes the names of the C source files to the linker. Finally, the
linker resolves the external references as follows:
1. In MAIN.OBJ, the reference to the mod1() function is resolved using
the definition in MOD1.OBJ and the reference to the mod2() function
is resolved using the definition in MOD2.OBJ.
2. In MOD1.OBJ, the references to printf and scanf are resolved using the
definitions in SLIBCE.LIB. The linker uses this library because it
finds the library name within MOD1.OBJ.
3. In MOD2.OBJ, the references to myline and mycircle are resolved using
the definitions in MYGRAPH.LIB.
4.3 QCL Options
Options to the QCL command consist of either a forward slash ( / ) or a dash
(-) followed by one or more letters. Certain QCL options take arguments; in
some of these options, a space is required between the option and the
argument, and in others, no space is allowed. The spacing rules for the
options are given in their descriptions.
────────────────────────────────────────────────────────────────────────────
Important
QCL options (except for the /HELP option) are case-sensitive. For example,
/C and /c are two different options.
────────────────────────────────────────────────────────────────────────────
Command-line order
Options can appear anywhere on the QCL command line. With a few exceptions
(/c, /Fe), each QCL option applies to the files that follow it on the
command line and does not affect files preceding it on the command line.
You can also define QCL options in the CL environment variable; these
options are used every time you invoke QCL. (See Section 4.3.41, "Giving
Options with the CL Environment Variable.")
The remainder of this section describes all the QCL options in alphabetical
order. If an option can take one or more arguments, its format is shown
under an "Option" heading before its description. See Chapter 1, "Creating
Executable Programs," for descriptions of the various categories of QCL
options and the more commonly used options belonging to each category.
4.3.1 /A Options (Memory Models)
Every program's code and data are stored in blocks called "segments." The
memory model of the program determines the organization of these segments.
(See Section 4.3.26 and Appendix B for more information on segments.) The
memory model also determines what kind of executable file is generated. All
models produce a .EXE file, except for the tiny model which produces a .COM
file. QCL offers the memory-model options described in Table 4.1.
Table 4.1 Memory Models
╓┌───────────┌─────────────┌──────────────┌──────────────┌───────────────────╖
QCL Memory Data Code Long
Option Model Segments Segments Form
────────────────────────────────────────────────────────────────────────────
/AT Tiny One segment One segment none
for both data for both data
and code and code
/AS Small One One /Asnd
/AM Medium One One code /Alnd
segment per
module
QCL Memory Data Code Long
Option Model Segments Segments Form
────────────────────────────────────────────────────────────────────────────
module
/AC Compact Multiple data One /Asfd
segments;
data items
must be
smaller than
64K
/AL Large Multiple data One code /Alfd
segments; segment per
data items module
must be
smaller than
64K
/AH Huge Multiple data One code /Alhd
segments; segment per
QCL Memory Data Code Long
Option Model Segments Segments Form
────────────────────────────────────────────────────────────────────────────
segments; segment per
data items module
can be larger
than 64K
────────────────────────────────────────────────────────────────────────────
Default memory model
By default, the QuickC compiler uses the small memory model.
Uses of memory models
Generally, memory models with multiple code segments can accommodate larger
programs than can memory models with one code segment. Also, memory models
with multiple data segments can accommodate more data-intensive programs
than can memory models with one data segment. Programs with multiple code or
data segments, however, are usually slower than programs with a single code
or data segment. It is often more efficient to compile with the smallest
possible memory model and use the near, far, and huge keywords to override
the default addressing conventions for any data items or functions that
can't be accommodated in that model. (Consult Appendix B for more
information about these keywords and their interactions with standard memory
models.)
Customized memory models
QCL also supports customized memory models, in which different features from
standard memory models are combined. You specify a customized memory model
with the /Astring option, where string is composed of three letters that
specify the code pointer size, the data pointer size, and the stack and data
segment setup, respectively. All three letters must be present, but they can
appear in any order. The allowable letters appear in Table 4.2.
Table 4.2 Customized Memory Model Codes
╓┌───────────────┌─────────┌─────────────────────────────────────────────────╖
Group Code Description
────────────────────────────────────────────────────────────────────────────
Code pointers s Small
l Large
Data pointers n Near
f Far
h Huge
Segment setup d SS == DS
u SS != DS; DS loaded for each function entry
w SS != DS; DS not loaded at function entry
────────────────────────────────────────────────────────────────────────────
As examples, the customized representations of the standard memory models
appear in the last column of Table 4.1.
The segment setup codes can also be given as separate options, when used to
modify a standard memory model. For example, the options /AS /Au specify the
small model, plus they force DS to be loaded at function entry.
Memory models and default libraries
The memory-model and math options used to compile the program determine the
library that the linker searches to resolve external references. The library
name is mLIBCf.LIB, where the memory-model option determines m: S for small
(default) or tiny model, M for medium model, C for compact model, or L for
large or huge model. The math option (see Section 4.3.12, "/FP Options")
determines f: E for emulator (default) or 7 for 8087/80287 option.
4.3.2 /batch (Compile in Batch Mode)
The /batch option assumes that QCL is being executed from a batch file.
Normally, if QCL cannot find one of the programs needed to complete the
compilation, it displays a prompt requesting that the appropriate disk be
inserted. If you specify the /batch option, QCL simply terminates
compilation with an error.
4.3.3 /c (Compile without Linking)
The /c option tells the QCL command to compile all C source files given on
the command line, creating object files, but not to link the object files.
QCL does not produce an executable file. Regardless of its position on the
command line, this option applies to all source files on the command line.
Example
QCL FIRST.C SECOND.C /c THIRD.OBJ
This example compiles FIRST.C, creating the object file FIRST.OBJ, and
SECOND.C, creating the object file SECOND.OBJ. No processing is performed
with THIRD.OBJ because QCL skips the linking step.
4.3.4 /C (Preserve Comments during Preprocessing)
The /C (for "comment") option preserves comments during preprocessing. If
you don't specify this option, the preprocessor strips comments from a
source file since they do not serve any purpose in later stages of
compiling.
This option is valid only if the /E, /P, or /EP option is also used.
Example
QCL /P /C SAMPLE.C
This example produces a listing named SAMPLE.I. The listing file contains
the original source file, including comments, with all preprocessor
directives expanded or replaced.
4.3.5 /D (Define Constants and Macros)
Option
/D identifier «=«{string|number}»»
Use the /D option to define constants or macros for your source file.
The identifier is the name of the constant or macro. It may be defined as a
string or as a number. The string must be enclosed in quotes if it includes
spaces.
If you leave out both the equal sign and the string or number, the
identifier is assumed to be defined, and its value is set to 1. For example,
/DSET is sufficient to define a macro named SET with a value of 1.
Use the /D option in combination with the #if directive to conditionally
compile source files.
Removing definitions
If you have defined a numeric constant, using the equal sign with no number
removes the definition of that constant from the source file. For example,
to remove all occurrences of RELEASE, use the following option:
/DRELEASE=
Note that the identifier argument is case sensitive. For example, the /D
option above would have no effect on a constant named release that is
defined in the source file.
Defining macros and constants with the /D option has the same effect as
using a #define preprocessor directive at the beginning of your source file.
The identifier is defined until either an #undef directive in the source
file removes the definition or the compiler reaches the end of the file.
Duplicate definitions
If an identifier defined in a /D option is also defined within the source
file, QCL uses the definition on the command line until it encounters the
redefinition of the identifier in the source file, as illustrated in Figure
4.1.
(This figure may be found in the printed book.)
The /D option has the same effect as the Define text box in the QuickC
environment.
Example
#if !defined(RELEASE)
_nheapchk();
#endif
This code fragment calls a function to check the near heap unless the
constant RELEASE is defined. While the program is under development, you
can leave RELEASE undefined and perform heap checking to find bugs.
Assuming the program name is BIG.C, you would compile with the following
command:
QCL BIG.C
After you have found all of the bugs in the program, you can define RELEASE
in a /D option so that the program will run faster, as follows:
QCL /DRELEASE BIG.C
4.3.6 /E (Copy Preprocessor Output to Standard Output)
The /E option copies output from the preprocessor to the standard output
(usually your terminal). This output is identical to the original source
file except that all
preprocessor directives are carried out, macro expansions are performed, and
comments are removed. You normally use the /E option with the /C option (see
Section 4.3.4), which preserves comments in the preprocessed output. DOS
redirection can be used to save the output in a disk file.
The /E option also places a #line directive at the beginning and end of each
included file and around lines removed by preprocessor directives that
specify conditional compilation.
Use this option when you want to resubmit the preprocessed listing for
compilation. The #line directives renumber the lines of the preprocessed
file so that errors generated during later stages of processing refer to the
line numbers of the original source file rather than to the preprocessed
file.
The /E option suppresses compilation. QCL does not produce an object file or
map file, even if you specify the /Fo or /Fm option on the QCL command line.
Example
QCL /E /C ADD.C > PREADD.C
The command above creates a preprocessed file with inserted #line directives
from the source file ADD.C. The output is redirected to the file PREADD.C.
4.3.7 /EP (Copy Preprocessor Output to Standard Output)
The /EP option is similar to the /E option: it preprocesses the C source
file and copies preprocessor output to the standard output. Unlike the /E
option, however, the /EP option does not add #line directives to the output.
Preprocessed output is identical to the original source file except that all
preprocessor directives are carried out, macro expansions are performed, and
comments are removed. You can use the /EP option with the /C option (see
Section 4.3.4), which preserves comments in the preprocessed output.
The /EP option suppresses compilation; QCL does not produce an object file
or map file, even if you specify the /Fo or /Fm option on the QCL command
line.
Example
QCL /EP /C ADD.C
The command above creates a preprocessed file from the source file ADD.C. It
preserves comments but does not insert #line directives. The output appears
on the screen.
4.3.8 /F (Set Stack Size)
Option
/F number
The /F option sets the program stack size to number bytes, where number is a
hexadecimal number in the range 0001 to FFFF. Decimal and octal numbers are
not allowed. If you don't specify this option, a stack size of 2K is used by
default.
You may want to increase the stack size if your program gets stack-overflow
diagnostic messages. Conversely, if your program uses the stack very little,
you may want to decrease the size of your program by reducing the stack
size. In general, if you modify the stack size, do not use the /Gs option to
suppress stack checking.
4.3.9 /Fe (Rename Executable File)
Option
/Feexefile
By default, QCL names the executable file with the base name of the first
file (source or object) on the command line plus the extension .EXE. The /Fe
option lets you give the executable file a different name or create it in a
different directory.
Because QCL creates only one executable file, you can give the /Fe option
anywhere on the command line. If more than one /Fe option appears, QCL gives
the executable file the name specified in the last /Fe option on the command
line.
The /Fe option applies only in the linking stage. If you specify the /c
option to suppress linking, /Fe has no effect.
Path names and extensions
The exefile argument must appear immediately after the option with no
intervening spaces. The exefile argument can be a file specification, a
drive name, or a path specification. If exefile is a drive name or path
specification, the QCL command creates the executable file in the given
location, using the default name (base name of the first file plus .EXE). A
path specification must end with a backslash ( \ ) so that QCL can
distinguish it from an ordinary file name.
You are free to supply any name and any extension you like for exefile. If
you give a file name without an extension, QCL automatically appends the
.EXE extension.
Examples
QCL /FeC:\BIN\PROCESS *.C
The example above compiles and links all source files with the extension .C
in the current directory. The resulting executable file is named PROCESS.EXE
and is created in the directory C:\BIN.
QCL /FeC:\BIN\ *.C
The preceding example is similar to the first example except that the
executable file, instead of being named PROCESS.EXE, is given the same base
name as the first file compiled. The executable file is created in the
directory C:\BIN.
4.3.10 /Fm (Create Map File)
Option
/Fm «mapfile»
The /Fm option produces a map file. The map file contains a list of segments
in order of their appearance within the load module.
Path names and extensions
The mapfile argument must follow the /Fm option immediately with no
intervening spaces. The mapfile can be a file specification, a drive name,
or a path specification. It can also be omitted.
If you give just a path specification as the mapfile argument, the path
specification must end with a backslash ( \ ) so that QCL can distinguish it
from an ordinary file name. For example, to create a map file in the path
C:\LIST, the appropriate /Fm option is /FmC:\LIST\ .
If you do not specify a name for the map file or if you supply only a drive
name or path, QCL uses the base name of the first source or object file on
the command line plus the extension .MAP.
A fragment of a sample map file is shown below:
Start Stop Length Name Class
00000H 01E9FH 01EA0H _TEXT CODE
01EA0H 01EA0H 00000H C_ETEXT ENDCODE
.
.
.
Segment information
The information in the Start and Stop columns shows the 20-bit address
(in hexadecimal) of each segment, relative to the beginning of the load
module. The load module begins at location zero. The Length column gives
the length of the segment in bytes. The Name column gives the name of the
segment, and the Class column gives information about the segment type.
Group information
The starting address and name of each group appear after the list of
segments. A sample group listing is shown below:
Origin Group
01EA:0 DGROUP
In this example, DGROUP is the name of the data group. DGROUP is used for
all near data (that is, all data not explicitly or implicitly placed in
their own data segment) in Microsoft QuickC programs.
Global symbols
The map file shown below contains two lists of global symbols: the first
list is sorted in ASCII-character order by symbol name and the second is
sorted by symbol address. The notation Abs appears next to the names of
absolute symbols (symbols containing 16-bit constant values that are not
associated with program addresses).
Address Publics by Name
01EA:0096 STKHQQ
0000:1D86 _brkctl
01EA:04B0 _edata
01EA:0910 _end
.
.
.
01EA:00EC __abrkp
01EA:009C __abrktb
01EA:00EC __abrktbe
0000:9876 Abs __acrtmsg
0000:9876 Abs __acrtused
.
.
.
01EA:0240 ___argc
01EA:0242 ___argv
Address Publics by Value
0000:0010 _main
0000:0047 _htoi
0000:00DA _exp16
0000:0113 __chkstk
0000:0129 __astart
0000:01C5 __cintDIV
.
.
.
Global symbols in a map file usually have one or more leading underscores
because the QuickC compiler adds an underscore to the beginning of variable
names. Many of the global symbols that appear in the map file are symbols
used internally by the QuickC compiler and the standard libraries.
The addresses of the external symbols show the location of the symbol
relative to zero (the beginning of the load module).
Program entry point
Following the lists of symbols, the map file gives the program entry point,
as shown in the following example:
Program entry point at 0000:0129
────────────────────────────────────────────────────────────────────────────
NOTE
If you use the /Fm option with the /Gi option (for incremental compilation),
QCL produces a segmented-executable map file rather than a DOS executable
map file. The segment addresses in the file are different from those in DOS
map files, and the file itself has a different format.
────────────────────────────────────────────────────────────────────────────
4.3.11 /Fo (Rename Object File)
Option
/Foobjfile
By default, QCL gives each object file it creates the base name of the
corresponding source file plus the extension .OBJ. The /Fo option lets you
give different names to object files or create them in a different
directory. If you are compiling more than one source file, you can use the
/Fo option with each source file to rename the corresponding object file.
Keep the following rules in mind when using this option:
■ The objfile argument must appear immediately after the option, with no
intervening spaces.
■ Each /Fo option applies only to the next source file on the command
line.
Path names and extensions
You are free to supply any name and any extension you like for objfile.
However, it is recommended that you use the conventional .OBJ extension
since the linker and the LIB library manager use .OBJ as the default
extension when processing object files.
If you do not give a complete object-file name with the /Fo option (that is,
if you do not give an object-file name with a base and an extension), QCL
names the object file according to the following rules:
■ If you give an object-file name without an extension (such as TEST),
QCL automatically appends the .OBJ extension.
■ If you give an object-file name with a blank extension (such as
TEST.), QCL leaves the extension blank.
■ If you give only a drive or directory specification following the /Fo
option, QCL creates the object file on that drive or directory and
uses the default file name (the base name of the source file plus
.OBJ).
You can use this option to create the object file in another directory or on
another disk. When you give only a directory specification, the directory
specification must end with a backslash ( \ ) so that QCL can distinguish
between a directory specification and a file name.
Examples
QCL /FoB:\OBJECT\ THIS.C
In the example above, QCL compiles the source file THIS.C and gives the
resulting object file the name THIS.OBJ (by default). The directory
specification B: \OBJECT\ tells QCL to create THIS.OBJ in the directory
named \OBJECT on drive B.
QCL /Fo\OBJECT\ THIS.C THAT.C /Fo\SRC\NEWTHOSE.OBJ THOSE.C
In the example above, the first /Fo option tells the compiler to create the
object file THIS.OBJ (the result of compiling THIS.C) in the \OBJECT
directory. The second /Fo option tells the compiler to create the object
file NEWTHOSE.OBJ (the result of compiling THOSE.C) in the \SRC directory.
The compiler also creates the object file THAT.OBJ (the result of compiling
THAT.C) in the current directory.
4.3.12 /FP Options (Select Floating-Point-Math Package)
The /FPi and /FPi87 options specify how your program handles
floating-point-math operations.
4.3.12.1 /FPi (Emulator)
Use the /FPi option if you do not know whether an 8087 or 80287 math
coprocessor will be available at run time. Programs compiled with /FPi work
as follows:
■ If a coprocessor is present at run time, the program uses the
coprocessor.
■ If no coprocessor is present or if the NO87 environment variable has
been set, the program uses the emulator.
The /FPi option generates in-line instructions for an 8087 or 80287
coprocessor and places the name of the emulator library (mLIBCE.LIB) in the
object file. At link time, you can specify an 8087/80287 library
(mLIBC7.LIB) instead. If you do not choose a floating-point option, QCL uses
the /FPi option by default.
Interrupt fixups
This option works whether or not a coprocessor is present because the QuickC
compiler does not generate "true" in-line 8087/80287 instructions. Instead,
it generates software interrupts to library code. The library code, in turn,
fixes up the interrupts to use either the emulator or the coprocessor,
depending on whether a coprocessor is present. The fixups can be removed by
linking the file RMFIXUP.OBJ with the C program. Linking this file with
QuickC programs can save execution time (the time required to fix up all the
interrupts the first time). However, a C program linked with RMFIXUP.OBJ
will run only if a coprocessor is present.
4.3.12.2 /FPi87 (Coprocessor)
The /FPi87 option includes the name of an 8087/80287 library (mLIBC7.LIB) in
the object file. At link time, you can override this option and specify an
emulator library (mLIBCE.LIB) instead so that the program will run on
computers without coprocessors.
If you use the /FPi87 option and link with mLIBC7.LIB, an 8087 or 80287
coprocessor must be present at run time; otherwise, the program fails and
the following error message is displayed:
run-time error R6002
- floating point not loaded
If you compile with /FPi87 and link with mLIBCE.LIB, you can set the NO87
environment variable to suppress the use of the coprocessor (see Section
4.3.12.5).
Compiling with the /FPi87 option results in the smallest, fastest programs
possible for handling floating-point arithmetic.
4.3.12.3 Library Considerations for Floating-Point Options
You may want to use libraries in addition to the default library for the
floating-point option you have chosen on the QCL command line. For example,
you may want to create your own libraries or object files, then link them at
a later time with object files that you have compiled using different QCL
options.
You must be sure that you use only one standard combined C library when you
link. You can control which library QLINK uses in one of two ways:
1. Make sure the first object file passed to the linker has the name of
the desired library. For example, if you want to use an 8087/80287
library, give the /FPi87 option before the first source-file name on
the QCL command line; or, give the name of an object file compiled
with /FPi87 as the first file name on the command line. All
floating-point calls in this object file refer to the 8087/80287
library.
2. Give the /NOD (no default-library search) option after the /link
option on the QCL command line. Then specify the name of the library
you want to use on the QCL command line. The /NOD option overrides the
library names embedded in the object files. Because the linker
searches libraries given on the command line before it searches
libraries named in object files, all floating-point calls will refer
to the libraries you specify.
Removing library names
Another complication might arise if you create your own libraries: normally,
each module in the library you create contains a standard-library name, and
the linker tries to search the standard libraries named in the modules when
it links with your library.
The safest course, especially when you are distributing libraries to others,
is to use the /Zl option when you compile the object files that make up your
libraries. The /Zl option tells the compiler not to put library names in the
object files. Later, when you link other object files with your library, the
standard library used for linking will depend only on the floating-point and
memory-model options used to compile those object files.
Examples
QCL CALC.C ANOTHER SUM
In the example above, no floating-point option is given, so QCL compiles the
source file CALC.C with the default floating-point option, /FPi. The /FPi
option generates in-line instructions and selects the small-model-emulator
combined library (SLIBCE.LIB), which is the default.
QCL /FPi87 CALC.C ANOTHER.OBJ SUM.OBJ /link SLIBCE.LIB /NOD
In the example above, QCL compiles CALC.C with the /FPi87 option, which
selects the SLIBC7.LIB library. The /link option, however, overrides the
default library specification: the /NOD option suppresses the search for the
default library, and the alternate math library (SLIBCE.LIB) is specified.
QLINK uses SLIBCE.LIB when it creates the resulting executable file,
CALC.EXE.
4.3.12.4 Compatibility between Floating-Point Options
Each time you compile a source file, you can specify a floating-point
option. When you link two or more source files to produce an executable
program file, you are responsible for ensuring that floating-point
operations are handled in a consistent way.
Example
QCL /AM CALC.C ANOTHER SUM /link MLIBC7.LIB /NOD
The preceding example compiles the program CALC.C with the medium-model
option (/AM). Because no floating-point option is specified, the default
(/FPi) is used. The /FPi option generates in-line 8087/80287 instructions
and specifies the emulator library MLIBCE.LIB in the object file. The /link
field specifies the /NOD option and the name of the medium-model 8087/80287
library, MLIBC7.LIB. Specifying the 8087/80287 library forces the program to
use an 8087 coprocessor; the program fails if a coprocessor is not present.
4.3.12.5 The NO87 Environment Variable
Programs compiled with the /FPi option automatically use an 8087 or 80287
coprocessor at run time if one is installed. You can override this and force
the use of the emulator instead by setting an environment variable named
NO87.
Coprocessor-suppression message
If NO87 is set to any value when the program is executed, the program will
use the emulator even if a coprocessor is present. When this occurs, the
NO87 setting is displayed on the standard output as a message. The message
is displayed only if a coprocessor is present and its use is suppressed; if
no coprocessor is present, no message appears. If you want to force use of
the emulator, but don't want a message to appear, set NO87 equal to one or
more spaces. The variable is still considered to be defined.
Note that the presence or absence of the NO87 definition determines whether
use of the coprocessor is suppressed. The actual value of the NO87 setting
is used only for the message.
The NO87 variable takes effect with any program linked with an emulator
library (mLIBCE.LIB). It has no effect on programs linked with 8087/80287
libraries (mLIBC7.LIB).
Examples
SET NO87=Use of coprocessor suppressed
The example above causes the message Use of coprocessor suppressed to
appear when a program that would use an 8087 or 80287 coprocessor is
executed on a computer that has such a coprocessor.
SET NO87=space
The example above sets the NO87 variable to the space character. Use of the
coprocessor is still suppressed, but no message is displayed.
4.3.12.6 Standard Combined Libraries
Table 4.3 shows each combination of memory-model and floating-point options
and the corresponding library name that QCL embeds in the object file.
Table 4.3 QCL Options and Default Libraries
╓┌──────────────────────┌────────────────────┌───────────────────────────────╖
Floating-Point Option Memory-Model Option Default Library
────────────────────────────────────────────────────────────────────────────
/FPi87 /AT or /AS SLIBC7.LIB
/AM MLIBC7.LIB
/AC CLIBC7.LIB
/AL or /AH LLIBC7.LIB
Floating-Point Option Memory-Model Option Default Library
────────────────────────────────────────────────────────────────────────────
/AL or /AH LLIBC7.LIB
/FPi /AT or /AS SLIBCE.LIB
/AM MLIBCE.LIB
/AC CLIBCE.LIB
/AL or /AH LLIBCE.LIB
────────────────────────────────────────────────────────────────────────────
4.3.13 /G0, /G1, /G2 (Generate Instructions for 8086, 80186, or 80286
Processor)
If you are writing programs for a machine with an 80186 or 80286 processor,
you can use the /G1 or the /G2 option, respectively, to enable the
instruction set for those processors. When you use either of these options,
the compiler automatically defines the identifier M_I286.
Although it is sometimes advantageous to enable the appropriate instruction
set, you may not always wish to do so. If you have an 80286 processor, for
example, but you want your program to be able to run on an 8086, do not
compile with the /G2 option.
The /G0 option enables the instruction set for the 8086/8088 processor. You
do not have to specify this option explicitly because QCL uses the 8086/8088
instruction set by default. Programs compiled with this option will also run
on machines with 80186 and 80286 processors but will not take advantage of
any processor-specific instructions. When you specify the /G0 option, the
compiler automatically defines the identifier M_I8086.
If your program includes in-line assembler code that uses a mnemonic
instruction supported only by the 80186/87 or 80286/87 processors, you must
compile with the /G1 or the /G2 option, respectively; compiling with /G0
results in an error. Note that you cannot use 80186 or 80286 mnemonics as
labels, even if you are compiling for an 8086/8088.
These options apply to all file names that follow on the command line until
another /G0, /G1 or /G2 option appears.
4.3.14 /Gc, /Gd (Use FORTRAN/Pascal or C Calling Convention)
The _fortran, _pascal, and _cdecl keywords along with the /Gc and /Gd
options, allow you to control the function-calling and naming conventions so
that your QuickC programs can call and be called by functions that are
written in FORTRAN or Pascal.
Parameter-passing conventions
Because functions in QuickC programs can take a variable number of
arguments, QuickC must handle function calls differently from languages such
as Pascal and FORTRAN. Pascal and FORTRAN normally push actual parameters to
a function in left-to-right order so that the last argument in the list is
the last one pushed on the stack. In contrast, because QuickC functions do
not always know the number of actual parameters, they must push their
arguments from right to left, so that the first argument in the list is the
last one pushed.
Stack-cleanup conventions
Another difference between QuickC programs and FORTRAN or Pascal programs is
that in QuickC programs, the calling function must remove the arguments from
the stack. In Pascal and FORTRAN programs, the called function must remove
the arguments. If the code for removing arguments is in the called function
(as in Pascal and FORTRAN), it appears only once; if it is in the calling
function (as in QuickC), it appears every time there is a function call.
Because a typical program has more function calls than functions, the
Pascal/FORTRAN method results in slightly smaller, more efficient programs.
The _pascal and _fortran keywords
The QuickC compiler can generate the Pascal/FORTRAN calling convention in
one of several ways. The first is through the use of the _pascal and
_fortran keywords. When these keywords are applied to functions, or to
pointers to functions, they indicate a corresponding Pascal or FORTRAN
function (or a function that uses the Pascal/FORTRAN calling convention).
Therefore, the correct calling convention must be used. In the following
example, sort is declared as a function using the alternative calling
convention:
short pascal sort(char *, char *);
The _pascal and _fortran keywords can be used interchangeably. Use them when
you want to use the left-to-right calling sequence for selected functions
only.
The /Gc option
The second method for generating the Pascal/FORTRAN calling convention is to
use the /Gc option. If you use the /Gc option, the entire module is compiled
using the alternative calling convention. You might use this method to make
it possible to call all the functions in a QuickC module from another
language or to gain the performance and size improvement provided by this
calling convention.
When you use /Gc to compile a module, the compiler assumes that all
functions called from that module use the Pascal/FORTRAN calling convention,
even if the functions are defined outside that module. Therefore, using /Gc
would normally mean that you cannot call or define functions that take
variable numbers of parameters and that you cannot call functions such as
the QuickC library functions that use the QuickC calling sequence. In
addition, if you compile with the /Gc option, either you must declare the
main function in the source program with the _cdecl keyword, or you must
change the start-up routine so that it uses the correct naming and calling
conventions when calling main.
The _cdecl keyword
The _cdecl keyword in QuickC is the "inverse" of the _fortran and _pascal
keywords. When applied to a function or function pointer, it indicates that
the associated function is to be called using the normal QuickC calling
convention. This allows you to write QuickC programs that take advantage of
the more efficient Pascal/FORTRAN calling convention while still having
access to the entire QuickC library, other QuickC objects, and even
user-defined functions that accept variable-length argument lists. The
_cdecl keyword takes precedence over the /Gc option.
For convenience, the _cdecl keyword has already been applied to
run-timelibrary function declarations in the include files distributed with
the QuickC compiler. Therefore, your QuickC programs can call the library
functions freely, no matter which calling conventions you compile with. Just
make sure to use the appropriate include file for each library function the
program calls.
The /Gd option
The /Gd option has the same effect as the _cdecl keyword. It specifies that
the entire module should use the C calling convention. This option is on by
default.
Naming conventions
Use of the _pascal and _fortran keywords, or the /Gc option, also affects
the naming convention for the associated item (or, in the case of /Gc, all
items): the name is converted to uppercase letters, and the leading
underscore that QuickC normally prefixes is not added. The _pascal and
_fortran keywords can be applied to data items and pointers, as well as to
functions; when applied to data items or pointers, these keywords force the
naming convention described above for that item or pointer.
The _pascal, _fortran, and _cdecl keywords, like the _near, _far, and _huge
keywords, are disabled by use of the /Za option. If this option is given,
these names are treated as ordinary identifiers, rather than keywords.
Examples
int _cdecl var_print(char*,...);
In the example above, var_print is declared with a variable number of
arguments using the normal right-to-left QuickC function-calling convention
and naming conventions. The _cdecl keyword overrides the left-to-right
calling sequence set by the /Gc option if the option is used to compile the
source file in which this declaration appears. If this file is compiled
without the /Gc option, _cdecl has no effect since it is the same as the
default QuickC convention.
float *pascal nroot(number, root);
The example above declares nroot to be a function returning a pointer to a
value of type float. The function nroot uses the default calling sequence
(left-to-right) and naming conventions for Microsoft FORTRAN and Pascal
programs.
4.3.15 /Ge, /Gs (Turn Stack Checking On or Off)
Stack probes
A "stack probe" is a short routine called on entry to a function to verify
that the program stack has enough room to allocate local variables required
by the function. The stack-probe routine is called at every function-entry
point. Ordinarily, the stack-probe routine generates a stack-overflow
message if the required stack space is not available. When stack checking is
turned off, the stack-probe routine is not called, and stack overflow can
occur without being diagnosed (that is, no stack-overflow message is
printed).
The QuickC compiler uses stack probes to guard against possible execution
errors. These stack probes are used whenever the /Ge option (the default) is
in effect. You can remove the stack probes by using either the /Gs option or
the check_stack pragma, which will reduce the size of a program and speed up
execution slightly. Note that the /Gs option and the check_stack pragma have
no effect on standard C library routines, only on the functions you compile.
When to use the /Gs option
Use the /Gs option when you want to turn off stack checking for an entire
module, if you know that the program does not exceed the available stack
space. For example, stack probes may not be needed for programs that make
very few function calls or that have only modest local-variable
requirements. In the absence of the /Gs option, stack checking is on. The
/Gs option should be used with great care. Although it can make programs
smaller and faster, it may mean that the program will not be able to detect
certain execution errors.
When to use the check_stack pragma
Use the check_stack pragma when you want to turn stack checking on or off
only for selected routines, leaving the default (as determined by the
presence or absence of the /Gs option) for the rest. When you want to turn
off stack checking, put the following line before the definition of the
function you don't want to check:
#pragma check_stack (off)
Note that the preceding line disables stack checking for all routines that
follow it in the source file, not just the routines on the same line. To
reinstate stack checking, insert the following line:
#pragma check_stack (on)
If you don't give an argument for the check_stack pragma, stack checking
reverts to the behavior specified on the command line: disabled if the /Gs
option is given, or enabled if it is not. The interaction of the check_stack
pragma with the /Gs option is summarized in Table 4.4.
Table 4.4 Using the check_stack Pragma
╓┌────────────────────────┌────────────────────────┌─────────────────────────╖
Compiled with /Gs
Syntax Option? Action
────────────────────────────────────────────────────────────────────────────
#pragma check_stack() Yes Turns off stack checking
for routines that follow
#pragma check_stack() No Turns on stack checking
Compiled with /Gs
Syntax Option? Action
────────────────────────────────────────────────────────────────────────────
#pragma check_stack() No Turns on stack checking
for routines that follow
#pragma check_stack(on) Yes or no Turns on stack checking
for routines that follow
#pragma Yes or no Turns off stack checking
check_stack(off) for routines that follow
────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────
NOTE
For versions of Microsoft QuickC prior to 2.0, the check_stack pragma had a
different format: check_stack(+) to enable stack checking and check_stack(-)
to disable stack checking. Although the Microsoft QuickC compiler still
accepts this format, its use is discouraged because it may not be supported
in future versions.
────────────────────────────────────────────────────────────────────────────
Example
QCL /Gs FILE.C
This example optimizes the file FILE.C by removing stack probes with the /Gs
option. If you want stack checking for only a few functions in FILE.C, you
can use the check_stack pragma before and after the definitions of functions
you want to check.
4.3.16 /Gi (Use Incremental Compilation)
Option
/Gi«mdtname»
When you specify the /Gi option, QCL compiles only those functions in each C
source file that have changed since the last time the source file was
compiled. The process of compiling only the changed functions in a source
file is known as "incremental compilation." Because the compiler does not
need to handle the entire source file, incremental compilation is
considerably faster than regular compilation. However, the object files
created and the code generated when you compile incrementally may be larger.
If you specify any of the optimization (/Ostring) options on the same line
with /Gi, the compiler ignores the /Gi option.
If you own the Microsoft C Optimizing Compiler version 5.1 or earlier, and
you wish to use the CodeView debugger, do not use the /Gi option or the
related /Li option (for incremental linking). You can use the QuickC
integrated debugger, or the CodeView debugger included with the Microsoft C
Professional Development System version 6.0, on programs compiled with /Gi
and /Li.
Module-description table (MDT)
The compiler tracks changes for incremental compilation in a file known as a
"module-description table," or MDT. A single MDT can contain change
information for multiple source files. If you specify mdtname, the compiler
saves change information for all source files in a single MDT named mdtname.
If you do not specify mdtname, the compiler creates one MDT for each source
file named on the command line. Each MDT has the base name of the source
file and the .MDT extension.
The types of changes made to a source file determine whether the compiler
can incrementally compile a source file and whether the compiler creates or
updates the corresponding MDT.
Incrementally compile, update MDT
Except as noted below, if changes are confined to function bodies, the QCL
command compiles only those changed functions and the "global regions" of
the source file. Global regions are the parts of the source file between the
closing curly brace (}) of one function and the opening curly brace ({) of
the next function (see Figure 4.2). The compiler also updates the MDT to
reflect changes to the source file.
(This figure may be found in the printed book.)
If a global region of the source file has changed, QCL recompiles from the
point at which the change occurred. A change in a global region is any
change in the storage-class specifier, type specifier, function declarator,
or formal-parameter declarations of a function. Similarly, if a file
specified in an #include directive has a more recent modification date than
the including object module, QCL recompiles the source file from the point
at which the #include directive appears. In addition, if a function is
defined within an include file, the source file is recompiled from the start
of the function.
Compile whole program, don't update MDT
The compiler must recompile an entire source file, but does not update its
MDT, in both of these cases:
■ A function definition appears within an include file.
■ The compiler does not have enough memory to create the MDT.
Using function prototypes
For fastest compilation with /Gi, use a prototype for each function in your
program. A function prototype lists the name and type of the function and
the name and type of each of its parameters. (See Chapter 2, "Functions," in
C for Yourself for more information.) The C include files that Microsoft
supplies contain prototypes for all the functions in the C run-time library.
The information in the prototypes lets the compiler check the number and
type of arguments to the function.
If you use the /Gi option and your program contains functions without
corresponding prototypes, the compiler issues the following level 3 warning
message:
no function prototype given
Compilation errors
When the /Gi option is given and errors occur during compilation, the
compiler still creates a partial object file; that is, it generates object
code up to the point at which the error occurs. It places a record in each
object file indicating that the object file is invalid. If you try to link
one of these object files, the linker issues the following error message:
invalid object due to aborted incremental compile
Incremental linking
When the compiler can perform incremental compilation, it invokes a special
form of the linker that performs "incremental linking." Like incremental
compiling, incremental linking links only the object files that have changed
since the previous link. No library searches are performed; the assumption
is that the libraries are exactly the same as in the previous link.
Incremental linking is considerably faster than regular linking. If any of
the changes to the program prevent QuickC from performing an incremental
link, it automatically performs a full link. If you specify the /c option
along with the /Gi option, QCL performs incremental compilation, but does
not invoke any linker.
────────────────────────────────────────────────────────────────────────────
NOTE
If you use the /Gi option with the /Fm option (which produces a map file),
the map file is a segmented-executable map file rather than a DOS-executable
map file. The segment addresses in the file are different from those in DOS
map files, and the file itself has a different format.
────────────────────────────────────────────────────────────────────────────
Examples
For the following examples, assume there are three C source files named
MOD1.C, MOD2.C, and MOD3.C .
QCL /Gi MOD1.C MOD2.C MOD3.C
The example above incrementally compiles and links the three C source files.
Three MDTs are created or updated: MOD1.MDT, MOD2.MDT, and MOD3.MDT.
QCL /GiMYMDT.MDT MOD1.C MOD2.C MOD3.C
The example above has the same effect as the example preceding it, except
that the compiler creates or updates only one MDT named MYMDT.MDT. This MDT
includes all change-control information for the three C source files.
4.3.17 /Gr (Register Calling Convention)
Normally, your program passes parameters to functions on the stack. The /Gr
option causes your program to pass parameters in registers instead. This
calling convention decreases execution time if you are using the Microsoft C
Professional Development System version 6.0, but it gives no advantage if
you are using QuickC. Therefore, you should use the /Gr option only if you
plan on using the C Professional Development System for your final
compilation.
This method of parameter passing is not appropriate for all functions. The
/Gr option enables it for all eligible functions, and the _fastcall keyword
enables it on a function-by-function basis. The _fastcall keyword cannot be
used with the _cdecl or _pascal keywords.
Because the 80x86 processor has a limited number of registers, only the
first three parameters are passed in registers; the remaining parameters are
passed using the FORTRAN/Pascal calling convention (see the /Gc option).
Note that the compiler allocates different registers for variables declared
as register and for passing arguments using the register calling convention.
Passing arguments in registers does not conflict with any register variables
that you may have declared.
────────────────────────────────────────────────────────────────────────────
IMPORTANT
Exercise caution when using the register calling convention for any function
written in in-line assembly language. Your use of registers in assembly
language could conflict with the compiler's use of registers for storing
parameters.
────────────────────────────────────────────────────────────────────────────
4.3.17.1 The _fastcall Calling Convention
The following section describes the details of the _fastcall calling
convention. This information is for assembly-language programmers who are
interested in using either the in-line assembler or the Microsoft Macro
Assembler to write functions declared as _fastcall.
────────────────────────────────────────────────────────────────────────────
WARNING
The register usage documented here applies only to Microsoft QuickC version
2.5 and Microsoft C Professional Development System version 6.0. It may
change in future releases of either compiler.
────────────────────────────────────────────────────────────────────────────
4.3.17.2 Argument-Passing Convention
The _fastcall register calling convention is "strongly typed": the compiler
allocates arguments to registers according to the argument's data types.
Strong typing allows the compiler to generate better code. Because the
compiler chooses registers depending on the type of the argument and not in
a strict linear order, the calling program and called function must agree on
the types of the arguments in order to communicate data correctly.
For each type of argument, there is a list of register candidates. Each
argument is put in the first register candidate that does not already
contain an argument. If no suitable register remains unused, the arguments
are pushed onto the stack in left-to-right order. The following list shows
the basic types and the register candidate for each:
Type Register Candidates
────────────────────────────────────────────────────────────────────────────
character AL, DL, BL
unsigned character AL, DL, BL
integer AX, DX, BX
unsigned integer AX, DX, BX
long integer DX:AX
unsigned long integer DX:AX
near pointer BX, AX, DX
Structures and unions are always pushed onto the stack, as are all
floating-point types.
4.3.17.3 Return Value Convention
The _fastcall return value convention is based on the size of the return
value, except with floating-point types. All floating point types are
returned on the top of the numeric coprocessor stack (whether real or
emulated). The following list shows how values 4 bytes or smaller, including
unions and structures, are returned from a _fastcall function.
Size Return Convention
────────────────────────────────────────────────────────────────────────────
1 Byte AL Register
2 Bytes AX Register
4 Bytes DX, AX Registers (for pointers, the
segment is returned in DX, the offset in
AX; for long integers, the
most-significant byte is returned in DX,
leastsignificant byte in AX)
The method for returning values 4 bytes or smaller is the same as for
functions declared as _cdecl. To return structures and unions larger than 4
bytes, the calling function passes a hidden parameter after the rest of the
parameters have been pushed. This parameter is a near pointer, based in the
segment specified by the stack register (SS), to a buffer in which the value
is to be returned. A far pointer to SS:hidden-param is returned in DX:AX.
This is the same convention for returning structures as _pascal.
4.3.17.4 Stack Adjustment Convention
When a function declared as _cdecl terminates, the calling program clears
the stack of the parameters it passed. However, functions declared as
_fastcall must pop the parameters off the stack themselves. The calling
function does not adjust the stack after function return.
4.3.17.5 Register Preservation Requirement
All functions must preserve the DS, BP, SI, and DI registers. Your _fastcall
function can modify the values in AX, DX, and BX.
────────────────────────────────────────────────────────────────────────────
NOTE
The compiler can make significant optimizations by keeping certain values in
registers. One such value is the base for variables declared as _based. This
value is normally stored in the ES register. By declaring functions as
_fastcall, you guarantee that the ES register is preserved and that ES does
not have to be reloaded.
────────────────────────────────────────────────────────────────────────────
4.3.18 /Gt (Set Data Threshold)
Option
/Gt«number»
The /Gt option causes all data items whose size is greater than or equal to
number bytes to be allocated in a new data segment.
If you specify number, it must follow the /Gt option immediately with no
intervening spaces. If you use /Gt without a number, the default threshold
value is 256. If you don't use the /Gt option, the default threshold value
is 32,767.
Use this option with programs that have more than 64K of initialized static
and global data in small data items.
By default, the compiler allocates all static and global data items within
the default data segment in the tiny, small and medium memory models. In
compact-, large-, and huge-model programs, only initialized static and
global data items are assigned to the default data segment.
────────────────────────────────────────────────────────────────────────────
NOTE
You can use the /Gt option only if you are creating a compact-, large-, or
huge-model program because tiny-, small-, and medium-model programs have
only one data segment.
────────────────────────────────────────────────────────────────────────────
4.3.19 /Gw, /GW (Generate Code for Windows(tm) Function Calls)
The /Gw option instructs the compiler to generate entry/exit code sequences
for call-back functions in Windows applications. The /GW option is similar,
but it generates a more efficient entry sequence and is intended for use
with non-call-back functions. See the Microsoft Windows(tm) Software
Development Kit for more information.
4.3.20 /HELP (List the Compiler Options)
Option
/HELP
/help
This option displays a list of the most commonly used compiler options. QCL
processes all information on the line containing the /help option and
displays the command list.
Unlike all the other QCL options, /HELP is not case sensitive. Any
combination of uppercase and lowercase letters is acceptable. For example,
/hELp is a valid form of this option. The option has no abbreviation.
4.3.21 /I (Search Directory for Include Files)
Option
/Idirectory
You can add to the list of directories searched for include files by using
the /I (for "include") option. This option causes the compiler to search the
directory you specify before searching the directories given by the INCLUDE
environment variable. That way, you can give a particular file special
handling without changing the compiler environment you normally use.
The space between /I and directory is optional. To search more than one
directory, you can give additional /I options on the QCL command line. The
directories are searched in order of their appearance on the command line.
The directories are searched only until the specified include file is found.
If the file is not found in the given directories or the standard places,
the compiler prints an error message and stops processing. When this occurs,
you must restart compilation with a corrected directory specification.
Examples
QCL /I \INCLUDE /I\MY\INCLUDE MAIN.C
In the example above, QCL looks for the include files requested by MAIN.C in
the following order: first in the directory \INCLUDE, then in the directory
\MY\INCLUDE, and finally in the directory or directories assigned to the
INCLUDE environment variable.
QCL /X /I \ALT\INCLUDE MAIN.C
In the example above, the compiler looks for include files only in the
directory \ALT\INCLUDE. First the /X option tells QCL to consider the list
of standard places empty; then the /I option specifies one directory to be
searched.
4.3.22 /J (Change Default char Type)
In Microsoft QuickC, the char type is signed by default, so if a char value
is widened to int type, the result is sign-extended.
You can change this default to unsigned with the /J option, causing the char
type to be zero-extended when widened to int type. If a char value is
explicitly declared signed, however, the /J option does not affect it, and
the value is sign-extended when widened to int type. This option is useful
when working with character data that eventually will be translated into a
language other than English.
When you specify /J, the compiler automatically defines the identifier
_CHAR_UNSIGNED, which is used with #ifndef in the LIMITS.H include file to
define the range of the default char type.
4.3.23 /Lc, Lr (Compile for Real Mode)
The /Lc and /Lr options are synonymous. Both options compile the program for
OS/2 real mode or for the DOS environment. If you compile with /Lc or /Lr,
you must make sure the linker uses the appropriate real-mode library; either
use /NOD to tell the linker not to search for the default library, or rename
the appropriate real-mode library so that it has the default name.
4.3.24 /Li (Link Incrementally)
The /Li option specifies incremental linking, causing QCL to invoke ILINK
instead of QLINK for linking the object files. When you link incrementally,
the linker pads all _near functions to a 40-byte boundary by default. Note
that QCL automatically invokes the incremental linker when you use the /Gi
option for incremental compilation, unless you also specify the /c option to
prevent linking.
4.3.25 /Ln (Link without C Run-Time Startup Code)
If you are using the tiny memory model (see the /AT option for QCL), you
will be creating a .COM file (see the /T option for QLINK). Normally, QCL
tells QLINK to link tiny- model programs with CRTCOM.LIB; this file contains
startup code needed by any .COM program written in C. Programs that are
written in assembly language do not need this code. Use the /Ln option to
keep QLINK from linking with this startup code.
4.3.26 /ND, /NT (Name the Data or Code Segments)
Options
/NDdatasegment
/NTcodesegment
The /ND option renames a data segment in a QuickC program, and the /NT
option renames a code segment. The name can be any combination of letters
and digits. The space between the option and the argument is optional.
Each object file produced by the QuickC compiler has its code and its data
stored separately, in blocks called "segments." A segment that contains
program instructions is called a "code segment," while a segment that
contains program data is
called a "data segment." An object file may have one or more of each kind of
segment. When object files are linked into a program, these segments are
combined and reorganized. The program's memory model determines how many
code segments and how many data segments the resulting program has (see
Appendix B).
Every segment in every object file has a name. The linker uses this name to
determine which segments are combined during linking, and how the segments
are arranged in the .EXE file. (Note that the segments in the group named
DGROUP are an exception.) By using the /ND and /NT options, you can control
how segments are combined and arranged.
The QuickC compiler normally gives the code and data segments default names.
These default names are determined by the memory model chosen for the
program, as follows:
■ Tiny- and small-model programs. The code segment is named _TEXT and
the data segment is named _DATA. These names are the same for all
object files. During linking with the tiny model, all the code and
data are placed in one segment. During linking with the small model,
all code segments from all object files are placed in one segment, and
all data segments are placed in another segment.
■ Medium-model programs. The code segment for each object file is given
a distinct name, consisting of the module base name plus the suffix
_TEXT. The data segment is named _DATA.
■ Compact-model programs. All data items that are smaller than the
threshold size (specified by the /Gt option) are placed in the default
data segment, _DATA. If they are larger than the threshold, they are
placed in a segment having a distinct name consisting of the
object-file name plus a suffix (_DATA, _CONST, or _BSS). The code
segment is named _TEXT.
■ Large- and huge-model programs. The code and data from each object
file are placed in separate segments with distinct names. Each code
segment is given the name of the object file plus the suffix _TEXT.
All data items smaller than the threshold size are placed in the
default data segment, _DATA, and those that are larger are placed in a
segment with a unique name.
The /ND option creates three new segments with the names datasegment,
datasegment_BSS, and datasegment_CONST, and combines them into a group named
datasegment_GROUP. The program then treats the named segment as the default;
that is, it assumes that the data register (DS) contains the address of the
segment, so that it can access the segment's contents using near pointers
instead of far. In doing so, your program no longer assumes that the address
in the stack segment register (SS) is the same as the address in the data
register (DS). You must therefore use the _loadds modifier for function
declarations or the /Au segment setup option to ensure that DS is loaded on
entry to a function.
The /NT option gives the code segment the specified name. In general, you
should not use the /NT option with the tiny, small and compact memory
models. Doing so may cause fixup-overflow errors at link time (see Section
5.5.6 for more information).
4.3.27 /nologo (Suppress Display of Sign-On Banner)
The /nologo option suppresses the display of the sign-on banner when QCL is
invoked.
4.3.28 /O Options (Optimize Program)
Option
/O string
The /O options give you control over the optimizing procedures that the
compiler performs. The string consists of one or more of the letters "d,"
"l," "t," and "x." The list below shows how each of these affects
optimization:
Letter Optimizing Procedure
────────────────────────────────────────────────────────────────────────────
/Od Turns off all optimization
/Ol Enables loop optimization
/O, /Ot Favors execution speed during
optimization
(the default)
/Ox Maximizes optimization
The letters can appear in any order. More than one /O option can be given;
the compiler uses the last one on the command line if any conflict arises.
Each option applies to all source files that follow on the command line.
4.3.28.1 /Od (Turn Off Optimization)
The /Od (for "debug") option tells the compiler to turn off all
optimizations in the program. This option speeds compilation because the
compiler does not take time to perform optimizations.
Use the /Od option when you compile with the /Zi option (described in
Section 4.3.36) to include debugging information. The /Od option does not
reorganize code, thus making it easier to debug.
4.3.28.2 /Ol (Optimize Loops)
The /Ol option tells the compiler to perform loop optimizations, which store
frequently used loop variables in registers. The /Ox option implicitly turns
on the /Ol option.
4.3.28.3 /O and /Ot (Minimize Execution Time)
When you do not use any of the /O options, the QCL command automatically
favors program execution speed in the optimization. The /O and /Ot options
have the same effect as this default.
Wherever the compiler has a choice between producing smaller (but perhaps
slower) and larger (but perhaps faster) code, the compiler generates faster
code. For example, when you specify the /Ot option, the compiler generates
intrinsic functions to perform shift operations on long operands.
4.3.28.4 /Ox (Use Maximum Optimization)
The /Ox option is a shorthand way to combine optimizing options to produce
the fastest possible program. Its effect is the same as using the following
options on the same command line:
/Olt /Gs
That is, the /Ox option performs loop optimizations, favors execution time
over code size, and removes stack probes.
Example
QCL /Ol FILE.C
This command tells the compiler to perform loop optimizations when it
compiles FILE.C. The compiler favors program speed over program size because
the /Ot option is also specified by default.
4.3.29 /P (Create Preprocessor-Output File)
The /P writes preprocessor output to a file with the same base name as the
source file but with the .I extension. The preprocessed listing file is
identical to the original source file except that all preprocessor
directives are carried out and macro expansions are performed. You normally
use the /P option with the /C option (discussed in Section 4.3.4), which
preserves comments in the preprocessed output.
The /P option suppresses compilation; QCL does not produce an object file or
listing, even if you specify the /Fo or /Fm option on the QCL command line.
Example
QCL /P MAIN.C
The example above creates the preprocessed file MAIN.I from the source file
MAIN.C.
4.3.30 /Ta, /Tc (Specify Assembly Language or C Source File)
Options
/Tc filename
/Ta filename
The /Tc option specifies that filename is a C source file, even if it
doesn't have the extension .C. The /Ta option specifies that filename is an
assembly language file, even if it doesn't have the extension .ASM. You must
have installed the Microsoft Macro Assembler in order to use the /Ta option.
This option causes QCL to invoke the Macro Assembler to assemble the file.
The space between the option and the filename is optional.
If this option does not appear, QCL assumes that files with the .C extension
are C source files, files with the .ASM extension are assembly language
files, files with the .LIB extension are libraries, and files with any other
extension or with no extension are object files.
If you need to specify more than one source file with an extension other
than .C, you must specify each source file in a separate /Tc option. The
same is true with regard to assembly language files and the /Ta option.
Example
In the example below, the QCL command compiles the three source files
MAIN.C, TEST.PRG, and COLLATE.PRG.
QCL MAIN.C /Tc TEST.PRG /Tc COLLATE.PRG PRINT.PRG
Because the file PRINT.PRG is given without a /Tc option, QCL treats it as
an object file. Therefore, after compiling the three source files, QCL links
the object files MAIN.OBJ, TEST.OBJ, COLLATE.OBJ, and PRINT.PRG.
4.3.31 /U, /u (Remove Predefined Names)
Options
/U name
/u
The /U (for "undefine") option turns off the definition of one of the names
that the QuickC compiler predefines. The /u option turns off the definitions
of all predefined names except for the name of the memory model. These
options do not apply to user-defined names.
These names are useful in writing portable programs. For instance, they can
be used with compiler directives to conditionally compile parts of a
program, depending on the processor and operating system being used. The
predefined identifiers and their meanings are listed in Table 4.5.
One or more spaces can separate /U and name. You can specify more than one
/U option on the same command line.
The /u option turns off the definitions of all predefined names except
M_I86mM, which identifies the memory model. You can use the /U option to
remove the definition of M_I86mM. If you do, however, you must explicitly
define the NULL constant in your program since the definition of NULL in the
STDIO.H and STDDEF.H files depends on the memory model in use.
Limits on command-line definitions
The /U and /u options are useful if you need to give more than the maximum
number of definitions (23 if you use either the /Za or the /J option, 22 if
you use both options, or 24 otherwise) on the command line, or if you have
other uses for the predefined names. For each predefined name you remove,
you can substitute a definition of your own on the command line. When the
definitions of all six predefined names are removed, you can specify up to
30 command-line definitions. However, because MS-DOS limits the number of
characters you can type on a command line the number of definitions you can
specify in practice is probably fewer than 30.
Example
QCL /UMSDOS /UM_I86 WORK.C
This example removes the definitions of two predefined names. Note that the
/U option must be given twice to do this.
4.3.32 /V (Set Version String)
Option
/V string
The /V option embeds a text string in the object file. This string can label
an object file with a version number or a copyright notice. If the specified
string contains white-space characters, it must be enclosed in double
quotation marks (" "). A backslash must precede any embedded double
quotation marks.
Table 4.5 Predefined Names
╓┌────────────────┌────────────────────────────┌─────────────────────────────╖
Syntax Purpose When Defined
────────────────────────────────────────────────────────────────────────────
_CHAR_UNSIGNED Indicates that the char When the /J option is given
type is unsigned by default.
M_I86 Identifies target machine Always
as a member of the Intel(R)
family.
M_I86mM Identifies memory model, Always
where m is either T (tiny
model), S (small model), C
(compact model), M (medium
Syntax Purpose When Defined
────────────────────────────────────────────────────────────────────────────
(compact model), M (medium
model), L (large model), or
H (huge model). If huge
model is used, both M_I86LM
and M_I86HM are defined.
M_I8086 Identifies target machine When the /G0 option is given
as an 8086. and by default
M_I286 Identifies target machine When the /G1 or /G2 option
as an 80286. is given
_MSC_VER Identifies version of Always
Microsoft C currently
supported. Equal to 600.
MSDOS Identifies target operating Always
system as MS-DOS.
Syntax Purpose When Defined
────────────────────────────────────────────────────────────────────────────
NO_EXT_KEYS Indicates that When the /Za option is given
Microsoft-specific language
extensions and extended
keywords are disabled.
_QC Identifies compiler as Always
Microsoft QuickC.
────────────────────────────────────────────────────────────────────────────
4.3.33 /W, /w (Set Warning Level)
Options
/W{0|1|2|3|4|X}
/w
You can control the number of warning messages produced by the compiler by
using the /w, /W0, /W1, /W2, /W3, /W4, or /WX option. Compiler warning
messages are any messages beginning with C4; see Appendix D, "Error
Messages," for a complete list of these messages.
Warnings indicate potential problems (rather than actual errors) with
statements that may not be compiled as you intend.
The /W options affect only source files given on the command line; they do
not apply to object files.
The following list describes the warning-level options:
Option Action
────────────────────────────────────────────────────────────────────────────
/w Turns off all warning messages. Use this
option when you compile programs that
deliberately include questionable
statements. The /W0 option applies to
the remainder of the command line or
until the next occurrence of a /W option
on the command line.
/w0 Same as /w.
/W1 The default. Displays severe warning
messages.
/W2 Displays an intermediate level of
warning messages. Level-2 warnings may
or may not indicate serious problems.
They include warnings such as the
following:
■ Use of functions with no declared
return type
■ Failure to put return statements in
functions with non-void return types
■ Data conversions that would cause loss
of data or precision
/W3 Displays a higher level of warning
messages, including warnings about
function calls that precede their
function prototypes in the source code.
/W4 Displays the highest level of warning
messages, including warnings about the
use of non-ANSI features and extended
keywords.
/WX Treats all warnings as fatal errors. If
there are any warning messages, the
compilation aborts and QCL does not
produce an object file.
────────────────────────────────────────────────────────────────────────────
NOTE
The descriptions of the warning messages in Appendix D indicate the warning
level that must be set (that is, the number for the appropriate /W option)
for the message to appear.
────────────────────────────────────────────────────────────────────────────
Example
QCL /W4 CRUNCH.C PRINT.C
This example enables all possible warning messages when the source files
CRUNCH.C and PRINT.C are compiled.
4.3.34 /X (Ignore Standard Include Directory)
You can prevent the QuickC compiler from searching the standard places for
include files by using the /X (for "exclude") option. When QCL sees the /X
option, it does not search the current directory or any directories
specified in the INCLUDE environment variable.
You can use this option with the /I option to define the location of include
files that have the same names as include files found in other directories
but that contain different definitions. See Section 4.3.21 for an example of
/X used with /I.
4.3.35 /Ze, /Za (Enable or Disable Language Extensions)
Microsoft QuickC supports the ANSI C standard. In addition, it offers a
number of features beyond those specified in the ANSI C standard. These
features are enabled when the /Ze (default) option is in effect and disabled
when the /Za option is in effect. They include the following:
■ The _cdecl, _far, _fortran, _huge, _near, and _pascal keywords
■ Use of casts to produce lvalues:
int *p;
((long *)p)++;
The preceding example could be rewritten to conform with the ANSI C
standard:
p = (int *)((long *)p + 1);
■ Redefinitions of extern items as static:
extern int foo();
static int foo()
{}
■ Use of trailing commas (,) rather than an ellipsis (...) in function
declarations to indicate variable-length argument lists:
int printf(char *,);
■ Benign typedef redefinitions within the same scope:
typedef int INT;
typedef int INT;
■ Use of mixed character and string constants in an initializer:
char arr[5] = {'a', 'b', "cde"};
■ Use of bit fields with base types other than unsigned int or signed
int
■ Use of single-line comments, which are introduced with two slash
characters:
// This is a single-line comment.
■ Casting of a function pointer to a data pointer:
int (* pfunc) ();
int *pdata;
pdata = (int *) pfunc;
To perform the same cast while maintaining ANSI compatibility, you
must cast the function pointer to an int before casting it to a data
pointer:
pdata = (int *) (int) pfunc;
Use the /Za option if you plan to port your program to other environments.
The /Za option tells the compiler to treat extended keywords as simple
identifiers and disable the other extensions listed above.
When you specify /Za, the compiler automatically defines the identifier
NO_EXT_KEYS. In the include files provided with the QuickC run-time library,
this identifier is used with #ifndef to control use of the _cdecl keyword on
library function prototypes. For an example of this conditional compilation,
see the file STDIO.H.
4.3.36 /Zi, /Zd (Compile for Debugging)
The /Zi option produces an object file containing full symbolic-debugging
information for use with the QuickC debugger and the CodeView
window-oriented debugger. This object file includes full symbol-table
information and line numbers.
The /Zd option produces an object file containing line-number records
corresponding to the line numbers of the source file. Use /Zd if you plan to
debug with the SYMDEB debugger. Also use this option when you want to reduce
the size of an executable file that you will be debugging with the CodeView
debugger and when you do not need to use the expression evaluator during
debugging.
Example
QCL /c /Zi TEST.C
This command produces an object file named TEST.OBJ that contains line
numbers corresponding to the lines in TEST.C.
4.3.37 /Zl (Remove Default-Library Name from Object File)
Ordinarily, QCL puts the name of the default library (SLIBCE.LIB) in the
object file so that the linker can automatically find the correct library to
link with the object file.
The /Zl option tells the compiler not to place the default-library name in
the object file. As a result, the object file is slightly smaller.
Use the /Zl option when you are using the LIB utility (described in Chapters
2 and 6) to build a library. You can use /Zl to compile the object files you
plan to put in your library, thereby omitting the default-library names from
your object modules. Although the /Zl option saves only a small amount of
space for a single object file, the total amount of space saved is
significant in a library containing many object modules.
Example
QCL ONE.C /Zl TWO.C
The example above creates the following two object files:
1. An object file named ONE.OBJ that contains the name of the C library
SLIBCE.LIB
2. An object file named TWO.OBJ that contains no default-library
information
When ONE.OBJ and TWO.OBJ are linked, the default-library information in
ONE.OBJ causes the default library to be searched for any unresolved
references in either ONE.OBJ or TWO.OBJ.
4.3.38 /Zp (Pack Structure Members)
Option
/Zp«{1|2|4}»
When storage is allocated for structures, structure members are ordinarily
stored as follows:
■ Items of type char or unsigned char, or arrays containing items of
these types, are byte aligned.
■ Structures are word aligned; structures of odd size are padded to an
even number of bytes.
■ All other types of structure members are word aligned.
To conserve space or to conform to existing data structures, you may want to
store structures more or less compactly. The /Zp option and the pack pragma
control how structure data are packed into memory.
Use the /Zp option to specify the same packing for all structures in a
module. When you give the /Zpn option, where n is 1, 2, or 4, each structure
member after the first is stored on n-byte boundaries depending on the
option you choose. If you use the /Zp option without an argument, structure
members are packed on two-byte boundaries.
On some processors, the /Zp option may result in slower program execution
because of the time required to unpack structure members when they are
accessed. For example, on an 8086 processor, this option can reduce
efficiency if members with int or long type are packed in such a way that
they begin on odd-byte boundaries.
Use the pack pragma in your source code to pack particular structures on
boundaries different from the packing specified on the command line. Give
the pack(n) pragma, where n is 1, 2, or 4, before structures that you want
to pack differently. To reinstate the packing given on the command line,
give the pack() pragma with no arguments.
Table 4.6 shows the interaction of the /Zp option with the pack pragma.
Table 4.6 Using the pack Pragma
╓┌─────────────────────┌─────────────────────────┌───────────────────────────╖
Compiled with /Zp
Syntax Option? Action
────────────────────────────────────────────────────────────────────────────
#pragma pack() Yes Reverts to packing
specified on the command
line for structures that
follow
#pragma pack() No Reverts to default packing
for structures that follow
#pragma pack(n) Yes or no Packs the following
structures to the given
byte boundary until
changed or disabled
────────────────────────────────────────────────────────────────────────────
Compiled with /Zp
Syntax Option? Action
────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────
Example
QCL /Zp PROG.C
This command causes all structures in the program PROG.C to be stored
without extra space for alignment of members on int boundaries.
4.3.39 /Zr (Check Pointers)
The /Zr option checks for null or out-of-range pointers in your program. A
run-time error occurs if you try to run a program with such pointers.
#pragma check_pointer
If you compile with the /Zr option, you can use the check_pointer pragma
within your source file to turn checking on or off only for selected
pointers leaving the default (see below) for the remaining pointers in the
program. When you want to turn on pointer checking, put the following line
before the usage of the pointer you want to check:
#pragma check_pointer (on)
This line turns on pointer checking for all pointers that follow it in the
source file, not just the pointers on the following line. To turn off
pointer checking, insert the following line:
#pragma check_pointer (off)
If you don't give an argument for the check_pointer pragma, pointer checking
reverts to the behavior specified on the command line: turned on if the /Zr
option is given or turned off otherwise.
Example
QCL /Zr prog.c
This command causes QCL to check for null or out-of-range pointers in the
file prog.c. All pointers in the file are checked except those to which a
check_pointer(off) pragma applies.
4.3.40 /Zs (Check Syntax Only)
The /Zs option tells the compiler to check only the syntax of the source
files that follow the option on the command line. This option provides a
quick way to find and correct syntax errors before you try to compile and
link a source file.
When you give the /Zs option, the compiler does not generate code or produce
object files, object listings, or executable files. The compiler, however,
does display error messages if the source file has syntax errors.
Example
QCL /Zs TEST*.C
This command causes the compiler to perform a syntax check on all source
files in the current working directory that begin with TEST and end with the
.C extension. The compiler displays messages for any errors found.
4.3.41 Giving Options with the CL Environment Variable
Use the CL environment variable to specify files and options without giving
them on the command line. This variable has the following format:
SET CL=« «option» ... «file» ...» «/link « link-libinfo» »
Use this variable if you usually give a large number of files and options
when you compile. Ordinarily, DOS limits the command line to 128 characters.
The files and options that you define with the CL environment variable,
however, do not count toward this limit. Therefore, you can define the files
and options you use most often with the CL variable and then give only the
files and options you need for specific purposes on the command line.
The information defined in the CL variable is treated as though it appeared
before the information given on the QCL command line, as illustrated in
Figure 4.3.
(This figure may be found in the printed book.)
Note that if you have given an option in the CL environment variable, you
generally cannot turn off or change the option from the command line. You
must reset the CL environment variable and omit the file or option that you
do not want to use.
Also note that you cannot use CL to set options that use an equal sign (for
example, the /Didentifier= string option), and you cannot use wild-card
characters in file names to specify multiple files with CL.
Examples
In the following example, the CL environment variable tells the QCL command
to use the /Zp, /Ox, and /I options during compilation and then to link with
the object file \LIB\BINMODE.OBJ.
SET CL=/Zp /Ox /I\INCLUDE\MYINCLS \LIB\BINMODE.OBJ
QCL INPUT.C
With CL defined as shown, the QCL command above has the same effect as the
command line
QCL /Zp /Ox /I\INCLUDE\MYINCLS \LIB\BINMODE.OBJ INPUT.C
That is, both specify structure packing on two-byte boundaries; perform
maximum optimizations; search for include files in the \INCLUDE\MYINCLS
directory; and suppress translation of carriage-return-line-feed character
combinations for the source file INPUT.C.
In the following example, the CL environment variable tells the QCL command
to compile and link the source files FILE1.C and FILE2.C.
SET CL=FILE1.C FILE2.C
QCL FILE3.OBJ
The QCL command line above has the same effect as the command line
QCL FILE1.C FILE2.C FILE3.OBJ
The following example illustrates how to turn off the effects of a QCL
option defined in the environment.
SET CL=/Za
QCL FILE1.C /Ze FILE2.C
In this example, the CL environment variable is set to the /Za option, which
tells the compiler not to recognize Microsoft extensions to the C language.
This option causes Microsoft-specific keywords to be treated as ordinary
identifiers rather than reserved words. The QCL command specifies the
inverse option, /Ze, which tells the compiler to treat language extensions
as reserved words. Since the effect is the same as compiling with the
command line
QCL /Za FILE1.C /Ze FILE2.C
FILE1.C is compiled with language extensions turned off and FILE2.C is
compiled with language extensions enabled.
4.4 Controlling Stack and Heap Allocation
The "stack" and the "heap" are two important memory areas that are allocated
for QuickC programs. The stack is used for all local data (that is, data
that are defined within a function); the heap is used for all dynamically
allocated data (that is, data allocated by one of the alloc family of
functions).
Programs compiled and linked with QuickC run with a fixed stack size (the
default size is 2,048 bytes). The stack resides above static data, and the
heap uses whatever space is left above the stack. For some programs,
however, a fixed-stack model may not be ideal; a model where the stack and
heap compete for space is more appropriate.
Linking with the mVARSTCK.OBJ object files (where m is the first letter of
the library you choose) gives you such a model: when the heap runs out of
memory, it tries to use available stack space until it runs into the top of
the stack. When the allocated space in the heap is freed, it is once again
made available to the stack. Note that the stack cannot grow beyond the
last-allocated heap item in the stack, or, if there are no heap items in the
stack, beyond the size it was given at link time. Furthermore, while the
heap can employ unused stack space, the reverse is not true: the stack
cannot employ unused heap space.
You can change the model used to allocate heap space by linking your program
with one of the mVARSTCK.OBJ object files. These files are the small-,
medium-, compact-, and large-model versions of a routine that allows the
memory-allocation functions (malloc, calloc, _expand, _fmalloc, _nmalloc,
and realloc) to allocate items in unused stack space if they run out of
other memory. (If you use the huge memory model, link with the large-model
object file LVARSTCK.OBJ.)
When you link your program with one of the mVARSTCK.OBJ files, do not
suppress stack checking with the #check_stack pragma, or with the /Gs or /Ox
option. Stack overflow can occur more easily in programs that link with the
variable-stack object files, possibly causing errors that would be difficult
to detect.
Example
QCL TEST.C SVARSTCK
This command line compiles TEST.C and then links the resulting object module
with SVARSTCK.OBJ, the variable-stack object file for small-model programs.
Chapter 5 QLINK
────────────────────────────────────────────────────────────────────────────
This chapter describes in detail the operation of the Microsoft QuickC
Compiler linker (QLINK) and includes an alphabetical reference to the QLINK
options.
5.1 Overview
The QuickC linker (QLINK) combines object files into a single executable
file. It can be used with object files compiled or assembled for 8086/8088,
80286, 80386, or 80486 machines. The format of input to the linker is the
Microsoft Relocatable Object-Module Format (OMF), which is based on the
Intel 8086 OMF.
The output file from QLINK (that is, the executable file) is not bound to
specific memory addresses. Thus, the operating system can load and execute
this file at any convenient address. QLINK can produce executable files
containing up to one megabyte of code and data.
5.2 Invoking QLINK
Instead of using the QCL command to invoke the linker, you can use the QLINK
command to invoke QLINK directly. You can specify the input required for
this command in one of three ways:
1. By placing it on the command line.
2. By responding to prompts.
3. By specifying a file containing responses to prompts. This type of
file is known as a "response file."
Regardless of how you invoke QLINK, you can press CTRL+C at any time to
terminate a QLINK operation and exit to DOS.
You can use any combination of uppercase and lowercase letters for the file
names you specify on the QLINK command line or give in response to the QLINK
command prompts.
If you specify file names without extensions, QLINK uses the following
default file-name extensions:
File Type Default Extension
────────────────────────────────────────────────────────────────────────────
Object .OBJ
Executable .EXE
Map (or "Listing") .MAP
Library .LIB
You can override the default extension for a particular command-line field
or prompt by specifying a different extension. To enter a file name that has
no extension, type the name followed by a period.
5.2.1 Command Line
Use the following form of the QLINK command to specify input on the command
line:
QLINK «linkoptions» objfiles «, «exefile» «, «mapfile» «, «libraries» » »
» «;»
Commas must separate command-line fields. You can omit the text from any
field (except the required objfiles), but you must include the comma. A
semicolon can end the command line after any field causing QLINK to use
defaults for the remaining fields. See Section 5.2.1.6 for details of QLINK
defaults.
The command-line fields are explained below.
5.2.1.1 QLINK Options
You can specify command-line options after any field but before the comma
that terminates the field. You do not have to give any options when you run
the linker. Linker options are described in Section 5.4.
5.2.1.2 Object Files
The objfiles field allows you to specify the names of the object files you
are linking. You must specify at least one object-file name. A space or plus
sign (+) must separate each pair of object-file names. QLINK automatically
supplies the .OBJ extension when you give a file name without an extension.
If your object file has
a different extension or if it appears in another directory or on another
disk, you must give the full name─including the extension and path name─for
the file to be found. If QLINK cannot find a given object file and the drive
associated with the object file is a removable-disk (floppy) drive, then
QLINK displays a message and waits for you to change disks.
You can also specify one or more libraries in the objfiles field. To enter a
library in this field, make sure that you include the .LIB extension;
otherwise, QLINK assumes the .OBJ extension. Libraries entered in this field
are called "load libraries." QLINK automatically links in every object
module in a load library; it does not search for unresolved external
references first. The effect of entering a load library is exactly the same
as if you had entered the names of all the library's object modules in the
objfiles field. This feature is useful if you are developing software using
many object files and wish to avoid typing the name of each file on the
QLINK command line.
5.2.1.3 Executable File
The exefile field allows you to specify the name of the executable file. If
the file name you give does not have an extension, QLINK automatically adds
.EXE as the extension. You can give any file name you like. However, if you
are specifying an extension, you should always use .EXE because DOS expects
executable files to have either this extension or the .COM extension.
5.2.1.4 Map File
The mapfile field allows you to specify the name of the map file if you are
creating one. To include public symbols and their addresses in the map file,
specify the /MAP option on the QLINK command line.
If you specify a map-file name without an extension, QLINK automatically
adds a .MAP extension. QLINK creates the map file in the current working
directory unless you specify a path name for the map file.
5.2.1.5 Libraries
The libraries field allows you to specify the name of one or more libraries
that you want linked with the object file(s). When QLINK finds the name of a
library in this field, it treats the library as a "regular library"; QLINK
links in only those object modules needed to resolve external references.
Each time you compile a source file for a high-level language, the compiler
places the name of one or more libraries in the object file that it creates;
the linker automatically searches for a library with this name (see Section
5.2.4). Because of this, you do not need to give library names on the QLINK
command line unless you want to search libraries other than the default
libraries or libraries in different locations.
When you link your program with a library, the linker pulls into your
executable file any library modules that your program references. If the
library modules have external references to other library modules, the
linker links your program with those other library modules as well.
5.2.1.6 Choosing Defaults
If you include a comma (to indicate where a field would be) but do not put a
file name before the comma, then QLINK selects the default for that field.
However, if you use a comma to include the mapfile field (but do not include
a name), then QLINK creates a map file. This file has the same base name as
the executable file. Use NUL for the map-file name if you do not want to
produce a map file.
You can also select default responses by using a semicolon (;). The
semicolon tells QLINK to use the defaults for all remaining fields. QLINK
ignores anything after the semicolon. If you do not give all file names on
the command line or if you do not end the command line with a semicolon, the
linker prompts you for the files you omitted. See Section 5.2.2 for a
description of these prompts.
The list below summarizes the linker's defaults for each field:
Field Default
────────────────────────────────────────────────────────────────────────────
linkoptions Assumes no options.
exefile Creates a file with the base name of the
first object file and a .EXE extension.
mapfile Does not create a map file unless you
include the mapfile field. The field may
be empty, as in the following command
line:
QLINK myfile yourfile, ourfile, ;
If you include the field, but not a file
name, QLINK creates a map file with the
base name of the executable file and the
.MAP extension. Thus the example creates
a map file named OURFILE.MAP.
libraries Searches only the default libraries
specified in the object files.
If you do not specify a drive or directory for a file, the linker assumes
that the file is on the current drive and directory. If you want the linker
to create files in a location other than the current drive and directory,
you must specify the new drive and directory for each such file on the
command line.
Examples
QLINK SPELL+TEXT+DICT+THES, ,SPELLIST, XLIB.LIB
The command line above causes QLINK to load and link the object files
SPELL.OBJ, TEXT.OBJ, DICT.OBJ, and THES.OBJ, and to search for unresolved
references in the library file, XLIB.LIB, and the default libraries. By
default, QLINK gives the executable file that it produces the name
SPELL.EXE. QLINK also produces a map file, SPELLIST.MAP. Note that a
semicolon is not required because a library is specified.
QLINK SPELL,,;
The QLINK command line shown above produces a map file SPELL.MAP because a
comma appears as a placeholder for the mapfile specification on the command
line.
QLINK SPELL,;
QLINK SPELL;
The two command lines above do not produce a map file because commas do not
appear as placeholders for the mapfile specification.
QLINK MAIN+GETDATA+PRINTIT, , MAIN;
The command above causes QLINK to link the three files MAIN.OBJ,
GETDATA.OBJ, and PRINTIT.OBJ into an executable file. QLINK also produces a
map file named MAIN.MAP.
5.2.2 Prompts
If you want the linker to prompt you for input, start QLINK by entering
QLINK
at the DOS prompt. QLINK also displays prompts if you type an incomplete
command line that does not end with a semicolon or if a response file is
missing any required responses (see Section 5.2.3) .
QLINK prompts you for the input it needs by displaying the following lines,
one at a time. The items in square brackets are the defaults QLINK applies
if you press ENTER in response to the prompt. (You must supply at least one
object-file name for the "Object Modules" prompt.) QLINK waits for you to
respond to each prompt before it displays the next one.
Object Modules [.OBJ]:
Run File [basename.EXE]:
List File [NUL.MAP]:
Libraries [.LIB]:
Note that the default for the Run File prompt is the base name of the
first object file with the .EXE extension.
The responses you give to the QLINK command prompts correspond to the fields
on the QLINK command line as follows:
Prompt Command-Line Field
────────────────────────────────────────────────────────────────────────────
"Object Modules" objfiles
"Run File" exefile
"List File" mapfile
"Libraries" libraries
Continuation character (+)
If you type a plus sign (+) as the last character on a response line, the
same prompt appears on the next line; you can then continue typing
responses. The plus sign must appear at the end of a complete file or
library name, path name, or drive name.
Choosing defaults
To select the default response to the current prompt, press ENTER without
giving a file name. The next prompt appears.
To select default responses to the current prompt and all remaining prompts,
type a semicolon (;) and press ENTER. You can enter the semicolon by itself,
or place it after your response to the current prompt. After you type a
semicolon, you cannot respond to any of the remaining prompts for that link
session. This option saves time when you want the default responses. Note,
however, that because there is no default response for that prompt, you
cannot enter only a semicolon in response to the "Object Modules" prompt;
the linker requires the name of at least one object file.
The following list shows the defaults for the other linker prompts:
Prompt Default
────────────────────────────────────────────────────────────────────────────
"Run File" The name of the first object file
submitted at the "Object Modules" prompt,
with the .EXE extension replacing the
.OBJ extension
"List File" The special file name NUL.MAP, which
tells QLINK not to create a map file
"Libraries" The default libraries encoded in the
object files (see Section 5.2.4)
5.2.3 Response File
A response file contains responses to the QLINK prompts. The responses must
be in the same order as the QLINK prompts discussed in the previous section.
Each new response must appear on a new line or must begin with a comma;
however, you can extend long responses across more than one line by typing a
plus sign (+) as the last character of each incomplete line. You can give
options at the end of any response or place them on one or more separate
lines.
QLINK treats the input from the response file just as if you had entered it
in response to prompts or on a command line. It treats any new-line
character in the response file as if you had pressed ENTER in response to a
prompt or included a comma in a command line. (This mechanism is illustrated
in Figure 5.1.) For compatibility with OS/2 versions of the linker, it is
recommended that all linker response files end with a semicolon after the
last line.
(This figure may be found in the printed book.)
To use the linker with a response file, create the response file, then type
the following command:
QLINK @responsefile
Here responsefile specifies the name or path name of the response file for
the linker. You can also enter the name of a response file, preceded by an
"at" sign (@), after any QLINK command prompt or at any position in the
QLINK command line; in this case, the response file completes the remaining
input.
Options and command characters
You can use options and command characters in the response file in the same
way you would use them in responses you type at the keyboard. For example,
if you type a semicolon on the line of the response file corresponding to
the "Run File" prompt, QLINK uses the default responses for the executable
file and for the remaining prompts.
Prompts
When you enter the QLINK command with a response file, each QLINK prompt is
displayed on your screen with the corresponding response from your response
file. If the response file does not include a line with a file name,
semicolon, or carriage return for each prompt, QLINK displays the
appropriate prompt and waits for you to enter a response. When you type an
acceptable response, QLINK continues.
Example
Assume that the following response file is named SPELL.LNK:
SPELL+TEXT+DICT+THES
/PAUSE /MAP
SPELLIST
XLIB.LIB;
You can type the following command to run QLINK and tell it to use the
responses in SPELL.LNK:
QLINK @SPELL.LNK
The response file tells QLINK to load the four object files SPELL, TEXT,
DICT, and THES. QLINK produces an executable file named SPELL.EXE and a map
file named SPELLIST.MAP. The /PAUSE option tells QLINK to pause before it
produces the executable file so that you can swap disks, if necessary. The
/MAP option tells QLINK to include public symbols and addresses in the map
file. QLINK also links any needed routines from the library file XLIB.LIB.
The semicolon is included after the library name for compatibility with the
OS/2 version of the linker.
5.2.4 How QLINK Searches for Libraries
QLINK searches for libraries that are specified in either of the following
ways:
■ In the libraries field on the command line or in response to the
"Libraries" prompt.
■ By an object file. The QuickC compiler writes the name of a default
combined library in each object file it creates.
────────────────────────────────────────────────────────────────────────────
NOTE
The material in this section does not apply to libraries that QLINK finds in
the objfiles field, either on the command line or in response to the "Object
Modules" prompt. Those libraries are treated simply as a series of object
files, and QLINK does not conduct extensive searches in such cases.
────────────────────────────────────────────────────────────────────────────
Library name with path specification
If the library name includes a path specification, QLINK searches only that
directory for the library. Libraries specified by object files (that is,
default libraries) normally do not include a path specification.
Library name without path specification
If the library name does not include a path specification, QLINK searches
the following locations, in the order shown, to find the library file:
1. The current directory
2. Any path specifications or drive names that you give on the command
line or type in response to the "Libraries" prompt, in the order in
which they appear
3. The locations given by the LIB environment variable
Because object files created by the QuickC compiler contain the names of all
the standard libraries you need, you are not required to specify a library
on the QLINK command line or in response to the QLINK "Libraries" prompt
unless you want to do one of the following:
■ Add the names of additional libraries to be searched
■ Search for libraries in different locations
■ Override the use of one or more default libraries
For example, if you have developed your own customized libraries, you might
want to include one or more of them as additional libraries at linking time.
5.2.4.1 Searching Additional Libraries
You can tell QLINK to search additional libraries by specifying one or more
library files on the command line or in response to the "Libraries" prompt.
QLINK searches these libraries in the order you specify before it searches
default libraries.
QLINK automatically supplies the .LIB extension if you omit it from a
library-file name. If you want to link a library file that has a different
extension, be sure to specify the extension.
5.2.4.2 Searching Different Locations for Libraries
You can tell QLINK to search additional locations for libraries by giving a
drive name or path specification in the libraries field on the command line
or in response to the "Libraries" prompt. Each path must end with a
backslash. You can specify up to 32 additional paths. If you give more than
32 paths, QLINK ignores the additional paths without displaying an error
message.
5.2.4.3 Overriding Libraries Named in Object Files
If you do not want to link with the library whose name is included in the
object file, you can give the name of a different library instead. You might
need to specify a different library name in the following cases:
■ You assigned a custom name to a standard library when you set up your
libraries
■ You want to link with a library that supports a different math package
than the math package you gave on the compiler command line (or the
default)
If you specify a new library name on the QLINK command line, the linker
searches the new library to resolve external references before it searches
the library specified in the object file.
If you want the linker to ignore the library whose name is included in the
object file, you must use the /NOD option. This option tells QLINK to ignore
the default-library information that is encoded in the object files created
by high-level-language compilers. Use this option with caution; see Section
5.4.14 for more information.
Example
QLINK
Microsoft(R) QuickC Linker Version 4.10.
Copyright(C) Microsoft Corp 1989. All rights reserved.
Object Modules [.OBJ]: SPELL TEXT DICT THES
Run File [SPELL.EXE]:
List File [NUL.MAP]:
Libraries [.LIB]: C:\TESTLIB\ NEWLIBV3
This example links four object files to create an executable file named
SPELL.EXE. QLINK searches NEWLIBV3.LIB before searching the default
libraries to resolve references. To locate NEWLIBV3.LIB and the default
libraries, the linker searches the current working directory, then the
C:\TESTLIB\ directory, and finally the locations given by the LIB
environment variable.
5.3 QLINK Memory Requirements
QLINK uses available memory for the link session. If the files to be linked
create an output file that exceeds available memory, QLINK creates a
temporary disk file to serve as memory. Depending on the DOS version, QLINK
handles this temporary file in one of the following ways:
■ For the purpose of creating a temporary file, the linker uses the
directory specified by the TMP environment variable. If the TMP
variable is set to C:\TEMPDIR, for example, then QLINK puts the
temporary file in C:\TEMPDIR.
If there is no TMP environment variable or if the directory specified
by TMP does not exist, then QLINK puts the temporary file in the
current directory.
■ If the linker is running on DOS version 3.0 or later, it uses a DOS
system call to create a temporary file with a unique name in the
temporary-file directory.
■ If the linker is running on a version of DOS prior to version 3.0, it
creates a temporary file named VM.TMP.
When the linker creates a temporary disk file, you see the message
Temporary file tempfile has been created.
Do not change diskette in drive, letter.
In the message displayed above, tempfile is ".\" followed by either VM.TMP
or a name generated by DOS, and letter is the drive containing the temporary
file.
If you are running QuickC on a removable-disk system, the message
Do not change diskette
appears. After this message appears, do not remove the disk from the
specified drive until the link session ends. If you remove the disk, the
operation of QLINK is unpredictable, and you may see the following message:
unexpected end-of-file on scratch file
If this happens, rerun the link session. The temporary file created by QLINK
is a working file only. QLINK deletes it at the end of the link session.
────────────────────────────────────────────────────────────────────────────
NOTE
Do not give any of your own files the name VM.TMP. The linker displays an
error message if it encounters an existing file with this name.
────────────────────────────────────────────────────────────────────────────
5.4 QLINK Options
This section explains how to use linker options to specify and control the
tasks performed by QLINK.
When you use the QLINK command line to invoke QLINK, you can put options at
the end of the line or after individual fields on the line. However, options
must immediately precede the comma that separates each field from the next.
If you respond to the individual prompts for the QLINK command, you can
specify linker options at the end of any response. When you use more than
one option, you can either group the options at the end of a single response
or distribute the options among several responses. Every option must begin
with the slash character ( / ), even if other options precede it on the same
line.
In a response file, options can appear on a line by themselves or after
individual response lines.
Abbreviations
Because linker options are named according to their functions, some of their
names are quite long. You can abbreviate the options to save space and
effort. Be sure that your abbreviation is unique so that the linker can
determine which option you want. The minimum legal abbreviation for each
option is indicated in the syntax description of the option.
Abbreviations must begin with the first letter of the name and must be
continuous through the last letter typed. No gaps or transpositions are
allowed. Options can be entered in uppercase or lowercase letters.
Numeric arguments
Some linker options take numeric arguments. A numeric argument can be any of
the following:
■ A decimal number from 0 to 65,535.
■ An octal number from 00 to 0177777. QLINK interprets a number as octal
if it starts with 0. For example, the number 10 is interpreted as a
decimal number, but the number 010 is interpreted as an octal number,
equivalent to 8 in decimal.
■ A hexadecimal number from 0X0 to 0XFFFF. QLINK interprets a number as
hexadecimal if it starts with 0X. For example, 0X10 is a hexadecimal
number, equivalent to 16 in decimal.
LINK environment variable
You can use the LINK environment variable to cause certain options to be
used each time you link. The linker checks the environment variable for
options if the variable exists.
The linker expects to find options listed in the variable exactly as you
would type them on the command line. It does not accept any other arguments;
for instance, including file names in the environment variable causes the
error message
unrecognized option name
Each time you link, you can specify options in addition to those in the LINK
environment variable. If you enter the same option both on the command line
and in the environment variable, the linker ignores the redundant option. If
the options conflict, however, the command-line option overrides the effect
of the environment variable option. For example, the command-line option
/SE:512 cancels the effect of the environment-variable option /SE:256.
────────────────────────────────────────────────────────────────────────────
NOTE
The only way to prevent an option in the environment variable from being
used is to reset the environment variable itself.
────────────────────────────────────────────────────────────────────────────
Example
>SET LINK=/NOI /SE:256 /CO
>QLINK TEST;
>QLINK /NOD /CO PROG;
In the example above, the file TEST.OBJ is linked with the options /NOI,
/SE:256, and /CO. The file PROG.OBJ is then linked with the option /NOD, in
addition to /NOI, /SE:256, and /CO. Note that the second /CO option is
ignored.
5.4.1 /BA (Running in Batch Mode)
Option
/BA«TCH»
By default, the linker prompts you for a new path name whenever it can't
find a library it has been directed to use. It also prompts you if it cannot
find an object file that it expects to find on a removable disk. If you use
the /BA option, however, the linker does not prompt you for any libraries or
object files that it cannot find. Instead, the linker generates an error or
warning message, if appropriate.
In addition, when you use /BA, the linker does not display its copyright
banner, nor does it echo commands from response files. This option does not
prevent the linker from prompting for command-line arguments. You can
prevent such prompting only by using a semicolon on the command line or in a
response file.
Using this option may result in unresolved external references. It is
intended primarily for use with batch or NMAKE files that link many
executable files with a single command and to prevent linker operation from
halting.
────────────────────────────────────────────────────────────────────────────
NOTE
In previous versions of the linker included with QuickC, the /BATCH option
was abbreviated to /B.
────────────────────────────────────────────────────────────────────────────
5.4.2 /CO (Link for Debugging)
Option
/CO«DEVIEW»
Use the /CO option to prepare for debugging with the integrated QuickC
debugger or the CodeView window-oriented debugger. This option tells the
linker to prepare a special executable file containing symbolic data and
line-number information.
Object files linked with the /CO option must first be compiled with the /Zi
option, which is described in Section 4.3.36.
You can run this executable file outside the CodeView debugger; the extra
data in the file are ignored. To keep file size to a minimum, however, use
the special-format executable file only for debugging; then you can link a
separate version without the /CO option after you've debugged the program.
5.4.3 /CP (Set the Maximum Allocation Space)
Option
/CP«ARMAXALLOC»:number
The /CP option sets the maximum number of 16-byte paragraphs needed by the
program when it is loaded into memory. The operating system uses this value
when allocating space for the program before loading it. The option is
useful when you want to execute another program from within your program and
you need to reserve space for that other program.
QLINK normally requests the operating system to set the maximum number of
paragraphs to 65,535. Since this represents more memory than could be
available under DOS, the operating system always denies the request and
allocates the largest contiguous block of memory it can find. If you specify
the /CP option, the operating system allocates no more space than the option
specifies. This means any additional space in memory is free for other
programs.
The number can be any integer value in the range 1-65,535. If number is less
than the minimum number of paragraphs needed by the program, QLINK ignores
your request and sets the maximum value equal to whatever the minimum value
happens to be. The minimum number of paragraphs needed by a program is
never less than the number of paragraphs of code and data in the program. To
free more memory for programs compiled in the medium and large memory
models, link with /CP:1; this leaves no space for the near heap.
5.4.4 /DO (Order Segments)
Option
/DO«SSEG»
The /DO option forces a special ordering on segments. This option is
automatically enabled by a special object-module record in Microsoft QuickC
libraries. If you are linking to one of these libraries, then you do not
need to specify this option.
This option is also enabled by assembly modules that use the Microsoft Macro
Assembler directive .DOSSEG.
The /DO option forces segments to be ordered as follows:
1. All segments with a class name ending in CODE
2. All other segments outside DGROUP
3. DGROUP segments, in the following order:
a. Any segments of class BEGDATA (this class name reserved for Microsoft
use)
b. Any segments not of class BEGDATA, BSS, or STACK
c. Segments of class BSS
d. Segments of class STACK
When the /DO option is in effect, the linker initializes two special
variables as follows:
_edata = DGROUP : BSS
_end = DGROUP : STACK
The variables _edata and _end have special meanings for the Microsoft C and
FORTRAN compilers, so it is not wise to give these names to your own program
variables. Assembly modules can reference these variables but should not
change them.
5.4.5 /DS (Load Data at High Address)
Option
/DS«ALLOCATE»
QLINK normally loads all data starting at the low end of the data segment.
At run time, the DS (data segment) register is set to the lowest possible
address to allow the entire data segment to be used.
Use the /DS option to tell QLINK to load all data starting at the high end
of the data segment instead of at the low end. In this case, the DS register
is set at run time to the lowest data-segment address that contains program
data.
You can use the /DS option with the /HI option (see Section 5.4.9) to take
advantage of unused memory within the data segment.
────────────────────────────────────────────────────────────────────────────
WARNING
This option should be used only with assembly-language programs.
────────────────────────────────────────────────────────────────────────────
5.4.6 /E (Pack Executable Files)
Optionspecific types>
/E«XEPACK»
The /E option directs QLINK to remove sequences of repeated bytes (typically
null characters) and to optimize the load-time-relocation table before
creating the executable file. (The load-time-relocation table is a table of
references, relative to the start of the program. Each reference changes
when the executable image is loaded into memory and an actual address for
the entry point is assigned.)
Executable files linked with this option may be smaller, and thus load
faster, than files linked without this option. Programs with many load-time
relocations (about 500 or more) and long streams of repeated characters are
usually shorter if packed. The /E option, however, does not always save a
significant amount of disk space and may sometimes increase file size. QLINK
notifies you if the packed file is larger than the unpacked file.
Note that you cannot use the QuickC debugger, the Symbolic Debug Utility
(SYMDEB), or the CodeView window-oriented debugger to debug packed files.
The /E option strips symbolic information needed by the debuggers from the
input file and issues a warning message to notify you.
5.4.7 /F (Optimize Far Calls)
Option
/F«ARCALLTRANSLATION»
The /F option directs the linker to optimize far calls to procedures that
lie in the same segment as the caller. Using the /F option may result in
slightly faster code and smaller executable-file size. It should be used
with the /PACKC option (see Section 5.4.23) for significant results. By
default, the /F option is off. Furthermore, once you have enabled it, you
can disable it for one or more object files by using the /NOF option (see
Section 5.4.16).
For example, a medium- or large-model program may include a machine
instruction that makes a far call to a procedure in the same segment.
Because both the instruction and the procedure it calls have the same
segment address, only a near call is truly necessary. A near-call
instruction does not require an entry in the relocation table; a far-call
instruction does. In this situation, use of /F (together with /PACKC)
results in a smaller executable file because the relocation table is
smaller. Such files load faster.
When /F has been specified, the linker optimizes code by removing the
following instruction:
call FAR label
and substituting the sequence
push cs
call NEAR label
nop
Upon execution, the called procedure still returns with a far-return
instruction. Because both the code segment and the near address are on the
stack, however, the far return is executed correctly. The nop (no-op)
instruction appears so that exactly five bytes replace the five-byte
far-call instruction; the linker may in some cases place nop at the
beginning of the sequence.
The /F option has no effect on programs that make only near calls. Of the
high-level Microsoft languages, only tiny-, small-, and compact-model C
programs use near calls.
────────────────────────────────────────────────────────────────────────────
IMPORTANT
There is a small risk involved with the /F option: the linker may mistakenly
translate a byte in a code segment that happens to have the far-call opcode
(9A hexadecimal). If a program linked with /F inexplicably fails, then you
may want to try linking with this option off. Object files produced by
Microsoft high-level languages, however, should be safe from this problem
because relatively little immediate data is stored in code segments.
In general, assembly-language programs are also relatively safe for use with
the /F option, as long as they do not involve advanced system-level code,
such as might be found in operating systems or interrupt handlers.
────────────────────────────────────────────────────────────────────────────
5.4.8 /HE (View the Options List)
Option
/HE«LP»
The /HE option causes QLINK to display a list of its options on the screen.
This gives you a convenient reminder of the options.
When you use this option, QLINK ignores any other input you give and does
not create an executable file.
5.4.9 /HI (Place Executable in High Memory)
Option
/HI«GH»
The /HI option tells QLINK to place the executable file as high as possible
in memory. Without the /HI option, QLINK places the executable file as low
in memory as possible.
────────────────────────────────────────────────────────────────────────────
WARNING
This option should be used only with assembly-language programs.
────────────────────────────────────────────────────────────────────────────
5.4.10 /INC (Prepare for ILINK)
Option
/INC«REMENTAL»
Use this option to prepare a program for subsequent incremental linking with
ILINK. In incremental linking, only the object files that have changed since
the last link are linked. This process is much faster than performing
regular linking with QLINK, but it produces larger executable files. The use
of this option produces a .SYM file and a .ILK file, each containing extra
information needed by ILINK. This option requires that the file ILINKSTB.OVL
be in the current directory or the current path.
Incremental linking is possible only when small changes have been made to
object files. If large changes have been made, ILINK invokes QLINK to
perform a full link.
Incremental linking has no advantage over regular linking in the beginning
of the development process, when large amounts of code are being added. You
should use ILINK later in the development process, when only small changes
are being made to certain modules. When you have finished all changes and
are ready to produce the final .EXE file, you should use QLINK to produce
the smallest possible file.
Incremental linking is not compatible with the /T (see Section 5.4.30) or /E
(see Section 5.4.6) options.
5.4.10.1 Incremental Violations
ILINK can generate two kinds of errors: real errors and incremental
violations. Real errors are errors such as undefined symbols that cannot be
resolved by a full link. If ILINK detects a real error, it displays an error
message.
Incremental violations are caused by code changes that go beyond the scope
of incremental linking. When an incremental violation occurs, ILINK invokes
QLINK automatically. The following sections describe the incremental
violations.
Changing Libraries
An incremental violation occurs when a library changes. Furthermore, if an
altered module shares a code segment with a library, ILINK needs access to
the library as well as the altered module.
If you add a function, procedure, or subroutine call to a library that has
never been called before, ILINK invokes QLINK automatically.
Exceeding Code/Data Padding
An incremental violation occurs if two or more modules contribute to the
same physical segment and either module exceeds its padding. The padding
allows the module to increase in size by the specified number of bytes
before another full link is required. See Section 5.4.25, "/PADC" and
Section 5.4.26, "/PADD."
Moving or Deleting Data Symbols
An incremental violation occurs if a data symbol is moved or deleted. To add
new data symbols without requiring a full link, add the new symbols at the
end of all other data symbols in the module.
Deleting Code Symbols
You can move or add code symbols, but an incremental violation occurs if you
delete any code symbols from a module. Code symbols can be moved within a
module but cannot be moved between modules.
Adding Debugging Information
If you are using the CodeView debugger from the Microsoft C Professional
Development System version 6.0, you must include CodeView information in
your modules when you first specify /INC to prepare for incremental linking.
If you add the CodeView information later in the development process, an
incremental violation occurs the next time you use ILINK.
An incremental violation will also occur if you try to link object files
that include CodeView information for the Microsoft C Optimizing Compiler
version 5.1.
5.4.10.2 ILINK options
The options that ILINK accepts are described in the following list:
Option Action
────────────────────────────────────────────────────────────────────────────
/A Directs ILINK to check for changes in
the object files since the last linking
process.
/C Specifies case sensitivity.
/E "command" Specifies command to be executed if
incremental linking fails. The quotation
marks are required if there are any
embedded spaces in the command. The
default is /E "QLINK /INC".
/HE Provides help about the incremental
linker.
/I Specifies that ILINK should attempt only
an incremental link and not a regular
link. If the incremental link fails, a
fatal error follows the incremental
violation error.
/NOL Causes ILINK to suppress the sign-on
banner.
/V Directs ILINK to list all changed
modules.
/X Prevents ILINK from allocating memory
from an expanded memory manager if one
is present.
In very unusual cases, linking with /INC may cause the following warning to
be generated:
frame-relative fix-up, frame ignored near 'offset' in segment 'segment'
If this occurs, do not use this option or ILINK.
5.4.11 /INF (Display Linker-Process Information)
Option
/INF«ORMATION»
The /INF option tells the linker to display information about the linking
process, including the phase of linking and the names of the object files
being linked. Use this option if you want to determine the locations of the
object files being linked and the order in which they are linked.
Output from this option is sent to the standard error output.
Example
The following is a sample of the linker output when the /INF option is
specified on the QLINK command line:
**** PASS ONE ****
HSTGM.OBJ(hstgm.c)
**** LIBRARY SEARCH ****
\qc\lib\SLIBCE.LIB(CRT0)
\qc\lib\SLIBCE.LIB(CRT0DAT)
\qc\lib\SLIBCE.LIB(CRT0MSG)
\qc\lib\SLIBCE.LIB(CRT0FP)
\qc\lib\SLIBCE.LIB(CHKSTK)
\qc\lib\SLIBCE.LIB(CHKSUM)
.
.
.
**** ASSIGN ADDRESSES ****
**** PASS TWO ****
HSTGM.OBJ(hstgm.c)
\qc\lib\SLIBCE.LIB(CRT0)
\qc\lib\SLIBCE.LIB(CRT0DAT)
\qc\lib\SLIBCE.LIB(CRT0MSG)
\qc\lib\SLIBCE.LIB(CRT0FP)
\qc\lib\SLIBCE.LIB(CHKSTK)
\qc\lib\SLIBCE.LIB(CHKSUM)
**** WRITING EXECUTABLE ****
Segments 31
Groups 1
Bytes in symbol table 32784
5.4.12 /LI (Include Line Numbers in Map File)
Option
/LI«NENUMBERS»
You can include the line numbers and associated addresses of your source
program in the map file by using the /LI option. Use this option if you will
be debugging with the SYMDEB debugger included with earlier releases of
Microsoft language products.
Ordinarily, the map file does not contain line numbers. To produce a map
file with line numbers, you must give QLINK an object file (or files) with
line-number information. The /Zd option of the QCL command (see Section
4.3.36) directs the compiler to include line numbers in the object file. If
you give QLINK an object file without line-number information, the /LI
option has no effect.
The /LI option forces QLINK to create a map file even if you did not
explicitly tell the linker to create a map file. By default, QLINK gives the
file the same base name as the executable file plus the extension .MAP. You
can override the default name by specifying a new map file on the QLINK
command line or in response to the "List File" prompt.
5.4.13 /M (List Public Symbols)
Option
/M«AP»
You can list all public (global) symbols defined in the object file(s) by
using the /M option. When you invoke QLINK with the /M option, the map file
contains a list of all the symbols sorted by name and a list of all the
symbols sorted by address. If you do not use this option, the map file
contains only a list of segments.
When you use this option, the default for the mapfile field or "List File"
prompt response is no longer NUL. Instead, the default is a name that
combines the base name of the executable file with a .MAP extension. You can
still specify NUL in the mapfile field (which indicates that QLINK should
not generate a map file); if you do, the /M option has no effect.
────────────────────────────────────────────────────────────────────────────
NOTE
In earlier versions of QLINK, number specified the maximum number of public
symbols that QLINK could sort; the current version of QLINK sorts the
maximum number of symbols that can be sorted in available memory.
────────────────────────────────────────────────────────────────────────────
5.4.14 /NOD (Ignore Default Libraries)
Option
/NOD«EFAULTLIBRARYSEARCH» «:filename»
The /NOD option tells QLINK not to search any library specified in the
object file to resolve external references. If you specify filename, then
QLINK searches all libraries specified in the object file except for
filename.
In general, higher-level-language programs do not work correctly without a
stan-dard library. Therefore, if you use the /NOD option, you should
explicitly specify the name of a standard library in the libraries field.
5.4.15 /NOE (Ignore Extended Dictionary)
Option
/NOE«XTDICTIONARY»
The /NOE option prevents the linker from searching the extended dictionary,
which is an internal list of symbol locations that the linker maintains.
Normally, the linker consults this list to speed up library searches. The
/NOE option therefore slows down the linker. You often need this option when
a library symbol is redefined. Use /NOE if the linker issues the following
error message:
symbol name multiply defined
5.4.16 /NOF (Disable Far-Call Optimization)
Option
/NOF«ARCALLTRANSLATION»
Normally you don't need to specify this option because QLINK doesn't
ordinarily perform far-call optimization (translation). However, if an
environment variable such as LINK (or CL) turns on far-call translation
automatically, you can use /NOF to turn far-call translation off again.
5.4.17 /NOG (Preserve Compatibility)
Option
/NOG«ROUPASSOCIATION»
The /NOG option causes the linker to ignore group associations when
assigning addresses to data and code items. It is provided primarily for
compatibility with previous versions of the linker (versions 2.02 and
earlier) and early versions of Microsoft language compilers.
────────────────────────────────────────────────────────────────────────────
WARNING
This option should be used only with assembly-language programs.
────────────────────────────────────────────────────────────────────────────
5.4.18 /NOI (Employ Case Sensitivity)
Option
/NOI«GNORECASE»
By default, QLINK treats uppercase letters and lowercase letters as
equivalent. Thus ABC, abc, and Abc are considered the same name. When you
use the /NOI option, the linker distinguishes between uppercase letters and
lowercase letters and considers ABC, abc, and Abc to be three separate
names. Because names in some high-level languages are not case sensitive,
this option can have minimal importance. In Microsoft QuickC, however, case
is significant. If you plan to link your files from other high-level
languages with QuickC routines, you may need to use this option.
5.4.19 /NOL (Suppress Sign-On Banner)
Option
/NOL«OGO»
This option suppresses the QLINK sign-on banner display.
5.4.20 /NON (Order Segments without Nulls)
Option
/NON«ULLSDOSSEG»
This option arranges segments in the executable file in the same order they
are arranged by the /DO«SSEG» option, but it doesn't insert 16 null bytes at
the beginning of the _TEXT segment (if it is defined). The null bytes are
normally inserted by the /DO option to provide proper alignment.
The /NON option overrides the /DO option when both are used. Therefore, you
can use /NON to override the /DO comment record commonly found in standard
Microsoft libraries.
5.4.21 /NOP (Disable Segment Packing)
Option
/NOP«ACKCODE»
Normally you don't need to specify this option because QLINK doesn't
ordinarily perform code-segment packing. However, if an environment variable
such as LINK (or CL) turns on code-segment packing automatically, you can
use /NOP to turn segment packing off again.
5.4.22 /O (Set the Overlay Interrupt)
Option
/O«VERLAYINTERRUPT»:number
By default, the interrupt number used for passing control to overlays is 63
(3F hexadecimal). The /O option allows you to select a different interrupt
number.
The number can be a decimal number from 0 to 255, an octal number from octal
0 to octal 0377, or a hexadecimal number from hexadecimal 0 to hexadecimal
FF. Numbers that conflict with DOS interrupts can be used; however, their
use is not advised.
In general, you should not use /O with programs. The exception to this
guideline would be a program that uses overlays and spawns another program
that also uses overlays. In this case, each program should use a separate
overlay-interrupt number, meaning that at least one of the programs should
be compiled with /O.
5.4.23 /PACKC (Pack Contiguous Segments)
Option
/PACKC«ODE»«:number»
The /PACKC option affects code segments only in medium- and large-model
programs. It should be used with the /F option. You don't need to understand
the details of the /PACKC option in order to use it. You only need to know
that this option, used in conjunction with /F, produces slightly faster and
more compact code. The packing of code segments provides more opportunities
for far-call optimization, which is enabled with /F. The /PACKC option is
off by default; if on, it can be turned off with the /NOP option.
The /PACKC option directs the linker to group neighboring code segments.
Segments in the same group are assigned the same segment address; the offset
addresses of items are adjusted upward accordingly. In other words, the
/PACKC option does not change the physical address of any items.
The number field specifies the maximum size of groups formed by /PACKC. The
linker stops adding segments to a group as soon as it cannot add another
segment without exceeding number. At that point, the linker starts forming a
new group. The default for number is 65,530.
You can safely use /PACKC with programs developed with the QuickC compiler.
The /PACKC option, however, should not be used with assembly programs that
make assumptions about the relative order of code segments. For example, the
following assembly code attempts to calculate the distance between CSEG1 and
CSEG2. This code would produce incorrect results when used with /PACKC
because /PACKC causes the two segments to share the same segment address.
Therefore, the procedure would always return 0.
CSEG1 SEGMENT PARA PUBLIC 'CODE'
.
.
.
CSEG1 ENDS
CSEG2 SEGMENT PARA PUBLIC 'CODE'
ASSUME cs:CSEG2
; Return the length of CSEG1 in AX.
codsize PROC NEAR
mov ax,CSEG2 ; Load para address of CSEG1
sub ax,CSEG1 ; Load para address of CSEG2
mov cx,4 ; Load count, and convert
shl ax,cl ; distance from paragraphs
; to bytes
codsize ENDP
CSEG2 ENDS
5.4.24 /PACKD (Pack Contiguous Data)
Option
/PACKD«ATA»«:number»
The /PACKD option tells QLINK to group neighboring data segments. It works
like the code packing option (/PACKC) except that it packs data segments.
Use this option if your program uses a large number of very small data
segments, since it combines them and reduces the system overhead required
for using them. You should use this option if you use the compact or large
memory models.
The number field specifies the maximum size of a data segment grouped by
/PACKD. If you omit number, QLINK uses the default value of 65,536. QLINK
stops adding segments to a group as soon as it cannot add another segment
without exceeding number. At this point, QLINK forms a new group.
5.4.25 /PADC (Pad Code Segments)
Option
/PADC«ODE»:padsize
The /PADC option adds filler bytes to the end of each code module, in
preparation for subsequent incremental linking with ILINK. The padsize field
specifies the number of filler bytes. You can specify padsize in decimal,
octal, or hexadecimal format. This option and the related /PADD option are
used in conjunction with incremental linking (see Section 5.4.10).
These filler bytes provide space for expansion if ILINK updates the module
later. If the updates involve increasing the amount of code, ILINK uses the
space occupied by the filler bytes, instead of resizing the entire .EXE
file. If the module outgrows the space available, an incremental violation
occurs, and ILINK invokes QLINK to perform a full link. You can use code
padding with small-, compact-, and mixed-model programs.
If you don't specify the /PADC option, QLINK doesn't add any bytes to the
code segment. The optimum amount of padding to specify depends on how much
your code changes from one link to the next. If you expect to add only a
little code, choose a relatively small amount of padding (32 to 64 bytes).
If ILINK issues the message
padding exceeded
and performs a full link more often than desired, increase the padding size.
Remember that the total size of a code segment, including padding bytes,
cannot exceed 64K.
5.4.26 /PADD (Pad Data Segments)
Option
/PADD«ATA»:padsize
The /PADD option adds filler bytes to the end of each code module, in
preparation for incremental linking with ILINK later. The padsize field
specifies the number of filler bytes. You can specify padsize in decimal,
octal, or hexadecimal format. This option and the related /PADC option are
used in conjunction with incremental linking (see Section 5.4.10).
These filler bytes provide space for expansion if ILINK updates the module
later. If the updates involve increasing the amount of data, ILINK uses the
space occupied by the filler bytes, instead of resizing the entire .EXE
file. If the module outgrows the space available, an incremental violation
occurs and ILINK invokes QLINK to perform a full link.
QLINK normally adds 16 filler bytes. This amount of padding should be
sufficient in most cases, since public variables are added less frequently
than code. If ILINK issues the message
padding exceeded
and performs a full link more often than desired, increase the padding size.
Remember that the total size of a data segment, including padding bytes,
cannot exceed 64K.
5.4.27 /PAU (Pause during Linking)
Option
/PAU«SE»
The /PAU option tells QLINK to pause before it writes the executable (.EXE)
file to disk. Use this option if you want to create the executable file on
its own removable (floppy) disk. Without the /PAU option, QLINK performs the
linking session from beginning to end without stopping.
If you specify the /PAU option, QLINK displays the following message before
it creates the file:
About to generate .EXE file
Change diskette in drive letter and press <ENTER>
The letter corresponds to the current drive. QLINK resumes processing when
you press ENTER.
────────────────────────────────────────────────────────────────────────────
NOTE
Do not remove the disk that will receive the listing file or the disk used
for the temporary file.
────────────────────────────────────────────────────────────────────────────
Depending on how much memory is available, QLINK may create a temporary disk
file during processing (see Section 5.3, "QLINK Memory Requirements") and
display the following message:
Temporary file tempfile has been created.
Do not change diskette in drive, letter
If QLINK creates the file on the disk you plan to swap, press CTRL+C to
terminate the QLINK session. Rearrange your files so that the temporary file
and the executable file can be written to the same disk, then try linking
again.
5.4.28 /SE (Set Maximum Number of Segments)
Option
/SE«GMENTS»:number
The /SE option controls the number of segments that the linker allows a
program to have. The default is 128, but you can set number to any value
(decimal, octal, or hexadecimal) in the range 1-3,072 (decimal).
For each segment, the linker must allocate some space to keep track of
segment information. By using a relatively low segment limit as a default
(128), the linker is able to link faster and allocate less storage space.
When you set the segment limit higher than 128, the linker allocates
additional space for segment information. This option allows you to raise
the segment limit for programs with a large number of segments. For programs
with fewer than 128 segments, you can keep the storage requirements of the
linker at the lowest level possible by setting number to reflect the actual
number of segments in the program. If the number of segments allocated is
too high for the amount of memory available to the linker, QLINK issues the
following error message:
segment limit set too high
If this occurs, relink the object files, specifying a lower segment limit.
5.4.29 /ST (Set Stack Size)
Option
/ST«ACK»:number
The /ST option allows you to specify the size of the stack for your program.
The number is any positive value (decimal, octal, or hexadecimal) up to
65,535 (decimal). It represents the size, in bytes, of the stack. If you do
not use this option, the stack size is 2K.
If your program returns a stack-overflow message, you may need to increase
the size of the stack. In contrast, if your program uses the stack very
little, you can save some space by decreasing the stack size.
5.4.30 /T (Create a .COM File)
Option
/T«INY»
The /T option causes QLINK to create a .COM file instead of a .EXE file. It
can be used for programs that use the tiny memory model. The result is the
same as if you had linked a .EXE file from a tiny-model program, and then
used the EXE2BIN program to convert it to a .COM file. (See The MS-DOS
Programmer's Reference Manual for more information on .COM files and the
EXE2BIN program.)
When you use the /T option, the linker normally produces an output file with
the .COM extension. If you specify a file name with a different extension,
the linker applies the extension you specify. Note that the "Run File"
prompt shows the .EXE extension if you have not yet given the /T option.
After you give the option, the linker issues a warning message that the
extension of the output file is .COM.
Not every program can be linked using .COM format. When you specify the /T
option, QLINK automatically sets the /F option to optimize far calls; this
provides the best chance that a .COM format file can be generated.
The following restrictions apply to programs written for the .COM format:
■ The program must consist of only one physical segment. If you have
written an assembly-language program, you can declare more than one
segment. However, the segments must be in the same group.
■ The program cannot perform load-time relocations, and therefore cannot
have any far-segment references. Specifically, segment addresses
cannot be used as immediate data for instructions. You cannot, for
example, use the instruction
mov ax, CODESEG
The linker issues an error if it detects such references.
When you give the /CO option in combination with /T, QLINK creates a
separate file with debugger information rather than embedding debugger
information in the .COM file. QLINK gives this file the base name of the
.COM file plus the .DBG extension, and places it in the current directory.
The /T option is incompatible with the /INC option.
────────────────────────────────────────────────────────────────────────────
NOTE
This option was called the /BI«NARY» option in previous versions of the
linker included with QuickC.
────────────────────────────────────────────────────────────────────────────
5.5 Linker Operation
QLINK performs the following steps to combine object files and produce an
executable file:
1. Reads the object files submitted
2. Searches the given libraries, if necessary, to resolve external
references
3. Assigns addresses to segments
4. Assigns addresses to public symbols
5. Reads code and data in the segments
6. Reads all relocation references in object files
7. Performs fixups
8. Outputs an executable file (executable image and relocation
information)
Steps 5, 6, and 7 are performed concurrently: in other words, QLINK moves
back and forth between these steps before it progresses to step 8.
The "executable image" contains the code and data that constitute the
executable file. The "relocation information" is a list of references,
relative to the start of the program. The references change when the
executable image is loaded into memory and an actual address for the entry
point is assigned.
The following sections explain the process QLINK uses to concatenate
segments and resolve references to items in memory.
5.5.1 Alignment of Segments
QLINK uses a segment's alignment type to set the starting address for the
segment. The alignment types are BYTE, WORD, PARA, and PAGE. These
correspond to starting addresses at byte, word, paragraph, and page
boundaries, representing addresses that are multiples of 1, 2, 16, and 256,
respectively. The default alignment is PARA.
When QLINK encounters a segment, it checks the alignment type before copying
the segment to the executable file. If the alignment is WORD, PARA, or PAGE,
QLINK checks the executable image to see if the last byte copied ends on the
appropriate boundary. If not, QLINK pads the image with null bytes.
5.5.2 Frame Number
QLINK computes a starting address for each segment in the program. The
starting address is based on the segment's alignment and the sizes of the
segments already copied to the executable file (as described in the previous
section). The starting address consists of an offset and a "canonical frame
number." The canonical frame number specifies the address of the first
paragraph in memory that contains one or more bytes of the segment. (A
paragraph is 16 bytes of memory; therefore, to compute a physical location
in memory, multiply the frame number by 16 and add the offset.) The offset
is the number of bytes from the start of the paragraph to the first byte in
the segment. For BYTE and WORD alignments, the offset may be nonzero. The
offset is always zero for PARA and PAGE alignments. (An offset of zero means
that the physical location is an exact multiple of 16.)
You can find the frame number for each segment in the map file created by
QLINK. The first four digits of the segment's start address give the frame
number in hexadecimal. For example, a start address of 0C0A6 indicates the
frame number 0C0A.
5.5.3 Order of Segments
QLINK copies segments to the executable file in the same order that it
encounters them in the object files. This order is maintained throughout the
program unless QLINK encounters two or more segments that have the same
class name. Segments having identical segment names are copied as a
contiguous block to the executable file.
The /DO option may change the way in which segments are ordered (see Section
5.4.4).
5.5.4 Combined Segments
QLINK uses combine types to determine whether two or more segments that
share the same segment name should be combined into one large segment. The
valid combine types are PUBLIC, STACK, COMMON, and PRIVATE.
If a segment has combine type PUBLIC, QLINK automatically combines it with
any other segments that have the same name and belong to the same class.
When QLINK combines segments, it ensures that the segments are contiguous
and that all addresses in the segments can be accessed using an offset from
the same frame address. The result is the same as if the segment were
defined as a whole in the source file.
QLINK preserves each individual segment's alignment type. This means that
even though the segments belong to a single large segment, the code and data
in the segments do not lose their original alignment. If the combined
segments exceed 64K, QLINK displays an error message.
If a segment has combine type STACK, QLINK carries out the same combine
operation as for PUBLIC segments. The only exception is that STACK segments
cause QLINK to copy an initial stack-pointer value to the executable file.
This stack-pointer value is the offset to the end of the first stack segment
(or combined stack segment) encountered.
If a segment has combine type COMMON, QLINK automatically combines it with
any other segments that have the same name and belong to the same class.
When QLINK combines COMMON segments, however, it places the start of each
segment at the same address, creating a series of overlapping segments. The
result is a single segment no larger than the largest segment combined.
A segment has combine type PRIVATE only if no explicit combine type is
defined for it in the source file. QLINK does not combine private segments.
5.5.5 Groups
Groups allow segments to be addressed relative to the same frame address.
When QLINK encounters a group, it adjusts all memory references to items in
the group so that they are relative to the same frame address.
Segments in a group do not have to be contiguous, belong to the same class,
or have the same combine type. The only requirement is that all segments in
the group fit within 64K.
Groups do not affect the order in which the segments are loaded. Unless you
use class names and enter object files in the right order, there is no
guarantee that the segments will be contiguous. In fact, QLINK may place
segments that do not belong to the group in the same 64K of memory. QLINK
does not explicitly check whether all the segments in a group fit within 64K
of memory; however, QLINK is likely to encounter a fixup-overflow error if
they do not.
5.5.6 Fixups
Once the linker knows the starting address of each segment in the program
and has established all segment combinations and groups, QLINK can "fix up"
any unresolved references to labels and variables. To fix up unresolved
references, QLINK computes the appropriate offset and segment address and
replaces the temporary values generated by the assembler with the new
values.
QLINK carries out fixups for the types of references shown in Table 5.1.
The size of the value to be computed depends on the type of reference. If
QLINK discovers an error in the anticipated size of a reference, it displays
a fixupoverflow message. This can happen, for example, if a program attempts
to use a 16-bit offset to reach an instruction that is more than 64K away.
It can also occur if all segments in a group do not fit within a single 64K
block of memory.
5.6 Using Overlays
You can direct QLINK to create an overlaid version of a program. In an
overlaid version of a program, specified parts of the program (overlays) are
loaded only if and when they are needed. These parts share the same space in
memory. Only code is overlaid; data are never overlaid. Programs that use
overlays usually require less memory, but they run more slowly because of
the time needed to read and reread the code from disk into memory.
Table 5.1 QLINK Fixups
╓┌──────────────────────┌─────────────────────────┌──────────────────────────╖
Type Location of Reference QLINK Action
────────────────────────────────────────────────────────────────────────────
Short In JMP instructions that Computes a signed,
attempt to pass control eight-bit number for the
to labeled instructions reference, and displays
in the same segment or an error message if the
group. The target target instruction
instruction must be no belongs to a different
more than 128 bytes from segment or group (has a
the point of reference. different frame address),
or if the target is more
than 128 bytes away in
either
direction.
Near self-relative In instructions that Computes a 16-bit offset
access data relative to for the reference and
the same segment or displays an error if the
group. data are not in the same
segment or group.
Type Location of Reference QLINK Action
────────────────────────────────────────────────────────────────────────────
Near segment-relative In instructions that Computes a 16-bit offset
attempt to access data for the reference, and
in a specified segment displays an error message
or group, or relative to if the offset of the
a specified segment target within the
register. specified frame is
greater than 64K or less
than 0, or if the begin-
ning of the canonical
frame of the target is
not addressable.
Long In CALL instructions Computes a 16-bit frame
that attempt to access address and 16-bit offset
an instruction in for this reference, and
another segment or group. displays an error message
if the computed offset is
greater than 64K or less
Type Location of Reference QLINK Action
────────────────────────────────────────────────────────────────────────────
greater than 64K or less
than 0, or if the begin-
ning of the canonical
frame of the target is
not addressable.
────────────────────────────────────────────────────────────────────────────
You specify overlays by enclosing them in parentheses in the list of object
files that you submit to the linker. Each module in parentheses represents
one overlay. For example, you could give the following object-file list in
the objfiles field of the QLINK command line:
a + (b+c) + (e+f) + g + (i)
In this example, the modules (b+c), (e+f), and (i) are overlays. The
remaining modules, and any drawn from the run-time libraries, constitute the
resident part (or root) of your program. Overlays are loaded into the same
region of memory, so only one can be resident at a time. Duplicate names in
different overlays are not supported, so each module can appear only once in
a program.
The linker replaces calls from the root to an overlay and from an overlay to
another overlay with an interrupt (followed by the module identifier and
offset). By default, the interrupt number is 63 (3F hexadecimal). You can
use the /O option of the QLINK command to change the interrupt number.
You can use the CodeView debugger with overlaid modules. In fact, in the
case of large programs, you may need to use overlays to leave sufficient
room for the debugger to operate. However, the QuickC debugger cannot debug
overlaid modules.
5.6.1 Restrictions on Overlays
You can overlay only modules to which control is transferred and returned by
a standard 8086 long (32-bit) call/return instruction. Therefore, because
calls to subroutines modified with the near attribute are short (16-bit)
calls, you cannot overlay modules containing near subroutines if other
modules call those subroutines. You cannot use long jumps with the longjmp
library function. Also, the linker does not produce overlay modules that can
be called indirectly through function pointers. When a function is called
through a pointer, the called function must be in the same overlay or root.
5.6.2 Overlay-Manager Prompts
The overlay manager is part of the language's run-time library. If you
specify overlays during linking, the code for the overlay manager is
automatically linked with the other modules of your program. Even with
overlays, the linker produces only one .EXE file. At run time, the overlay
manager opens the .EXE file each time it needs to extract new overlay
modules. The overlay manager first searches for the file in the current
directory; then, if it does not find the file, the manager searches the
directories listed in the PATH environment variable. When it finds the file,
the overlay manager extracts the overlay modules specified by the root
program. If the overlay manager cannot find an overlay file when needed, it
prompts you for the file name.
For example, assume that an executable program called PAYROLL.EXE uses
overlays and does not exist in either the current directory or the
directories specified by PATH. If you run PAYROLL.EXE (by entering a
complete path specification), the overlay manager displays the following
message when it attempts to load overlay files:
Cannot find PAYROLL.EXE
Please enter new program spec:
You can then enter the drive or directory, or both, where PAYROLL.EXE is
located. For example, if the file is located in directory \EMPLOYEE\DATA\
on drive B, you could enter B:\EMPLOYEE\DATA\ or you could enter
\EMPLOYEE\DATA\ if the current drive is B.
If you later remove the disk in drive B and the overlay manager needs to
access the overlay again, it does not find PAYROLL.EXE and displays the
following message:
Please insert diskette containing B:\EMPLOYEE\DATA\PAYROLL.EXE
in drive B: and strike any key when ready.
After reading the overlay file from the disk, the overlay manager displays
the following message:
Please restore the original diskette.
Strike any key when ready.
Execution of the program then continues.
Chapter 6 LIB
────────────────────────────────────────────────────────────────────────────
The Microsoft Library Manager (LIB) helps you create and maintain objectcode
libraries. An object-code library is a collection of separately compiled or
assembled object files combined into a single file. Object-code libraries
provide a convenient source of commonly used routines. A program that calls
library routines is linked with the library to produce the executable file.
Only the necessary routines, not all library routines, are linked into the
executable file.
Library files are usually identified by their .LIB extension, although other
extensions are allowed. In addition to accepting DOS object files and
library files, LIB can read the contents of 286 XENIX(R) archives and
Intel-style libraries and combine their contents with DOS libraries.
You can use the LIB utility to
■ Create a new library file
■ Add object files or the contents of a library to an existing library
■ Delete library modules
■ Replace library modules
■ Copy library modules to object files
6.1 Invoking LIB
To invoke LIB, type the LIB command on the DOS command line. You can specify
the input required in one of three ways:
1. Type it on the command line.
2. Respond to prompts.
3. Specify a response file (a file containing responses to prompts).
The three sections below present the three methods of invoking LIB. Section
6.1.1 describes the input fields in detail and is relevant to all three
methods.
To terminate the library session at any time and return to DOS, press
CTRL+C.
6.1.1 Command Line
You can start LIB and specify all the necessary input from the command line.
In this case, the LIB command line has the following form:
LIB oldlibrary «options» «commands» «,«listfile» «,« newlibrary» » » «;»
The individual components of the command line are discussed in the sections
that follow.
Type a semicolon (;) anywhere a comma appears to tell LIB to use the default
responses for the remaining fields. The semicolon should be the last
character on the command line.
Typing a semicolon after the oldlibrary field causes LIB to perform a
consistency check on the library─no other action is performed. LIB displays
any consistency errors it finds and returns to the operating-system level.
Examples
LIB GRAPHIC;
The example above causes LIB to perform a consistency check on the library
file GRAPHIC.LIB.
LIB GRAPHIC ,SYMBOLS.LST;
This example tells LIB to perform a consistency check on the library file
GRAPHIC.LIB and to create SYMBOLS.LST, a cross-reference-listing file.
LIB GRAPHIC +STAR;
The example above uses the add-command symbol (+) to instruct LIB to add the
file STAR to the library GRAPHIC.LIB. The semicolon at the end of the
command line causes LIB to use the default responses for the remaining
fields. As a result, no listing file is created and the original library
file is renamed GRAPHIC.BAK. The modified library is GRAPHIC.LIB.
LIB GRAPHIC -*JUNK *STAR, ,SHOW
This last example instructs LIB to move the module JUNK from the library
GRAPHIC.LIB to an object file called JUNK.OBJ. The module JUNK is removed
from the library in the process. The module STAR is copied from the library
to an object file called STAR.OBJ; the module remains in the library. No
cross-reference-listing file is produced. The revised library is called
SHOW.LIB. It contains all the modules in GRAPHIC.LIB except JUNK, which was
removed by using the move-command symbol (-*). The original library,
GRAPHIC.LIB, remains unchanged.
6.1.1.1 Library File
Use the oldlibrary field to specify the name of the library to be modified.
The LIB utility assumes that the file-name extension is .LIB, since this is
usually the case. If your library file has the .LIB extension, you can omit
it. Otherwise, include the extension. You must give LIB the path name of a
library file if it is in another directory or on another disk.
There is no default for the oldlibrary field. This field is required and LIB
issues an error message if you do not give a file name.
Consistency check
If you type a library name and follow it immediately with a semicolon (;),
LIB performs only a consistency check on the given library. A consistency
check tells you whether all the modules in the library are in usable form.
No changes are made to the library. It is usually not necessary to perform
consistency checks because LIB automatically checks object files for
consistency before adding them to the library. The LIB utility prints a
message if it finds an invalid object module; no message appears if all
modules are intact.
6.1.1.2 LIB Options
LIB has five options. Specify options on the command line following the
required library-file name and preceding any commands.
Option
/I«GNORECASE»
The /I option tells LIB to ignore case when comparing symbols, which is the
default. Use this option when you are combining a library that is case
sensitive (created with the /NOI option) with others that are not case
sensitive. The resulting library will not be case sensitive. The /NOI option
is described later in this section.
Option
/NOE«XTDICTIONARY»
The /NOE option tells LIB not to generate an extended dictionary. The
extended dictionary is an extra part of the library that helps the linker
process libraries faster.
Use the /NOE option if you get either the error message insufficient memory
or no more virtual memory, or if the extended dictionary causes problems
with the linker. See Section 5.4.15 for more information on how the linker
uses the extended dictionary.
Option
/NOI«GNORECASE»
The /NOI option tells LIB not to ignore case when comparing symbols; that
is, /NOI makes LIB case sensitive. By default, LIB ignores case. Using this
option allows symbols that are the same except for case, such as Spline and
SPLINE, to be put in the same library.
Note that when you create a library with the /NOI option, LIB "marks" the
library internally to indicate that /NOI is in effect. Earlier versions of
LIB did not mark libraries in this way. If you combine multiple libraries
and any one of them is marked /NOI, then /NOI is assumed to be in effect for
the output library.
Option
/NOL«OGO»
The /NOL option suppresses the display of the sign-on banner when LIB is
first invoked. This option can be used for batch file operation.
Option
/PA«GESIZE»:number
The /PA option specifies the library-page size of a new library or changes
the library-page size of an existing library. The number specifies the new
page size. It must be an integer value representing a power of 2 between the
values 16 and 32,768.
A library's page size affects the alignment of modules stored in the
library. Modules in the library are always aligned to start at a position
that is a multiple of the page size (in bytes) from the beginning of the
file. The default page size for a new library is 16 bytes; for an existing
library, the default is its current page size. Because of the indexing
technique used by the LIB utility, a library with a large page size can hold
more modules than a library with a smaller page size. For each module in the
library, however, an average of number/2 bytes of storage space is wasted.
In most cases, a small page size is advantageous; you should use a small
page size unless you need to put a very large number of modules in a
library.
Another consequence of the indexing technique is that the page size
determines the maximum possible size of the library file. Specifically, this
limit is number * 65,536. For example, /PA:16 means that the library file
must be smaller than 1 megabyte (16 * 65,536 bytes).
6.1.1.3 Commands
The commands field allows you to specify the command symbols for
manipulating modules. In this field, type a command symbol followed
immediately by a module name or an object-file name. The command symbols are
the following:
Symbol Action
────────────────────────────────────────────────────────────────────────────
+ Adds an object file or library to the
library
- Deletes a module from the library
- + Replaces a module in the library
* Copies a module from the library to an
object file
- * Moves a module (copies the module and
then
deletes it)
Note that LIB does not process commands in left-to-right order; it uses its
own precedence rules for processing, as described in Section 6.2. You can
specify more than one operation in the commands field, in any order. LIB
makes no changes to oldlibrary if you leave this field blank.
6.1.1.4 Cross-Reference Listing File
The listfile field allows you to specify a file name for a cross-reference
listing file. You can give the listing file any name and any extension. To
create it outside your current directory, supply a path specification. Note
that the LIB utility does not assume any defaults for this field on the
command line. If you do not specify a name for the file, the file is not
created.
A cross-reference listing file contains the following two lists:
1. An alphabetical list of all public symbols in the library.
Each symbol name is followed by the name of the module in which it is
defined. The example output below shows that the public symbol ADD
is contained in the module junk and the public symbols CALC, MAKE,
and ROLL are contained in the module dice:
ADD...............junk CALC..............dice
MAKE..............dice ROLL..............dice
2. A list of the modules in the library.
Under each module name is an alphabetical listing of the public
symbols defined in that module. The example output below shows that
the module dice contains the public symbols CALC, MAKE, and ROLL
and the module junk contains the public symbol ADD:
dice Offset: 00000010H Code and data size: 621H
CALC MAKE ROLL
junk Offset: 00000bc0H Code and data size: 118H
ADD
6.1.1.5 Output Library
If you specify a name in the newlibrary field, LIB gives this name to the
modified library it creates. You need not give a name unless you specify
commands to change the library.
If you leave this field blank, the original library is renamed with a .BAK
extension, and the modified library receives the original name.
6.1.2 Prompts
If you want to respond to individual prompts to give input to LIB, start the
LIB utility at the DOS command level by typing LIB. The library manager
prompts you for the input it needs by displaying the following four
messages, one at a time:
Library name:
Operations:
List file:
Output library:
LIB waits for you to respond to each prompt before printing the next prompt.
If you notice that you have entered an incorrect response to a previous
prompt, press CTRL+C to exit LIB and begin again.
The responses to the LIB command prompts correspond to fields on the LIB
command line (Section 6.1.1), as follows:
Prompt Corresponding Command-Line Field
────────────────────────────────────────────────────────────────────────────
"Library name" The oldlibrary field and the options. To
perform a consistency check on the
library, type a semicolon (;)
immediately after the library name.
If the library you name does not exist,,
LIB displays the following prompt:
Library does not exist. Create? (y/n)
Type y to create the library file, or
n to terminate the session. This
message does not appear if a command, a
comma, or a semicolon immediately
follows the library name.
"Operations" The commands field.
"List file" The listfile field.
"Output library" The newlibrary field. This prompt
appears only if you specify at least one
operation at the "Operations" prompt.
Extending lines
If you have many operations to perform during a library session, use the
ampersand symbol (&) to extend the operations line. Type the symbol after
the name of an object module or object file; do not put the ampersand
between a command symbol and a name.
The ampersand causes LIB to display the "Operations" prompt again, allowing
you to specify more operations.
Default responses
Press ENTER to choose the default response for the current prompt. Type a
semicolon (;) and press ENTER after any response except "Library name" to
select default responses for all remaining prompts.
The following list shows the defaults for LIB prompts:
Prompt Default
────────────────────────────────────────────────────────────────────────────
"Operations" No operation; no change to library file
"List file" NULL; tells LIB not to create a listing
file
"Output library" Current library name
6.1.3 Response File
Using a response file lets you conduct the library session without typing
responses to prompts at the keyboard. To run LIB with a response file, you
must first create the response file. Then type the following at the DOS
command line:
LIB @responsefile
The responsefile is the name of a response file. Specify a path name if the
response file is not in the current directory.
You can also type @responsefile at any position on a command line or after
any of the prompts. The input from the response file is treated exactly as
if it had been entered on a command line or after the prompts. A new-line
character in the response file is treated the same as pressing the ENTER key
in response to a prompt.
A response file uses one text line for each prompt. Responses must appear in
the same order as the command prompts appear. Use command symbols in the
response file the same way you would use responses typed on the keyboard.
You can type an ampersand (&) at the end of the response to the "Operations"
prompt, for instance, and continue typing operations on the next line. This
mechanism is illustrated in Figure 6.1.
(This figure may be found in the printed book.)
When you run LIB with a response file, the prompts are displayed with the
responses. If the response file does not contain responses for all the
prompts, LIB uses the default responses.
Example
GRAPHIC
+CIRCLE+WAVE-WAVE*FLASH
GRAPHIC.LST
Assume that a response file named RESPONSE in the directory B:\ PROJ
contains the above lines and you invoke LIB with the command shown below:
LIB @B:\PROJ\RESPONSE
LIB deletes the module WAVE from the library GRAPHIC.LIB, copies the module
FLASH into an object file named FLASH.OBJ, and appends the object files
CIRCLE.OBJ and WAVE.OBJ as the last two modules in the library. LIB also
creates a cross-reference listing file named GRAPHIC.LST.
6.2 LIB Commands
The LIB utility can perform a number of library-management functions,
including creating a library file, adding an object file as a module to a
library, deleting modules from a library, replacing a module in the library
file, copying a module to a separate object file, and moving a module out of
a library and into an object file.
For each library session, LIB reads and interprets commands in the order
listed below. It determines whether a new library is being created or an
existing library is being examined or modified.
1. LIB processes any deletion and move commands.
LIB does not actually delete modules from the existing file. Instead,
it marks the selected modules for deletion, creates a new library
file, and copies only the modules not marked for deletion into the new
library file.
2. LIB processes any addition commands.
Like deletions, additions are not performed on the original library
file. Instead, the additional modules are appended to the new library
file. (If there were no deletion or move commands, a new library file
would be created in the addition stage by copying the original library
file.)
As the LIB utility carries out these commands, it reads the object modules
in the library, checks them for validity, and gathers the information
necessary to build a library index and a listing file. When you link a
library with other object files, the linker uses the library index to search
the library.
LIB never makes changes to the original library; it copies the library and
makes changes to the copy. Therefore, if you press CTRL+C to terminate the
session, you do not lose your original library. Therefore, when you run LIB,
make sure your disk has enough space for both the original library file and
the copy.
Once an object file is incorporated into a library, it becomes an object
module. The LIB utility makes a distinction between object files and object
modules: an object file exists as an independent file while an object module
is part of a library file. An object file has a full path name, including a
drive designation, directory path name, and file-name extension (usually
.OBJ). Object modules have only a name. For example, B:\RUN\SORT.OBJ is an
object-file name, while SORT is an object-module name.
6.2.1 Creating a Library File
To create a new library file, give the name of the library file you want to
create in the oldlibrary field of the command line or at the "Library name"
prompt. LIB supplies the .LIB extension.
If the name of the new library file is the same as the name of an existing
library file, LIB assumes that you want to change the existing file. If the
name of the new library file is the same as the name of a file that is not a
library, LIB issues an error message.
When you give the name of a file that does not currently exist, LIB displays
the following prompt:
Library does not exist. Create? (y/n)
Type y to create the file, or n to terminate the library session. This
message does not appear if the name is followed immediately by a command, a
comma, or a semicolon.
You can specify a page size for the library by specifying the /P option when
you create the library (see Section 6.1.1.2). The default page size is 16
bytes.
Once you have given the name of the new library file, you can insert object
modules into the library by using the add-command symbol (+).
6.2.2 Add Command (+)
Use the add-command symbol (+) to add an object module to a library. Give
the name of the object file to be added, without the .OBJ extension,
immediately following the plus sign.
LIB uses the base name of the object file as the name of the object module
in the library. For example, if the object file B:\CURSOR.OBJ is added to a
library file, the name of the corresponding object module is CURSOR.
Object modules are always added to the end of a library file.
Combining libraries
You can also use the plus sign to combine two libraries. When you give a
library name following the plus sign, a copy of the contents of that library
is added to the library file being modified. You must include the .LIB
extension when you give a library-file name. Otherwise, LIB uses the default
.OBJ extension when it looks for the file. If both libraries contain a
module with the same name, LIB ignores the second module of that name. For
information on replacing modules, see Section 6.2.4.
LIB adds the modules of the library to the end of the library being changed.
Note that the added library still exists as an independent library, since
LIB copies the modules without deleting them.
In addition to allowing DOS libraries as input, LIB also accepts 286 XENIX
archives and Intel-format libraries. Therefore, you can use LIB to convert
libraries from either of these formats to the DOS format.
Examples
LIB mainlib +flash;
This command adds the file FLASH.OBJ to the library MAINLIB.LIB.
LIB math +trig.lib;
The command above adds the contents of the library TRIG.LIB to the library
MATH.LIB. The library TRIG.LIB is unchanged after this command is executed.
6.2.3 Delete Command (-)
Use the delete-command symbol (-) to delete an object module from a library.
After the minus sign, give the name of the module to be deleted. Module
names do not have path names or extensions.
Example
LIB mainlib -flash;
The command shown above deletes the module flash from the library
MAINLIB.LIB.
6.2.4 Replace Command (- +)
Use the replace-command symbol (- +) to replace a module in a library.
Following the symbol, give the name of the module to be replaced. Module
names do not have path names or extensions.
To replace a module, LIB first deletes the existing module, then appends an
object file that has the same name as the module. The object file is assumed
to have the .OBJ extension and to reside in the current directory; if it
does not, give the object-file name with an explicit extension or path.
Example
LIB mainlib -+flash;
This command replaces the module flash in the MAINLIB.LIB library with the
contents of FLASH.OBJ from the current directory. Upon completion of this
command, the file FLASH.OBJ still exists, and the flash module is updated in
MAINLIB.LIB.
6.2.5 Copy Command (*)
Use the copy-command symbol (*) followed by a module name to copy a module
from the library into an object file of the same name. The module remains in
the library. When LIB copies the module to an object file, it adds the .OBJ
extension to the module name and places the file in the current directory.
Example
LIB mainlib *flash;
This command copies the module flash from the MAINLIB.LIB library to a file
called FLASH.OBJ in the current directory. Upon completion of this command,
MAINLIB.LIB still contains the module flash.
6.2.6 Move Command (- *)
Use the move-command symbol (-*) to move an object module from the library
file to an object file. This operation is equivalent to copying the module
to an object file, then deleting the module from the library.
Example
LIB mainlib -*flash;
This command moves the module flash from the MAINLIB.LIB library to a file
called FLASH.OBJ in the current directory. Upon completion of this command,
MAINLIB.LIB no longer contains the module flash.
Chapter 7 NMAKE
────────────────────────────────────────────────────────────────────────────
NMAKE (the Microsoft Program-Maintenance Utility) is a sophisticated command
processor that can save time and simplify project management. By determining
which project files depend on others, NMAKE can automatically execute the
commands needed to update your project when any project file has changed.
The advantage of using NMAKE over simple batch files is that NMAKE does only
what is needed. You don't waste time rebuilding files that are already
up-to-date. NMAKE also has advanced features, such as macros, that help you
manage complex projects.
7.1 Overview of NMAKE
NMAKE works by comparing the times and dates of two sets of files, which are
called targets and dependents. A target is normally a file that you want to
create, such as an executable file. A dependent is a file used to create a
target, such as a C source file.
When you run NMAKE, it reads a description file that you supply. The
description file consists of one or more blocks. Each block typically lists
a target, the target's dependents, and the command that builds the target.
NMAKE compares the date and time of the target to those of its dependents.
If any dependent has changed more recently than the target, NMAKE updates
the target by executing the command listed in the block.
NMAKE's main purpose is to help you update applications quickly and simply.
However, because it can execute any command, it is not limited to compiling
and linking. NMAKE can also make backups, move files, and do many other
project management tasks.
7.1.1 Using a Command Line to Invoke NMAKE
When you run NMAKE, you can supply the description-file name and other
arguments using the following syntax:
NMAKE «options» «macrodefinitions» «targets »
All of the command-line fields are optional. If you don't supply any
arguments, NMAKE looks for a default description file named MAKEFILE and
follows various other defaults that are described in this chapter.
The options field lists NMAKE options, which are described in Section 7.3,
"Command-Line Options." To specify the description file, specify the /F
option in this field.
The macrodefinitions field lists macro definitions, which allow you to
replace text in the description file. Macros are described in Section 7.2.3.
The targets field lists targets to build. If you do not list any targets,
NMAKE builds only the first target in the description file.
Example
NMAKE /S "program = sample" sort.exe search.exe
The command supplies four arguments: an option (/S), a macro definition
("program = sample"), and two target specifications (sort.exe search.exe).
Because the command does not specify a description file, NMAKE looks for the
default description file, MAKEFILE. The /S option tells NMAKE to suppress
the display of commands as they are executed. The macro definition performs
a text substitution throughout the description file, replacing every
instance of program with sample. The target specifications tell NMAKE to
update the targets SORT.EXE and SEARCH.EXE.
7.2 NMAKE Description Files
You must always supply NMAKE with a description file. In addition to
description blocks, which tell NMAKE how to build your project's target
files, the description file can contain comments, macros, inference rules,
and directives. This section describes all the elements of description
files.
7.2.1 Description Blocks
Description blocks form the heart of the description file. Figure 7.1
illustrates a typical NMAKE description block, including the three parts:
targets, dependents, and commands.
(This figure may be found in the printed book.)
A target is a file that you want to build.
The targets part of the description block lists one or more files to build.
The line that lists targets and dependents is called the dependency line.
The example in Figure 7.1 tells NMAKE to build a single target, MYAPP.EXE.
Although single targets are common, you can also list multiple targets;
separate each target name with a space. If the rightmost target name is one
character long, put a space between the name and the colon.
The target is normally a file, but it can also be a "pseudotarget," a name
that allows you to build groups of files or execute a group of commands. See
Section 7.2.6, "Pseudotargets."
A dependent is a file used to build a target.
The dependents part of the description block lists one or more files from
which the target is built. It is separated from the targets part by a colon.
The example in Figure 7.1 lists two dependents:
myapp.exe : myapp.obj another.obj
The example tells NMAKE to build the target MYAPP.EXE whenever MYAPP.OBJ, or
ANOTHER.OBJ has changed more recently than MYAPP.EXE.
If any dependents of a target are listed as targets in other description
blocks, NMAKE builds those files before it builds the original target.
Essentially, NMAKE evaluates a "dependency tree" for the entire description
file. It builds files in the order needed to update the original target,
never building a target until all files that depend on it are up-to-date.
The dependent list can also include a list of directories in which NMAKE
should search for dependents. The directory list is enclosed in curly braces
( {} ) and precedes the dependent list. NMAKE searches the current directory
first, then the directories you list:
forward.exe : {\src\alpha;d:\proj}pass.obj
In the line above, the target, FORWARD.EXE, has one dependent: PASS.OBJ. The
directory list specifies two directories:
{\src\alpha;d:\proj}
NMAKE begins searching for PASS.OBJ in the current directory. If it is not
found, NMAKE searches the \SRC\ALPHA directory, then the D:\PROJ directory.
If NMAKE cannot find a dependent in the current directory or a listed
directory, it looks for an inference rule that describes how to create the
dependent (see Section 7.2.4, "Inference Rules").
The commands part of a description block can contain one or more
commands.
The commands part of the description block lists the command(s) NMAKE should
use to build the target. This can be any command that you can execute from
the command line. The example in Fig 7.1 tells NMAKE to build MYAPP.EXE
using the following QLINK command:
QLINK /F /PACKC myapp another
Notice that the line above is indented. NMAKE uses indentation to
distinguish between the dependency line and command line. If the command
appears on a separate line, as here, it must be indented at least one space
or tab. The dependency line must not be indented (it cannot start with a
space or tab).
Many targets are built with a single command, but you can place more than
one command after the dependency line. A long command can span several lines
if each line ends with a backslash ( \ ).
You can also place the command at the end of the dependency line. Separate
the command from the rightmost dependent with a semicolon.
To use CD, CHDIR, or SET in a description block, place the command on a
separate line:
DIR
CD \mydir
7.2.1.1 Wild Cards
You can use DOS wild-card characters (* and ?) to specify target and
dependent file names. NMAKE expands wild cards in target names when it reads
the description file. It expands wild cards in the dependent names when it
builds the target. For example, the following description block compiles all
source files with the .C extension:
bondo.exe : *.c
CL *.c
7.2.1.2 Command Modifiers
Command modifiers provide extra control over the command listed in a
description block. They are special characters that appear in front of a
command. You can use more than one modifier for a single command. The
characters are listed in the following list:
Character Action
────────────────────────────────────────────────────────────────────────────
@(At sign) Prevents NMAKE from displaying the
command as it executes. In the example
below, NMAKE does not display the ECHO
command line:
sort.exe : sort.obj
@ECHO sorting
The output of the ECHO command appears
as usual.
- (Dash) Turns off error checking for the command.
If the dash is followed by a number,
NMAKE stops only if the error level
returned by the command is greater than
the number. In the following example, if
the program sample returns an error
code, NMAKE does not stop but continues
to execute commands:
light.lst : light.txt
-sample light.txt
! (Exclamation point) Executes the command for each dependent
file if the command uses the predefined
macros $? or $**. The $? macro refers to
all dependent files that are out-of-date
with respect to the target. The $**
macro refers to all dependent files in
the description block (see Section 7.2.3,
"Macros"). For example,
print:hop.asm skip.bas jump.c
!print $** lpt1:
generates the following commands:
print hop.asm lpt1:
print skip.bas lpt1:
print jump.c lpt1:
7.2.1.3 Using Control Characters as Literals
Occasionally, you may need to list a file name containing a character that
NMAKE uses as a control character. These characters are:
# ( ) $ ^ \ { } ! @ -
To use an NMAKE control character as a literal character, place a caret (^)
in front of it. For example, say that you define a macro that ends with a
backslash:
exepath=c:\bin\
The line above is intended to define a macro named exepath with the value
c:\bin\. But the second backslash causes unexpected results. Since the
back-slash is the NMAKE line-continuation character, the line actually
defines the macro exepath as c:\bin followed by whatever appears on the
next line of the description file. You can solve the problem by placing a
caret in front of the second backslash:
exepath=c:\bin^\
You can also use a caret to place a literal newline character in a
description file. This feature can be useful in macro definitions:
XYZ=abc^
def
NMAKE interprets the example as if you assigned the C-style string abc\ndef
to the XYZ macro. This effect differs from using the backslash ( \ ) to
continue a line. A newline character that follows a backslash is replaced
with a space.
Carets that precede noncontrol characters are ignored. The line
ign^ore : these ca^rets
is interpreted as
ignore : these carets
A caret that appears in quotation marks is treated as a literal caret
character.
7.2.1.4 Listing a Target in Multiple Description Blocks
You can specify more than one description block for the same target by
placing two colons (::) after the target. This feature can be useful for
building a complex target, such as a library, that contains components
created with different commands.
Examples
target.lib :: a.asm b.asm c.asm
CL a.asm b.asm c.asm
LIB target -+a.obj -+b.obj -+c.obj;
target.lib :: d.c e.c
CL /c d.c e.c
LIB target -+d.obj -+e.obj;
Both description blocks above update the library named TARGET.LIB. If any of
the assembly-language files have changed more recently than the library,
NMAKE executes the commands in the first block to assemble the source files
and update the library. Similarly, if any of the C-language files have
changed, NMAKE executes the second group of commands, which compile the C
files and update the library.
If you use a single colon in the example above, NMAKE issues an error
message. It is legal, however, to use single colons if commands are listed
in only one block. In this case, dependency lines are cumulative. For
example,
target: jump.bas
target: up.c
echo Building target...
is equivalent to
target: jump.bas up.c
echo Building target...
7.2.2 Comments
You can place comments in a description file by preceding them with a number
sign (#):
# This comment appears on its own line
huey.exe : huey.obj dewey.obj # Comment on the same line
link huey.obj dewey.obj;
A comment extends to the end of the line in which it appears. Command lines
cannot contain comments.
7.2.3 Macros
Macros allow you to do text replacements throughout the description file.
Macros offer a convenient way to replace a string in the description file
with another string. The text is automatically replaced each time you run
NMAKE. Macros are useful in a variety of tasks, including the following:
■ To create a standard description file for several projects. The macro
represents the file names used in commands. These file names are then
defined when you run NMAKE. When you switch to a different project,
you can change file names throughout the description file by changing
a single macro.
■ To control the options that NMAKE passes to the compiler or linker.
When you specify options in a macro, you can change options throughout
the description file in one easy step.
You can define your own macros or use predefined macros. This section begins
by describing user-defined macros.
7.2.3.1 User-Defined Macros
You can define a macro with:
macroname = string
The macroname can be any combination of letters, digits, and the underscore
( _ ) character. Macro names are case sensitive. NMAKE interprets MyMacro
and MYMACRO as different macro names.
The string can be any string, including a null string. For example,
command = QLINK
defines a macro named command and assigns it the string QLINK.
You can define macros in the description file or on the command line. In the
description file, you must define each macro on a separate line; the line
cannot start with a space or tab. The string can contain embedded spaces,
and NMAKE ignores spaces on either side of the equal sign. You do not need
to enclose string in quotation marks (if you do, they become part of the
string).
Slightly different rules apply when you define a macro on the command line,
because of the way that the command line handles spaces. You must enclose
string in quotation marks if it contains embedded spaces. No spaces can
surround the equal sign. You can also enclose the entire macro definition,
macroname and string, in quotation marks. For example,
NMAKE "program=sample"
defines the macro program, assigning it the value sample.
Once you have defined a macro, you can "undefine" it with the !UNDEF
directive (see Section 7.2.5, "Directives").
7.2.3.2 Invoking Macros
You invoke a macro by enclosing its name in parentheses preceded by a
dollar sign ($). (The parentheses are optional if macroname is one character
long.) For example, you can invoke the command macro defined above as
$(command)
When NMAKE runs, it replaces every occurrence of $(command) with QLINK.
The following description file defines and uses three macros:
program = sample
c = QLINK
options =
$(program).exe : $(program).obj
$c $(options) $(program).obj;
NMAKE interprets the description block as
sample.exe : sample.obj
QLINK sample.obj;
NMAKE replaces every occurrence of $(program) with sample, every instance
of $c with QLINK, and every instance of $(options) with a null string.
Because c is only one character long, you do not need to enclose it in
parentheses.
If you invoke a macro that is not defined, NMAKE treats the macro as a null
string.
Occasionally, you may need to use the dollar sign ($) as a literal
character. Use two dollar signs ($$), or precede one with a caret (^$).
7.2.3.3 Predefined Macros
NMAKE provides several predefined macros, which represent various file names
and commands. Predefined macros are useful in their own right, and they are
also employed in predefined inference rules, which are described later in
Section 7.2.4.3. NMAKE predefined macros are described in the following
list:
Macro Meaning
────────────────────────────────────────────────────────────────────────────
$@ The current target's full name.
$* The current target's base name (full
name minus the file extension).
$** The dependents of the current target.
$? The dependents that are out-of-date with
respect to the current target.
$$@ The target that NMAKE is currently
evaluating. You can use this macro only
to specify a dependent.
$< The dependent file that is out-of-date
with respect to the current target
(evaluated only for inference rules).
$(CC) The command to invoke the C compiler. By
default, $(CC) is predefined as CC = cl,
which invokes the optimizing compiler.
$(AS) The command that invokes the Microsoft
Macro
Assembler. NMAKE predefines this macro
as
AS = masm.
$(AFLAGS) The options for the assembler. By
default, this macro is set to the null
string. If redefined, it will be used by
the predefined inference rules.
$(CFLAGS) The options for the C compiler. By
default, this macro is set to the null
string. If redefined, it will be used by
the predefined inference rules.
$(MAKE) The name with which the NMAKE utility is
invoked. This macro is used to invoke
NMAKE recursively. It causes the line on
which it appears to be executed even if
the /N option is on. You can redefine
this macro if you want to execute
another
program.
The $(MAKE) macro is useful for building
different versions of a program. The
following description file invokes NMAKE
recursively to build targets in the
VERS1 and VERS2 directories:
all :vers1 vers2
vers1 :
cd vers1
$(MAKE)
cd . .
vers2 :
cd vers2
$(MAKE)
cd . .
The example changes to the VERS1
directory, then invokes NMAKE
recursively, causing NMAKE to process
the file MAKEFILE in that directory.
Then it changes to the VERS2 directory
and invokes NMAKE again, processing the
file MAKEFILE in that directory.
Deeply recursive build procedures can
exhaust NMAKE's run-time stack, causing
a run-time error. To eliminate the error,
use the EXEHDR utility to increase
NMAKE's run-time stack. The following
command, for example, gives NMAKE.EXE a
stack size of 16,384 (0x4000) bytes:
exehdr /stack:0x4000 nmake.exe
$(MAKEFLAGS) The NMAKE options currently in effect.
If you invoke NMAKE recursively, you
should use the
command:
$(MAKE) $(MAKEFLAGS).
The following flags are not preserved: A,
C, D, F, P, R, S, X. You cannot redefine
this macro.
$(MAKEDIR) The directory from which NMAKE is
invoked.
Like user-defined macro names, predefined macro names are case sensitive.
NMAKE interprets CC and cc as different macro names.
Macro modifiers allow you to specify parts of predefined macros
representing file names.
You can append characters to the first six macros in the preceding list to
modify their meaning. Appending a D specifies the directory part of the file
name only, an F specifies the file name, a B specifies just the base name,
and an R specifies the complete file name without the extension. If you add
one of these characters, you must enclose the macro name in parentheses.
(The predefined macros $$@ and $** are the only exceptions to the rule that
macro names more than one character long must be enclosed in parentheses.)
For example, assume that $@ has the value C:\SOURCE\PROG\SORT.OBJ. The list
below shows the effect of combining the special characters with $@:
Macro Value
────────────────────────────────────────────────────────────────────────────
$(@D) C:\SOURCE\PROG
$(@F) SORT.OBJ
$(@B) SORT
$(@R) C:\SOURCE\PROG\SORT
Examples
trig.lib : sin.obj cos.obj arctan.obj
!LIB trig.lib -+$?;
In the example above, the macro $? represents the names of all dependents
that are more recent than the target. The exclamation point causes NMAKE to
execute the LIB command once for each dependent in the list. As a result,
the LIB command is executed up to three times, each time replacing a module
with a newer version.
# Include files depend on versions in current directory
DIR=c:\include
$(DIR)\globals.h : globals.h
COPY globals.h $@
$(DIR)\types.h : types.h
COPY types.h $@
$(DIR)\macros.h : macros.h
COPY macros.h $@
The example above shows the use of NMAKE to update a group of include files.
Each of the files GLOBALS.H, TYPES.H, and MACROS.H in the directory
C:\INCLUDE depends on its counterpart in the current directory. If one of
the include files is out-of-date, NMAKE replaces it with the file of the
same name from the current directory.
7.2.3.4 Substitution within Macros
Just as macros allow you to substitute text in a description file, you can
also substitute text within a macro itself. Use the following form:
$(macroname:string1 = string2)
You can replace text in a macro, as well as in the description file.
Every occurrence of string1 is replaced by string2 in the macro macroname.
Do not put any spaces or tabs between macroname and the colon. Spaces
between the colon and string1 are made part of string1. If string2 is a null
string, all occurrences of string1 are deleted from the macroname macro.
The following description file illustrates macro substitution:
SRCS = prog.c sub1.c sub2.c
prog.exe : $(SRCS:.c=.obj)
QLINK $**;
DUP : $(SRCS)
!COPY $** c:\backup
The predefined macro $** stands for the names of all the dependent files
(see the list in Section 7.2.3.3). If you invoke the example file with a
command line that specifies both targets, NMAKE executes the following
commands:
QLINK prog.obj sub1.obj sub2.obj;
COPY prog.c c:\backup
COPY sub1.c c:\backup
COPY sub2.c c:\backup
The macro substitution does not alter the definition of the SRCS macro;
rather, it simply replaces the listed characters. When NMAKE builds the
target PROG.EXE, it gets the definition for the predefined macro $** (the
dependent list) from the dependency line, which specifies the macro
substitution in SRCS. The same is true for the second target, DUP. In this
case, however, no macro substitution is requested; SRCS retains its
original value, and $** represents the names of the C source files. (In the
example above, the target DUP is a pseudotarget; Section 7.2.6 describes
pseudotargets.)
You can also perform substitution in the following predefined macros: $@,
$*, $**, $?, and $. The principle is the same as for other macros. The
command in the following description block substitutes within a predefined
macro:
target.abc : depend.xyz
echo $(@:targ=blank)
If dependent depend.xyz is out-of-date relative to target target.abc,
NMAKE executes the command
echo blanket.abc
The example uses the predefined macro $@, which equals the full name of the
current target ( target.abc). It substitutes blank for targ in the
target, resulting in blanket.abc. Note that you do not put the usual dollar
sign in front of the predefined macro. The example uses
$(@:targ=blank)
instead of
$($@:targ=blank)
to substitute within the predefined macro $@.
7.2.3.5 Inherited Macros
When NMAKE executes, it creates macros equivalent to every current
environment variable. These are called "inherited" macros because they have
the same names and values as the corresponding environment variables. (The
inherited macro is all uppercase, however, even if the corresponding
environment variable is not.)
Inherited macros can be used like other macros. You can also redefine them.
The following example redefines the inherited macro PATH:
PATH = c:\tools\bin
sample.obj : sample.c
CL /c sample.c
Inherited macros take their definitions from environment variables.
No matter what value PATH had in the DOS environment, it has the value
c:\tools\bin when NMAKE executes the CL command in this description block.
Redefining the inherited macro does not affect the original environment
variable; when NMAKE terminates, PATH has its original value.
The /E option enforces macro inheritance. If you supply this option, NMAKE
ignores any attempt to redefine a macro that derives from an environment
variable.
7.2.3.6 Precedence among Macro Definitions
If you define the same macro in more than one place, NMAKE uses the macro
with the highest precedence. The precedence from highest to lowest is as
follows:
1. Macros defined on the command line
2. Macros defined in a description file or include file
3. Inherited macros
4. Macros defined in the TOOLS.INI file
5. Predefined macros such as CC and AS
The /E option defeats any attempt to redefine inherited macros. If you run
NMAKE with this option, macros inherited from environment variables override
any same-named macros in the description file.
7.2.4 Inference Rules
Inference rules are templates that NMAKE uses to create files with a given
extension. For instance, when NMAKE encounters a description block with no
commands, it tries to apply an inference rule that specifies how to create
the target from the dependent files, given the two extensions. Similarly, if
a dependent file does not exist, NMAKE tries to apply an inference rule that
specifies how to create the missing dependent from another file with the
same base name.
Inference rules tell NMAKE how to create files with a certain extension.
Inference rules provide a convenient shorthand for common operations. For
instance, you can use an inference rule to avoid repeating the same command
in several description blocks.
You can define your own inference rules or use predefined inference rules.
This section begins by describing user-defined inference rules.
7.2.4.1 User-Defined Inference Rules
You can define inference rules in the description file or in the TOOLS.INI
file. An inference-rule definition lists two file extensions and one or more
commands. For instance, the following inference rule tells NMAKE how to
build a .OBJ file using a .C file:
.C.OBJ:
QCL /c $<
The first line lists two extensions. The second extension (.OBJ) specifies
the type of the desired file and the first (.C) specifies the type of the
desired file's dependent. The second line lists the command used to build
the desired file. Here, the predefined macro $ represents the name of a
dependent that is out-of-date relative to the target.
NMAKE could apply the above inference rule to the following description
block:
sample.obj :
The description block lists only a target, SAMPLE.OBJ. Both the dependent
and the command are missing. However, given the target's base name and
extension, plus the above inference rule, NMAKE has enough information to
build the target. NMAKE first looks for a .C file with the same base name as
the target. If SAMPLE.C exists, NMAKE compares its date to that of
SAMPLE.OBJ (the comparison is triggered by the predefined macro $). If
SAMPLE.C has changed more recently, NMAKE compiles it using the QCL command
listed in the inference rule:
QCL /c sample.c
────────────────────────────────────────────────────────────────────────────
NOTE
NMAKE applies an inference rule only if the base name of the file it is
trying to create matches the base name of a file that already exists. Thus,
inference rules are useful only when there is a one-to-one correspondence
between the desired file and its dependent. You cannot define an inference
rule that replaces several modules in a library, for example.
────────────────────────────────────────────────────────────────────────────
7.2.4.2 Extension Search Paths
If an inference rule does not specify a search path, as in the example
above, NMAKE looks for files in the current directory. You can specify a
single path for each of the extensions, using the following form:
{frompath}. fromext{topath}. toext:
commands
NMAKE searches in the frompath directory for files with the fromext
extension. It uses commands to create files with the toext extension in the
topath directory.
7.2.4.3 Predefined Inference Rules
NMAKE provides predefined inference rules to perform these common
development tasks:
■ Creating a .OBJ file by compiling a .C file
■ Creating a .OBJ file by assembling a .ASM file
■ Creating a .EXE file by compiling a .C file and linking the resulting
.OBJ file
Table 7.1 describes the predefined inference rules.
Table 7.1 Predefined Inference Rules
╓┌───────────────┌─────────────────────────┌─────────────────────────────────╖
Inference Rule Command Default Action
────────────────────────────────────────────────────────────────────────────
.C.OBJ $(CC) $(CFLAGS) /C $*.C CL /C $*.C
.ASM.OBJ $(AS) $(AFLAGS) $*; MASM $*;
.C.EXE $(CC) $(CFLAGS) $*.C CL $*.C
────────────────────────────────────────────────────────────────────────────
For example, say that you have the following description file:
sample.exe :
Like the previous example, this description block lists a target without any
dependents or commands. NMAKE looks at the target's extension (.EXE) and
checks for an inference rule that describes how to create a .EXE file. The
last rule in Table 7.1 provides this information:
.c.exe:
$(CC) $(CFLAGS) $*.c
To apply this rule, NMAKE first looks for a file with the same base name as
the target (SAMPLE) and the .C extension. If SAMPLE.C exists in the current
directory, NMAKE executes the command line given in the rule. The command
compiles SAMPLE.C and links the resulting file SAMPLE.OBJ to create
SAMPLE.EXE.
7.2.4.4 Precedence among Inference Rules
If the same inference rule is defined in more than one place, NMAKE uses the
rule with the highest precedence. The precedence from highest to lowest is
1. Inference rules defined in the description file
2. Inference rules defined in the TOOLS.INI file
3. Predefined inference rules
NMAKE uses a predefined inference rule only if no user-defined inference
rule exists for the desired operation.
7.2.5 Directives
Directives allow you to write description files that are similar to batch
files. Directives can execute commands conditionally, display error
messages, include other files, and turn on or off certain options.
NMAKE directives are similar to C preprocessor directives.
A directive begins with an exclamation point (!), which must appear at the
beginning of the line. You can place spaces between the exclamation point
and the directive keyword. The following list describes NMAKE directives:
Directive Description
────────────────────────────────────────────────────────────────────────────
!CMDSWITCHES Turns on or off one of four NMAKE
{+| -}opt... options:
/D, /I, /N, and /S. If no options are
specified, the
options are reset to the way they were
when NMAKE started. Turn an option on by
preceding it with a plus sign (+), or
turn it off by preceding it with a minus
sign (-). Using this keyword updates the
MAKEFLAGS macro.
!ELSE Executes the statements between the
!ELSE and !ENDIF keywords if the
statements preceding the !ELSE keyword
were not executed.
!ENDIF Marks the end of the !IF keyword.
!ERROR text Causes text to be printed and then stops
execution.
!IF constantexpression Executes the statements between the !IF
keyword
and the next !ELSE or !ENDIF keyword if
constant
expression evaluates to a nonzero value.
!IFDEF macroname Executes the statements between the
!IFDEF keyword and the next !ELSE or
!ENDIF keyword if macroname is defined.
NMAKE considers a macro with a null
value to be defined.
!IFNDEF macroname Executes the statements between the
!IFNDEF keyword and the next !ELSE or
!ENDIF keyword if macroname is not
defined.
!INCLUDE filename Reads and evaluates the file filename
before continuing with the current
description file. If filename is
enclosed by angle brackets (< >), NMAKE
searches for the file in the directories
specified by the
INCLUDE macro. Otherwise, it looks only
in the
current directory. The INCLUDE macro is
initially set to the value of the
INCLUDE environment
variable.
!UNDEF macroname Marks macroname as being undefined in
NMAKE's symbol table.
The constantexpression used with the !IF directive can consist of integer
constants, string constants, or program invocations. Integer constants can
use the C unary operators for numerical negation (-), one's complement (~),
and logical negation (!). They can also use any of the C binary operators
listed below:
Operator Description
────────────────────────────────────────────────────────────────────────────
+ Addition
- Subtraction
* Multiplication
/ Division
% Modulus
& Bitwise AND
| Bitwise OR
^^ Bitwise XOR
&& Logical AND
|| Logical OR
<< Left shift
>> Right shift
== Equality
!= Inequality
< Less than
> Greater than
<= Less than or equal to
>= Greater than or equal to
You can group expressions using parentheses. NMAKE treats numbers as decimal
unless they start with 0 (octal) or 0x (hexadecimal). Use the equality (==)
operator to compare two strings for equality or the inequality (!=) operator
to compare for inequality. Enclose strings within quotes. Program
invocations must be in square brackets ([ ]).
Example
!INCLUDE <infrules.txt>
!CMDSWITCHES +D
winner.exe:winner.obj
!IFDEF debug
! IF "$(debug)"=="y"
QLINK /CO winner.obj;
! ELSE
QLINK winner.obj;
! ENDIF
!ELSE
! ERROR Macro named debug is not defined.
!ENDIF
In the example above, the !INCLUDE directive causes NMAKE to insert the file
INFRULES.TXT into the description file. The !CMDSWITCHES directive turns on
the /D option, which displays the dates of the files as they are checked. If
WINNER.EXE is out-of-date with respect to WINNER.OBJ, the !IFDEF directive
checks to see if the macro debug is defined. If it is defined, the !IF
directive checks to see if it is set to y. If it is, the linker is invoked
with the /CO option; otherwise it is invoked without. If the debug macro
is not defined, the !ERROR directive prints the message and NMAKE stops.
7.2.6 Pseudotargets
Pseudotargets are useful for building a group of files or executing a group
of commands.
A pseudotarget is similar to a target, but it is not a file. It is a name
that serves as a "handle" for building a group of files or executing a group
of commands. In the following example, UPDATE is a pseudotarget.
UPDATE: *.*
!COPY $** a:\product
When NMAKE evaluates a pseudotarget, it always considers the dependents to
be out-of-date. In the example, NMAKE copies each of the dependent files to
the specified drive and directory.
Like macro names, pseudotarget names are case sensitive. Predefined
pseudotarget names are all uppercase.
Predefined pseudotargets provide special rules in a description file. You
can use their names on the command line, in a description file, or in the
TOOLS.INI file. You need not specify them as targets; NMAKE uses the rules
they define no matter where they appear. NMAKE's predefined pseudotargets
are described in the following list:
Pseudotarget Action
────────────────────────────────────────────────────────────────────────────
.IGNORE : Ignores exit codes returned by programs
called from the description file. Same
effect as invoking NMAKE with the /I
option.
.PRECIOUS : target(s)... Tells NMAKE not to delete target(s) if
the commands that build it are quit or
interrupted. Using this pseudotarget
overrides the NMAKE default. By default,
NMAKE deletes the target if it cannot be
sure the target is built successfully.
.SILENT : Does not display lines as they are
executed. Same effect as invoking NMAKE
with the /S option.
.SUFFIXES : list... Lists file suffixes for NMAKE to try
when building a target file for which no
dependents are specified. This list is
used together with inference rules. See
Section 7.2.4, "Inference Rules."
When NMAKE finds a target without any
dependents, it searches the current
directory for a file with the same base
name as the target and a suffix from the
list. If NMAKE finds such a file, and if
an inference rule applies to the file,
then NMAKE treats the file as a
dependent of the target. The order of
the suffixes in the list defines the
order in which NMAKE searches for the
file. The list is predefined as follows:
.SUFFIXES: .obj .exe .c .asm
To add suffixes to the list, specify
.SUFFIXES : followed by the new suffixes.
To clear the list, specify
.SUFFIXES:
7.3 Command-Line Options
NMAKE accepts a number of options. You can specify options in uppercase or
lowercase and use either a slash or dash. For example, -A, /A, -a, and /a
all represent the same option. The NMAKE options are described in the
following list:
Option Action
────────────────────────────────────────────────────────────────────────────
/A Builds all of the requested targets even
if they are not out-of-date.
/C Suppresses nonfatal error or warning
messages and the NMAKE logo display.
/D Displays the modification date of each
file.
/E Causes environment variables to override
macro definitions in description files.
See Section 7.2.3, "Macros."
/F filename Specifies filename as the name of the
description file. If you supply a dash
(-) instead of a file name, NMAKE gets
input from the standard input device
instead of the description file.
/HELP Displays NMAKE command syntax.
/I Ignores return codes from commands
listed in the description file. NMAKE
processes the whole description file
even if errors occur.
/N Displays, but does not execute, the
description file's commands. This option
is useful for debugging
description files and checking which
targets are
out-of-date.
/NOLOGO Suppresses the NMAKE logo display.
/P Displays all macro definitions and
target descriptions on the standard
output device.
/Q Returns zero if the target is up-to-date
and nonzero if it is not. This option is
useful when running NMAKE from a batch
file.
/R Ignores inference rules and macros that
are predefined or defined in the
TOOLS.INI file.
/S Suppresses the display of commands
listed in the description file.
/T Changes the modification dates for
out-of-date target files to the current
date.
/X filename Sends all error output to filename,
which can be a file or a device. If you
supply a dash (-) instead of a file name,
the error output is sent to the standard
output device.
Examples
NMAKE /f sample.mak /c targ1 targ2
The command in the above example specifies two NMAKE options.
The /f option tells NMAKE to read the description file SAMPLE.MAK. The /c
option tells NMAKE not to display nonfatal error messages and warnings. The
command lists two targets (targ1 and targ2) to update.
NMAKE /D /N targ1
In the example above, NMAKE updates the target targ1. The /D option
displays the modification date of each file; the /N option displays the
commands without executing them.
7.4 Using a Response File to Invoke NMAKE
Occasionally, you may need to give NMAKE a long list of command-line
arguments that exceeds the maximum length of a command line (128 characters
in DOS). To do this, place the command arguments in a file, then give the
name of the file when you run NMAKE.
For instance, say that you create a file named UPDATE, which consists of
this line:
/S "program = sample" sort.exe search.exe
If you start NMAKE with the command
NMAKE @update
NMAKE reads its command-line arguments from UPDATE. The at sign (@) tells
NMAKE to read arguments from the file. The effect is the same as if you
typed the arguments directly on the command line:
NMAKE /S "program = sample" sort.exe search.exe
Within the file, line breaks between arguments are treated as spaces. Macro
definitions that contain spaces must be enclosed in quotation marks, just as
if you typed them on the command line. You can continue a macro definition
across multiple lines by ending each line except the last with a backslash (
\ ):
/S "program \
= sample" sort.exe search.exe
This file is equivalent to the first example. The backslash in the example
allows the macro definition ("program = sample") to span two lines.
7.5 The TOOLS.INI File
You can customize NMAKE by placing commonly used macros and inference rules
in the TOOLS.INI initialization file. Settings for NMAKE must follow a line
that begins with [NMAKE]. This part of the initialization file can contain
macro definitions, .SUFFIXES lists, and inference rules. For example,
[NMAKE]
CC=cl
CFLAGS=-Gc -Gs -W3 -Olt
.c.obj:
$(CC) -c $(CFLAGS) $*.c
If TOOLS.INI contains the code above, NMAKE reads and applies the lines
following [NMAKE]. The example defines the macros CC and CFLAGS and
redefines the inference rule for making .OBJ files from .C sources.
NMAKE looks for TOOLS.INI in the current directory. If it is not found
there, NMAKE searches the directory specified by the INIT environment
variable.
7.6 In-Line Files
NMAKE can write "in-line files," which can contain any text you specify. One
use for in-line files is to write a response file for another utility such
as LIB. (Response files are useful when you need to supply a program with a
long list of arguments that exceeds the maximum length of the command line.)
Use this syntax to create an in-line file:
target : dependents
command << «filename»
inlinetext
<<«KEEP | NOKEEP»
All of the text between the two sets of double angle brackets () is placed
in the in-line file. The filename is optional. If you don't supply filename,
NMAKE gives the in-line file a unique name. NMAKE places the in-line file in
the current directory or, if the TMP environment variable is defined, in the
directory specified by TMP.
The in-line file can be temporary or permanent. If you don't specify
otherwise, or if you specify NOKEEP, it is temporary. Specify KEEP to retain
the file.
The following example creates a LIB response file named LIB.LRF:
math.lib : add.obj sub.obj mul.obj div.obj
LIB @<<lib.lrf
math.lib
-+add.obj-+sub.obj-+mul.obj-+div.obj
listing
<<KEEP
The resulting response file tells LIB which library to use, the commands to
execute, and the listing file to produce:
math.lib
-+add.obj-+sub.obj-+mul.obj-+div.obj
listing
The in-line file specification can create more than one in-line file. For
instance,
target.abc : depend.xyz
cat <<file1 <<file2
I am the contents of file1.
<<KEEP
I am the contents of file2.
<<KEEP
The example creates two in-line files named FILE1 and FILE2; then NMAKE
executes the command:
CAT file1 file2
The KEEP keywords tell NMAKE not to delete FILE1 and FILE2 when done.
7.7 NMAKE Operations Sequence
If you are writing a complex description file, you may need to know the
exact order of steps that NMAKE follows. This section describes those steps
in order.
When you run NMAKE from the command line, its first task is to find the
description file, following these steps:
1. If NMAKE is invoked with the /F option, it uses the file name
specified in the option.
2. If /F is not specified, NMAKE looks for a file named MAKEFILE in the
current directory. If such a file exists, it is used as a description
file.
3. If NMAKE still has not found a description file, it returns an error.
NMAKE stops searching for a description file as soon as it finds one, even
if other potential description files exist. If you specify /F, NMAKE uses
the file specified by that option even if MAKEFILE exists in the current
directory.
If you do not specify targets, NMAKE updates only the first target in the
description file.
Next, NMAKE updates every target listed on the command line. If none is
listed, NMAKE updates only the first target in the description file.NMAKE
then applies macro definitions and inference rules in the following order,
from highest to lowest priority:
1. Macros defined on the command line
2. Macros defined in a description file or include file
3. Inherited macros
4. Macros defined in the TOOLS.INI file
5. Predefined macros such as CC and AS
The /E option causes inherited macros to override macros defined on the
command line. The /R option causes NMAKE to ignore macros and inference
rules that are predefined or defined in TOOLS.INI. If a macro is defined
more than once in any file, the last definition is used.
NMAKE updates the specified targets in the order in which they appear on the
command line. For each target, NMAKE checks the date and time of each
dependent and, if the dependent has changed more recently than the target,
performs the commands needed to update the target. If the dependents are
themselves targets that are out-of-date, NMAKE updates them first, in the
order they appear in the description block. If you specify a pseudotarget,
or if you use the /A option, NMAKE updates the target even if it is not
out-of-date with respect to its dependents.
If the target has no explicit dependents, NMAKE looks in the current
directory for one or more files whose extensions are in the .SUFFIXES list.
If it finds such files, NMAKE treats them as dependents and updates the
target according to the commands.
If no commands are given to update the target or if the dependents cannot be
found, NMAKE applies inference rules to build the target. By default, it
tries to build .EXE files from .OBJ files; it also tries to build .OBJ files
from .C and .ASM sources. In practice, this means you should specify .OBJ
files as dependents, because NMAKE compiles your source files when it can't
find the .OBJ files.
NMAKE normally quits processing the description file when a command returns
an error. In addition, if it cannot tell that the target was built
successfully, NMAKE deletes the partially created target. If you use the /I
commandline option, NMAKE ignores exit codes and attempts to continue
processing. The .IGNORE pseudotarget has the same effect. To prevent NMAKE
from deleting the partially created target, specify the target name in the
.PRECIOUS pseudotarget.
Alternatively, you can use the dash (-) command modifier to ignore the error
code for an individual command. An optional number after the dash tells
NMAKE to continue if the command returns an error code that is less than or
equal to the number, and to stop if the error code is greater than the
number.
You can help document errors by using the !ERROR directive to print
descriptive text. The directive causes NMAKE to print some text, then stop,
even if you use /I, .IGNORE, or the dash (-) modifier.
Appendix A Exit Codes
────────────────────────────────────────────────────────────────────────────
Most of the utilities return an exit code (sometimes called an "errorlevel"
code) that can be used by DOS batch files or other programs such as NMAKE.
If the program finishes without errors, it returns exit code 0. The code
returned is nonzero if the program encounters an error. This appendix
discusses several uses for exit codes and lists the exit codes that can be
returned by each utility.
A.1 Exit Codes with NMAKE
The Microsoft Program-Maintenance Utility (NMAKE) automatically stops
execution if a program executed by one of the commands in the NMAKE
description file encounters an error. (Invoke NMAKE with the /I option to
disable this behavior for the entire description file. Or, place a minus
sign (-) in front of a command to disable it for that command only.) The
exit code returned by the program is displayed as part of the error message.
For example, assume the NMAKE description file TEST contains the following
lines:
TEST.OBJ : TEST.C
QCL /c TEST.C
If the source code in TEST.C contains a program error (not a warning error),
you would see the following message the first time you use NMAKE with the
description file TEST:
"nmake: fatal error U1077: return code 2"
This error message indicates that the command QCL /c TEST.C in the NMAKE
description file returned exit code 2.
You can also test exit codes in NMAKE description files with the !IF
directive.
A.2 Exit Codes with DOS Batch Files
If you prefer to use DOS batch files instead of NMAKE description files, you
can test the code returned with the IF command. The following sample batch
file, called COMPILE.BAT, illustrates how to do this:
QCL /c %1.C
IF NOT ERRORLEVEL 1 QLINK %1;
IF NOT ERRORLEVEL 1 %1
You can execute this sample batch file with the following command:
COMPILE TEST
DOS then executes the first line of the batch file, substituting TEST for
the parameter %1, as in the following command line:
QCL /c TEST.C
It returns exit code 0 if the compilation is successful, or a higher code if
the compiler encounters an error. In the second line, DOS tests to see if
the code returned by the previous line is 1 or higher. If it is not (that
is, if the code is 0), DOS executes the following command:
QLINK TEST;
QLINK also returns a code, which is tested by the third line. If this code
is 0, the TEST program is executed.
The compiler returns the following exit codes:
Code Meaning
────────────────────────────────────────────────────────────────────────────
0 No error
Nonzero number Program or system-level error
A.3 Exit Codes for Programs
An exit code 0 always indicates execution of the program with no fatal
errors. Warning errors also return exit code 0. NMAKE can return several
codes indicating different kinds of errors, while other programs return only
one code to indicate that an error occurred.
A.3.1 QLINK Exit Codes
The linker returns the following exit codes:
Code Meaning
────────────────────────────────────────────────────────────────────────────
0 No error.
2 Program error. Commands or files given
as input to the linker produced the
error.
4 System error. The linker encountered one
of the
following problems: 1) ran out of space
on output
files; 2) was unable to reopen the
temporary file;
3) experienced an internal error; 4) was
interrupted by the user.
A.3.2 LIB Exit Codes
The Microsoft Library Manager (LIB) returns the following exit codes:
Code Meaning
────────────────────────────────────────────────────────────────────────────
0 No error.
2 Program error. Commands or files given
as input to the utility produced the
error.
4 System error. The library manager
encountered one of the following
problems: 1) ran out of memory; 2)
experienced an internal error; 3) was
interrupted by the user.
A.3.3 NMAKE Exit Codes
NMAKE returns the following exit codes:
Code Meaning
────────────────────────────────────────────────────────────────────────────
0 No error
2 Program error
4 System error─out of memory
If a program called by a command in the NMAKE description file produces an
error, the exit code is displayed in the NMAKE error message.
Appendix B Working with QuickC Compiler Memory Models
────────────────────────────────────────────────────────────────────────────
You can gain greater control over the way your program uses memory by
specifying the memory model for the program. You do not need to specify a
memory model except in the following cases:
■ Your program has more than 64K of code or more than 64K of static
data.
■ Your program contains individual arrays that need to be larger than
64K.
In these cases, you have the following options:
1. If you are compiling with the QCL command, you can specify one of the
other standard memory models (medium, compact, large, or huge) using
one of the /A options.
2. You can create a mixed-model program using the _near, _far, and _huge
keywords.
3. You can combine method 2 with method 1.
B.1 Near, Far, and Huge Addressing
The terms "near," "far," and "huge" are crucial to understanding the concept
of memory models. These terms indicate how data can be accessed in the
segmented architecture of the 8086 family of microprocessors (8086, 80186,
and 80286).
Segments
DOS loads the code and data allocated by your program into segments in
physical memory. Each segment can be up to 64K long. Separate segments are
always allocated for the program code and data, except for tiny-model
programs, in which only one segment is allocated for both code and data. For
other memory models, the minimum number of segments allocated for a program
is two. These two segments are called the default segments. The small memory
model uses only the two default segments. The other memory models discussed
in this appendix allow more than one code segment per program, or more than
one data segment per program, or both.
Near addresses
In the 8086 family of microprocessors, all memory addresses consist of two
parts:
1. A 16-bit number that represents the base address of a memory segment
2. Another 16-bit number that gives an offset within that segment
The architecture of the 8086 microprocessor is such that code can be
accessed within the default code or data segment by using just the 16-bit
offset value. This is possible because the segment addresses for the default
segments are always known. This 16-bit offset value is called a "near
address"; it can be accessed with a "near pointer." Because only 16-bit
arithmetic is required to access any near item, near references to code or
data are smaller and more efficient.
Far addresses
When data or code lie outside the default segments, the address must use
both the segment and offset values. Such addresses are called "far
addresses"; they can be accessed by using "far pointers" in a C program.
Accessing far data or code items is more expensive in terms of program speed
and size, but using them en-ables your programs to address all memory,
rather than just the standard 64K code and data segments.
Huge addresses
There is a third type of address used with the Microsoft QuickC Compiler:
the "huge address." A huge address is similar to a far address in that both
consist of a segment value and an offset value; but the two differ in the
way address arithmetic is performed on pointers. Because items (both code
and data) referenced by far pointers are still assumed to lie completely
within the segment in which they start, pointer arithmetic is done only on
the offset portion of the address. This gain in pointer arithmetic
efficiency is achieved, however, by limiting the size of any single item to
64K. With data items, huge pointers overcome this size limitation: pointer
arithmetic is performed on all 32 bits of the data item's address, thus
allowing data items referenced by huge pointers to span more than one
segment, provided they conform to the rules outlined in Section B.2.6,
"Creating Huge-Model Programs."
The rest of this chapter deals with the various methods you can use to
control whether your program makes near or far calls to access code or data.
B.2 Using the Standard Memory Models
The libraries created by the SETUP program support six standard memory
models. Using the standard memory models is the simplest way to control how
your program accesses code and data in memory.
When you use the standard memory models, the compiler handles library
support for you. The library corresponding to the memory model you specify
is used automatically. All memory models, except the tiny and huge models,
have their own libraries. The tiny model uses the same library as the small
model, and the huge model uses the same library as the large model.
The advantage of using standard models for your programs is simplicity. In
the standard models, memory management is specified by compiler options;
since the standard models do not require the use of extended keywords, they
are the best way to write code that can be ported to other systems
(particularly systems that do not use segmented architectures).
The disadvantage of using standard memory models exclusively is that they
may not produce the most efficient code. For example, if you have an
otherwise small-model program containing a large array that pushes the total
data size for your program over the 64K limit for small model, it may be to
your advantage to declare the one array with the _far keyword, while keeping
the rest of the program small model, as opposed to using the standard
compact memory model for the entire program. For maximum flexibility and
control over how your program uses memory, you can combine the
standard-memory-model method with the _near, _far, and _huge keywords,
described in Section B.3.
The /A options for QCL are used to specify one of the six standard memory
models (tiny, small, medium, compact, large, or huge) at compile time. These
memory-model options are discussed in the next six sections.
Note that in the following sections, which describe the different
memory-model addressing conventions, it is important to keep in mind two
common features of all six models:
1. No single source module can generate 64K or more of code.
2. No single data item can exceed 64K, unless it appears in a huge-model
program or it has been declared with the _huge keyword.
B.2.1 Creating Tiny-Model Programs
The /AT option tells the compiler to create a program that occupies one
segment, which contains both code and data. A tiny-model program, including
code and data, cannot exceed 64K in size. Thus the tiny model produces the
smallest programs, though they offer no speed advantage over small-model
programs.
The tiny memory model produces .COM files instead of .EXE files. To produce
.COM files, specify the /T option when linking. This will link the object
files with CRTCOM.LIB, which contains code needed by .COM files.
Figure B.1 illustrates how memory is set up for the tiny memory model.
(This figure may be found in the printed book.)
B.2.2 Creating Small-Model Programs
The /AS option tells the compiler to create a program that occupies the two
default segments─one for code and one for data.
Small-model programs are typically QuickC programs that are short or have a
limited purpose. Because code and data for these programs are each limited
to 64K, the total size of a small-model program can never exceed 128K. Most
programs fit easily into this model.
Because programs compiled within the QuickC environment use the small memory
model by default, you should give the /AS option in cases where you use the
QCL command to compile a module for use within the QuickC environment.
By default, both code and data items in small-model programs are accessed
with near addresses. This makes small-model programs faster than those using
the memory models described in the following sections. You can override the
defaults by using the _far or _huge keyword for data or by using the _far
keyword for code.
The QCL command and the compiler in the QuickC environment create
small-model programs automatically if you do not specify a memory model. The
/AS option is provided for completeness; you never need to give it
explicitly.
Figure B.2 illustrates how memory is set up for the small memory model.
(This figure may be found in the printed book.)
B.2.3 Creating Medium-Model Programs
The /AM option provides a single segment for program data and multiple
segments for program code. Each source module is given its own code segment.
Medium-model programs are typically QuickC programs that have a large number
of program statements (more than 64K of code), but a relatively small amount
of data (less than 64K). Program code can occupy any amount of space and is
given as many segments as needed; total program data cannot be greater than
64K.
By default, code items in medium-model programs are accessed with far
addresses, and data items are accessed with near addresses. You can override
the default by using the _far or _huge keyword for data and the _far keyword
for code.
The medium model provides a useful trade-off between speed and space, since
most programs refer more frequently to data items than to code. Figure B.3
illustrates how memory is set up for the medium memory model.
(This figure may be found in the printed book.)
B.2.4 Creating Compact-Model Programs
The /AC option directs the compiler to allow multiple segments for program
data but only one segment for the program code.
Compact-model programs are typically QuickC programs that have a large
amount of data but a relatively small number of program statements. Program
data can occupy any amount of space and are given as many segments as
needed.
By default, code items in compact-model programs are accessed with near
addresses, and data items are accessed with far addresses. You can override
the defaults by using the _near or _huge keyword for data or by using the
_far keyword for code.
In the medium and compact models, NULL must be used carefully in certain
situations. NULL actually represents a null data pointer. In the small,
large, and huge memory models, where code and data pointers are the same
size, it can be used with either. This is not the case, however, in medium
and compact memory models, where code and data pointers are different sizes.
Consider the following example:
void func1(char *dp)
{
.
.
.
}
void func2(char (*fp)(void))
{
.
.
.
}
main()
{
func1(NULL);
func2(NULL);
}
This example passes a 16-bit pointer to both func1 and func2 if compiled
using the medium model, and a 32-bit pointer to both func1 and func2 if
compiled using the compact model. To override this behavior, add prototypes
to the beginning of the program to indicate the types, or use an explicit
cast on the argument to func1 (compact model) or func2 (medium model).
Figure B.4 illustrates how memory is set up for the compact memory model.
(This figure may be found in the printed book.)
B.2.5 Creating Large-Model Programs
The /AL option allows the compiler to create multiple segments, as needed,
for both code and data. No one data item, however, can exceed 64K.
Large-model programs are typically very large C programs that use a large
amount of data storage during normal processing.
By default, both code and data items in large-model programs are accessed
with far addresses. You can override the defaults by using the _near or
_huge keyword for data or by using the _near keyword for code.
Figure B.5 illustrates how memory is set up for the large and huge memory
models.
(This figure may be found in the printed book.)
B.2.6 Creating Huge-Model Programs
The /AH option is similar to the /AL option, except that the restriction on
the size of individual data items is removed for arrays.
Restrictions
Some size restrictions do apply to elements of huge arrays where the array
is larger than 64K. To provide efficient addressing, array elements are not
permitted to cross segment boundaries. This has the following implications:
■ No array element can be larger than 64K. For instance, this might
occur when an array has elements that are structures or arrays.
■ For any array larger than 128K, all elements must have a size in bytes
equal to a power of 2 (that is, 2 bytes, 4 bytes, 8 bytes, 16 bytes,
and so on). If the array is 128K or smaller, however, its elements may
be any size, up to and including 64K.
Pointer subtraction
In huge-model programs, care must be taken when using the sizeof operator or
when subtracting pointers. The C language defines the value returned by the
sizeof operator to be an unsigned int value, but the size in bytes of a huge
array is an unsigned long value. To solve this discrepancy, the QuickC
compiler produces the correct size of a huge array when a type cast like the
following is used:
(unsigned long)sizeof(huge_item)
Similarly, the C language defines the result of subtracting two pointers as
an int value. When subtracting two huge pointers, however, the result may be
a long int value. The QuickC compiler gives the correct result when a type
cast like the following is used:
(long)(huge_ptr1 - huge_ptr2)
B.3 Using the _near, _far, and _huge Keywords
One limitation of the predefined memory-model structure is that when you
change memory models, all data and code address sizes are subject to change.
The QuickC compiler, however, lets you override the default addressing
convention for a given memory model and access items with a near, far, or
huge pointer. This is done with the _near, _far, and _huge keywords. These
special type
modifiers can be used with a standard memory model to overcome addressing
limitations for particular data or code items, or to optimize access to
these items without changing the addressing conventions for the program as a
whole. Table B.1 explains how the use of these keywords affects the
addressing of code or data, or pointers to code or data.
Table B.1 Addressing of Code and Data Declared with _near and
╓┌────────┌──────────────────────────┌──────────────────────────┌────────────╖
Keyword Pointer Data Function Arithmetic
────────────────────────────────────────────────────────────────────────────
_near Resides in default data Assumed to be in current 16 bits
segment; referenced with code segment; referenced
16-bit addresses with 16-bit addresses
(pointers to data are 16 (pointers to functions
bits) are 16 bits)
_far May be anywhere in Not assumed to be in 16 bits
memory─not assumed to current code segment;
reside in current data referenced with 32-bit
segment; referenced with address (pointers to
32-bit addresses functions are 32 bits)
(pointers to data are 32
bits)
Keyword Pointer Data Function Arithmetic
────────────────────────────────────────────────────────────────────────────
_huge May be anywhere in Not applicable to code 32 bits
memory─not assumed to
reside in current data
segment; individual data
items (arrays) can exceed
64K in size; referenced
with 32-bit addresses
(pointers to data are 32
bits)
────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────
NOTE
The _near, _far, and _huge keywords are not a standard part of the C
language; they are meaningful only for systems that use a segmented
architecture similar to that of the 8086 microprocessors. Keep this in mind
if you want your code to be ported to other systems.
────────────────────────────────────────────────────────────────────────────
In the Microsoft QuickC compiler, the words _near, _far, and _huge are C
keywords by default. To treat these keywords as ordinary identifiers, you
must do one of the following:
■ For programs compiled within the QuickC environment, compile with the
MS Extensions option turned off.
■ For programs compiled with the QCL command, give the /Za option at
compile time.
These options are useful if you are compiling programs with compilers in
which _near, _far, and _huge are not keywords─for instance, if you are
porting a program in which one of these words is used as a label.
B.3.1 Library Support for _near, _far, and _huge
When using the _near, _far, and _huge keywords to modify addressing
conventions for particular items, you can usually use one of the standard
libraries (tiny, small, compact, medium, large, or huge) with your program.
The large-model libraries are also appropriate for use with huge-model
programs. However, you must use care when calling library routines. In
general, you cannot pass far pointers, or the addresses of far data items,
to a small-model library routine. (Some exceptions to this statement are the
library routines halloc and hfree, and the printf family of functions.) Of
course, you can always pass the value of a far item to a small-model library
routine, as shown in the following example:
long _far time_val;
time(&time_val); /* Illegal */
printf("%ld\n", time_val); /* Legal */
If you use the _near, _far, or _huge keyword, it is strongly recommended
that you use function prototypes with argument-type lists to ensure that all
pointer arguments are passed to functions correctly (see Section B.3.4).
B.3.2 Declaring Data with _near, _far, and _huge
The _near, _far, and _huge keywords modify either objects or pointers to
objects. When using them to declare data or code (or pointers to data or
code), keep the following rules in mind:
■ The keyword always modifies the object or pointer immediately to its
right. In complex declarators, think of the _far keyword and the item
immediately to its right as being a single unit. For example, in the
declarator
char _far* *p;
p is a pointer (whose size depends on the memory model specified) to
a far pointer to char.
■ If the item immediately to the right of the keyword is an identifier,
the keyword determines whether the item will be allocated in the
default data segment ( _near) or a separate data segment ( _far or
_huge). For example,
char _near a;
allocates a as an item of type char with a near address.
■ If the item immediately to the right of the keyword is a pointer, the
keyword determines whether the pointer will hold a near address (16
bits), a far address (32 bits), or a huge address (also 32 bits). For
example,
char _far *p;
allocates p as a far pointer (32 bits) to an item of type char.
Examples
The examples in this section show data declarations using the _near, _far,
and _huge keywords.
char a[3000]; /* small-model program */
char _far b[30000];
The first declaration in the example above allocates the array a in the
default data segment. By contrast, the array b in the second declaration
may be allocated in any far data segment. Since these declarations appear in
a small-model program, array a probably represents frequently used data
that were deliberately placed in the default segment for fast access. Array
b probably represents seldom used data that might make the default data
segment exceed 64K and force the programmer to use a larger memory model if
the array were not declared with the _far keyword. The second declaration
uses a large array because it is more likely that a programmer would want to
specify the address-allocation size for items of substantial size.
char a[3000]; /* large-model program */
char _near b[3000];
In the example above, access speed would probably not be critical for array
a. Even though it may or may not be allocated within the default data
segment, it is always referenced with a 32-bit address. Array b is
explicitly allocated within the default data segment to improve speed of
access in this memory model (large).
char _huge a[100000]; /* illegal in QuickC */
extern char huge a[];
Both declarations in the example above are illegal. QuickC does not support
static huge data.
char _huge *hp; /* small-model program */
hp = halloc(100000,1);
hp[0] = 'a';
In the small-model program above, hp is declared as a pointer to huge
data. Any pointer arithmetic for hp (such as hp++) would be performed
using 32-bit arithmetic. You can simulate a huge array through the pointer
hp by using the huge data allocation function halloc.
char *pa; /* small-model program */
char _far *pb;
The pointer pa is declared as a near pointer to an item of type char in
the example above. The pointer is near by default since the example appears
in a small-model program. By contrast, pb is allocated as a far pointer to
an item of type char; pb could be used to point to, and step through, an
array of characters stored in a segment other than the default data segment.
For example, pa might be used to point to array a in the first example,
while pb might be used to point to array b.
char _far * *pa; /* small-model program */
char _far * *pa; /* large-model program */
The pointer declarations in the example above illustrate the interaction
between the memory model chosen and the _near, _far, and _huge keywords.
Although the declarations for pa are identical, in a small-model program
pa is declared as a near pointer to an array of far pointers to type char,
while in a large-model program, pa is declared as a far pointer to an
array of far pointers to type char.
char _far * _near *pb; /* any model */
char _far * _far *pb;
In the first declaration in this final example, pb is declared as a near
pointer to an array of far pointers to type char; in the second declaration,
pb is declared as a far pointer to an array of far pointers to type char.
Note that, in this example, the _far and _near keywords override the
model-specific addressing conventions shown in the fifth example; the
declarations for pb would have the same effect, regardless of the memory
model.
B.3.3 Declaring Functions with the _near and _far Keywords
The rules for using the _near, _far, and _huge keywords for functions are
similar to those for using them with data, as listed below:
■ The keyword always modifies the function or pointer immediately to its
right. See Chapter 2, "Functions," of C for Yourself, for more
information about rules for evaluating complex declarations.
■ If the item immediately to the right of the keyword is a function,
then the keyword determines whether the function will be allocated as
near or far. For example,
char _far fun( );
defines fun as a function called with a 32-bit address and returning
type char.
■ If the item immediately to the right of the keyword is a pointer to a
function, then the keyword determines whether the function will be
called using a near (16-bit) or far (32-bit) address. For example,
char (_far * pfun)( );
defines pfun as a far pointer (32 bits) to a function returning type
char.
■ Function declarations must match function definitions.
■ The _huge keyword cannot be applied to functions.
Examples
void char _far fun(void); /* small model */
void char _far fun(void)
{
.
.
.
}
In the example above, fun is declared as a function returning type char.
The _far keyword in the declaration means that fun must be called with a
32-bit call.
static char _far * _near fun( ); /* large model */
static char _far * _near fun( )
{
.
.
.
}
In the large-model example above, fun is declared as a near function that
returns a far pointer to type char. Such a function might be seen in a
large-model program as a helper routine that is used frequently, but only by
the routines in its own module. Because all routines in a given module share
the same code segment, the function could always be accessed with a near
call. However, you could not pass a pointer to fun as an argument to
another function outside the module in which fun was declared.
void _far *fun(void); /* small model */
void (_far * pfun) ( ) = fun;
The small-model example above declares pfun as a far pointer to a function
that has return type void, and then assigns the address of fun to pfun.
In fact, pfun could be used to point to any function accessed with a far
call. Note that if the function pointed to by pfun has not been declared
with the _far keyword, or if it is not far by default, then calling that
function through pfun would cause the program to fail.
double _far * (_far fun)( ); /* compact model */
double _far * (_far *pfun)( ) = fun;
The final example above declares pfun as a far pointer to a function that
returns a far pointer to type double, and then assigns the address of fun
to pfun. This might be used in a compact-model program for a function that
is not used frequently and thus does not need to be in the default code
segment. Both the function and the pointer to the function must be declared
with the _far keyword.
B.3.4 Pointer Conversions
Passing pointers as arguments to functions may cause automatic conversions
in the size of the pointer argument because passing a pointer to a function
forces the pointer size to the larger of the following two sizes:
1. The default pointer size for that type, as defined by the memory model
used during compilation.
For example, in medium-model programs, data pointer arguments are near
by default and code pointer arguments are far by default.
2. The type of the argument.
If a function prototype with argument types is given, the compiler performs
type checking and enforces the conversion of actual arguments to the
declared type of the corresponding formal argument. However, if no
declaration is present or the argument-type list is empty, the compiler
converts pointer arguments automatically to either the default type or the
type of the argument, whichever is largest. To avoid mismatched arguments,
you should always use a prototype with the argument types.
Examples
/* This program produces unexpected results in compact-,
** large-, or huge-model programs.
*/
main( )
{
int _near *x;
char _far *y;
int z = 1;
test_fun(x, y, z); /*x coerced to far pointer*/
}
int test_fun(ptr1, ptr2, a)
int _near *ptr1;
char _far *ptr2;
int a;
{
printf("Value of a = %d\n", a);
}
If the preceding example is compiled as a small-model program (default for
QCL) or medium-model program (with the /AM option on the QCL command line),
the size of pointer argument x is 16 bits, the size of pointer argument y
is 32 bits, and the value printed for a is 1. However, if the preceding
example is compiled with the /AC, /AL, or /AH option, both x and y are
automatically converted to far pointers when they are passed to test_fun.
Because ptr1, the first parameter of test_fun, is defined as a
near-pointer argument, it takes only 16 bits of the 32 bits passed to it.
The next parameter, ptr2, takes the remaining 16 bits passed to ptr1, plus
16 bits of the 32 bits passed to it. Finally, the third parameter, a, takes
the leftover 16 bits from ptr2, instead of the value of z in the main
function. This shifting process does not generate an error message because
both the function call and the function definition are legal; in this case,
the program does not work as intended because the value assigned to a is
not the value intended.
To pass ptr1 as a near pointer, you should include a forward declaration
that specifically declares this argument for test_fun as a near pointer,
as shown below:
/* First, declare test_fun so the compiler knows in advance
** about the near pointer argument:
*/
int test_fun(int _near*, char _far *, int);
main( )
{
int _near *x;
char _far *y;
int z = 1;
test_fun(x, y, z); /* now, x will not be coerced
** to a far pointer; it will be
** passed as a near pointer,
** no matter what memory
** model is used
*/
}
int test_fun(ptr1, ptr2, a)
int _near *ptr1;
char _far *ptr2;
int a;
{
printf("Value of a = %d\n", a);
}
Note that it would not be sufficient to reverse the definition order for
test_fun and main in the first example to avoid pointer coercions; the
pointer arguments must be declared in a forward declaration, as in the
second example.
Appendix C Hardware-Specific Utilities
────────────────────────────────────────────────────────────────────────────
This appendix describes three utility programs provided with the Microsoft
QuickC Compiler. These utilities support special hardware that some QuickC
users may have. The utilities are
■ The FIXSHIFT utility, which fixes a bug associated with some COMPAQ(R)
and compatible keyboards
■ The MSHERC driver, which supports the Hercules display adapter
■ The MOUSE driver, which supports the Microsoft mouse
C.1 Fixing Keyboard Problems with FIXSHIFT
On the keyboards of some COMPAQ and compatible computers, the arrow keys are
not part of the numeric keypad. Because of a bug in the ROM BIOS, the QuickC
editor (and other software not supplied by Microsoft) may not operate
correctly on these machines. The FIXSHIFT utility fixes this bug.
To correct the problem, copy FIXSHIFT.COM to the directory that contains the
QuickC program files, and type the following command:
fixshift
Any combination of uppercase and lowercase letters is acceptable for this
command. When FIXSHIFT executes, it first prompts you to press the DOWN key
to ascertain whether the BIOS has the bug. If not, FIXSHIFT displays a
message telling you so, then exits. You need not run FIXSHIFT again. If your
machine's BIOS has the bug, FIXSHIFT displays additional prompts that guide
you through the appropriate actions.
FIXSHIFT requires approximately 450 bytes of memory. It fixes only the BIOS
bug and has no effect on other programs that you run. You can include the
FIXSHIFT command in your AUTOEXEC.BAT file to correct the problem each time
you start the computer.
C.2 Using Hercules Graphics
This section briefly summarizes the support that Microsoft QuickC provides
for the Hercules display adapter. For more information, see your Hercules
documentation. Note that the graphics demonstration program GRDEMO.C
supports Hercules graphics.
C.2.1 Support for Cards and Display Characteristics
QuickC supports the Hercules Graphics Card, Graphics Card Plus, InColor
Card, and other cards that are 100 percent compatible.
Only monochrome text and graphics are supported. In monochrome, the screen
resolution is 720 x 348 pixels. The character box is 9 x 14 pixels. Text
dimensions are 80 columns by 25 rows, but the bottom two scan lines of the
25th row are not visible.
C.2.2 The MSHERC Driver
MSHERC.COM is the driver for Hercules graphics. You must load the driver
before running programs that use Hercules graphics. To load the driver, type
the following command:
MSHERC
To load the driver when you start the machine, put the MSHERC command in
your AUTOEXEC.BAT file.
If you have both a Hercules monochrome card and a color video card, you
should invoke MSHERC.COM with the /H (/HALF) option, as follows:
MSHERC /H
The /H option causes the driver to use one instead of two graphics pages.
This prevents the two video cards from trying to use the same area of
memory. You need not use the /H option if you have only a Hercules card.
If you are developing a commercial application that uses graphics, you
should include MSHERC.COM with your product; you are free to include this
file without an explicit licensing agreement.
────────────────────────────────────────────────────────────────────────────
NOTE
MSHERC.COM is identical to QBHERC.COM, the Hercules driver shipped with
Microsoft QuickBASIC version 4.0, and the Microsoft BASIC Compiler version
6.0.
────────────────────────────────────────────────────────────────────────────
C.2.3 Using a Mouse
To use a mouse with the Hercules adapter, follow the special instructions
for Hercules cards in the Microsoft Mouse Programmer's Reference Guide.
(This manual must be ordered separately; it is not supplied with either
Microsoft QuickC or the Microsoft Mouse package.)
C.2.4 Setting Hercules Graphics Mode
The graphics include file GRAPH.H sets manifest constants needed for
Hercules graphics operation. In GRAPH.H, the constant _HERCMONO sets the
video mode to 720 x 348 pixels in monochrome. GRAPH.H also includes the
constant _HGC in the section labeled "videoconfig adapter values."
C.3 The Mouse Driver
The Microsoft Mouse is optional software and is not required for QuickC. If
you use the mouse, however, you must have version 6.10 or later of the
MOUSE.COM driver; otherwise, QuickC will not operate correctly. If you have
an earlier release, you need to use the MOUSE.COM driver provided with
QuickC. See your Microsoft Mouse manual for installation instructions. If
you update the driver, be sure to delete any outdated MOUSE.SYS drivers from
your CONFIG.SYS file.
2094
Appendix D Error Messages
────────────────────────────────────────────────────────────────────────────
This appendix lists error messages you may encounter as you develop a
program and gives a brief description of actions you can take to correct the
errors. The following list tells where to find error messages for the
various components of the Microsoft QuickC Compiler:
Component Section
────────────────────────────────────────────────────────────────────────────
The Microsoft QuickC Compiler "Compiler Errors"
The command line used to invoke "Command-Line Errors"
the Microsoft QuickC Compiler
The Microsoft C "Run-Time Errors"
run-time libraries
and other run-time situations
The Microsoft QuickC linker, "QLINK Error Messages"
QLINK
The Microsoft Library Manager, "LIB Error Messages"
LIB
The Microsoft "NMAKE Error Messages"
Program-Maintenance Utility,
NMAKE
Note that the compiler, command-line, and run-time error messages are listed
alphabetically by category in this appendix.
See "Compiler Limits" in the "Compiler Errors" section for information about
compiler limits; see "Run-Time Limits" in the "Run-Time Errors" section for
information about run-time limits.
D.1 Compiler Errors
The error messages produced by the QuickC Compiler fall into three
categories:
1. Fatal error messages
2. Compilation error messages
3. Warning messages
The messages for each category are listed below in numerical order, with a
brief explanation of each error. To look up an error message, first
determine the message category, then find the error number. Each message
that is generated within the QuickC environment appears in the error window;
QuickC moves the cursor to the line that caused the error. Each message
generated by compiling with the QCL command gives the file name and line
number where the error occurs.
Fatal Error Messages
Fatal error messages indicate a severe problem, one that prevents the
compiler from processing your program any further. These messages have the
following format:
filename(line) : fatal error C1xxx : messagetext
After the compiler displays a fatal error message, it terminates without
producing an object file or checking for further errors.
Compilation Error Messages
Compilation error messages identify actual program errors. These messages
appear in the following format:
filename(line) : error C2xxx : messagetext
The compiler does not produce an object file for a source file that has
compilation errors in the program. When the compiler encounters such errors,
it attempts to recover from the error. If possible, it continues to process
the source file and produce error messages. If errors are too numerous or
too severe, the compiler stops processing.
Warning Messages
Warning messages are informational only; they do not prevent compilation or
linking. These messages appear in the following format:
filename(line) : warning C4xxx : messagetext
You can use the /W option to control the level of warnings that the compiler
generates.
D.1.1 Fatal Error Messages
The following messages identify fatal errors. The compiler cannot recover
from a fatal error; it terminates after displaying the error message.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1000 UNKNOWN FATAL ERROR Contact Microsoft
Product Support Services
An unknown error condition was detected
by the compiler.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
C1001 Internal Compiler Error (compiler file '
filename', line n) Contact Microsoft
Product Support Services
The compiler detected an internal
inconsistency.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package. Note the file name and line
number where the error occurred; an
internal file and line number are
provided in addition to the file and
line number of your source file.
C1002 compiler is out of heap space in Pass 2
The compiler ran out of dynamic memory
space. Usually this means the program
has too many symbols and/or complex
expressions.
One of the following may be a solution:
■ Divide the file into several smaller
source files.
■ Break expressions into smaller
subexpressions.
■ Remove other programs or drivers
running in the system which could be
consuming significant amounts of memory.
■ Compile without using NMAKE.
C1003 error count exceeds n; stopping
compilation
Errors in the program were too numerous
or too severe to allow recovery, and the
compiler must terminate.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1004 unexpected end-of-file found
The default disk drive did not contain
sufficient space for the compiler to
create temporary files. The space
required is approximately two times the
size of the source file.
This message also appears when the #if
directive occurs without a corresponding
closing #endif directive while the #if
test directs the compiler to skip the
section.
C1005 string too big for buffer
A string in a compiler intermediate file
overflowed a buffer.
C1006 write error on compiler intermediate
file
The compiler was unable to create the
intermediate files used in the
compilation process.
C1007 unrecognized flag 'string' in 'option'
The string in the command-line option
was not a valid option.
C1008 no input file specified
The compiler was not given a file to
compile.
C1009 compiler limit : macros nested too
deeply
Too many macros were being expanded at
the same time.
This error occurs when a macro
definition contains macros to be
expanded and those macros contain other
macros.
Try splitting the nested macros into
simpler macros.
C1010 compiler limit : macro expansion too big
The expansion of a macro exceeded the
available space.
Produce a preprocessor listing using the
/P option and check to see if the
expanded text is too large.
Try to split up the macros into simpler
macros, or to remove nonessential space
and tab characters from macro
definitions used in the expansion.
C1011 compiler limit : 'identifier' : macro
definition too big
The macro definition was longer than
allowed.
Split the definition into shorter
definitions.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1012 unmatched parenthesis nesting - missing
'character'
The parentheses in a preprocessor
directive were not matched. The missing
character is either a left or right
parenthesis.
C1014 too many include files
Nesting of #include directives exceeded
the 10-level limit.
Up to 10 open files may be included by
the use of nested directives. The .C
file containing the directive is counted
as one of the files.
C1016 #if[n]def expected an identifier
An identifier must be specified with the
#ifdef and #ifndef directives.
C1017 invalid integer constant expression
The expression in an #if directive
either did not exist or did not evaluate
to a constant.
C1018 unexpected '#elif'
The #elif directive is legal only when
it appears within an #if, #ifdef, or
#ifndef construct.
C1019 unexpected '#else'
The #else directive is legal only when
it appears within an #if, #ifdef, or
#ifndef construct.
C1020 unexpected '#endif'
An #endif directive appeared without a
matching #if, #ifdef, or #ifndef
directive.
C1021 invalid preprocessor command 'string'
The characters following the number sign
(#) did not form a valid preprocessor
directive.
C1022 expected '#endif'
An #if, #ifdef, or #ifndef directive was
not terminated with an #endif directive.
C1023 cannot open source file 'filename'
The given file either did not exist,
could not be opened, or was not found.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1023 (continued)
Make sure the environment settings are
valid and that the correct path name for
the file is specified.
If this error appears without an error
message, the compiler has run out of
file handles. Increase the number of
file handles by changing the FILES
setting in CONFIG.SYS to allow a larger
number of open files. FILES=20 is the
recommended setting.
C1024 cannot open include file 'filename'
The specified file in an #include
preprocessor directive could not be
found.
Make sure settings for the INCLUDE and
TMP environment variables are valid and
that the correct path name for the file
is specified.
If this error appears without an error
message, the compiler has run out of
file handles. Increase the number of
file handles by changing the FILES
setting in CONFIG.SYS to allow a larger
number of open files. FILES=20 is the
recommended setting.
C1025 compiler terminated by user
The compiler was stopped by the user.
C1026 parser stack overflow, please simplify
your program
The program cannot be processed because
the space required to parse the program
causes a stack overflow in the compiler.
Simplify the program by decreasing the
complexity of expressions. Decrease the
level of nesting in for and switch
statements by putting some of the more
deeply nested statements in separate
functions. Break up very long
expressions involving ',' operators or
function calls.
C1027 DGROUP data allocation exceeds 64K
More than 64K of variables were
allocated to the default data segment.
For compact-, large-, or huge-model
programs, compile with the QCL command
and use the /Gt option to move items
into separate segments. In tiny-, small-
or medium-model programs, consider
explicitly allocating some variables
outside of DGROUP by using _based or
_far.
C1028 'segment' : segment allocation exceeds
64K
More than 64K of far data were allocated
to the given segment. A single module
can have only 64K of far data.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1028 (continued)
There are several ways to correct this
situation:
■ Break the declarations into separate
modules.
■ Reduce the amount of data used by the
program.
■ Compile the program with the Microsoft
C Optimizing Compiler.
C1031 compiler limit : function calls nested
too deeply
The program exceeded the dynamic
compiler limit on nested function calls.
Split the nested call, saving the return
value from one of the nested functions
in a temporary variable.
C1032 cannot open object listing file '
filename'
There are several possible causes for
this error:
■ The given name is not valid.
■ The file cannot be opened for lack of
space.
■ A read-only file with the given name
already exists.
C1033 cannot open assembly language output
file 'filename'
There are several possible causes for
this error:
■ The given name is not valid.
■ The file cannot be opened for lack of
space.
■ A read-only file with the given name
already exists.
C1035 expression too complex, please simplify
The compiler was unable to generate code
for a complex expression. Break the
expression into simpler subexpressions
and recompile.
C1036 cannot open source listing file '
filename'
There are several possible causes for
this error:
■ The given name is not valid.
■ The file cannot be opened for lack of
space.
■ A read-only file with the given name
already exists.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1037 cannot open object file 'filename'
There are several possible causes for
this error:
■ The given name is not valid.
■ The file cannot be opened for lack of
space.
■ A read-only file with the given name
already exists.
C1039 unrecoverable heap overflow in Pass 3
The post-optimizer compiler pass
overflowed the heap and could not
continue.
One of the following may be a solution:
■ Break up the function containing the
line that caused the error.
■ Recompile with the /Od option,
removing optimization.
■ Remove other programs or drivers
running in the system which could be
consuming significant amounts of memory.
■ Compile without using NMAKE.
C1040 unexpected end-of-file in source file '
filename'
The compiler detected an unexpected
end-of-file condition while creating a
source listing or mingled source/object
listing.
C1041 cannot open compiler intermediate file -
no more files
The compiler could not create
intermediate files for use in the
compilation process because no more file
handles were available.
Increase the number of file handles by
changing the FILES setting in your
CONFIG.SYS file to allow a larger number
of open files. FILES=20 is the
recommended setting.
C1042 cannot open compiler intermediate file -
no such file or directory
The compiler could not create
intermediate files for use in the
compilation process because the TMP
environment variable was set to an
invalid directory or path.
C1043 cannot open compiler intermediate file
The compiler could not create
intermediate files for use in the
compilation process. The exact reason
could not be determined.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1043 (continued)
One of the following may be a solution:
■ Make sure that the environment
variable TMP points to a drive and
directory in which a file can be created.
■ Delete unneeded files in the TMP
directory.
C1044 out of disk space for compiler
intermediate file
The compiler could not create
intermediate files for use in the
compilation process because no more
space was available.
Make more space available on the disk
pointed to by the TMP environment
variable and then recompile.
C1045 floating point overflow
The compiler generated a floating-point
exception while doing constant
arithmetic on floating-point items at
compile time, as in the following
example:
float fp_val = 1.0e100;
In this example, the double-precision
constant 1.0e100 exceeds the maximum
allowable value for a floating-point
data item.
C1047 limit of 'option' exceeded at 'string'
The given option was specified too many
times. The given string is the argument
to the option that caused the error.
If the environment variable CL has been
set, options in the CL variable are read
before options specified on the command
line.
C1048 unknown option 'character' in 'option'
The given character was not a valid
letter for the option.
For example, the line
#pragma optimize("z", on)
causes the following error:
unknown option 'z' in '#pragma optimize'
C1049 invalid numerical argument 'string'
A numerical argument was expected
instead of the given string.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1050 'segment' : code segment too large
A code segment grew to within 36 bytes
of 64K during compilation.
A 36-byte pad is used because of a bug
in some 80286 chips that can cause
programs to exhibit unusual behavior
when, among other conditions, the size
of a code segment is within 36 bytes of
64K.
C1052 compiler limit : #if/#ifdef nested too
deeply
The program exceeded the maximum of 32
nesting levels for #if and #ifdef
directives.
C1053 compiler limit : struct/union nested too
deeply
A structure or union definition was
nested to more than 15 levels.
Break the structure or union into two
parts by defining one or more of the
nested structures using typedef.
C1054 compiler limit : initializers nested too
deeply
The compiler limit on the nesting of
initializers was exceeded. The limit
depends on the combination of types
being initialized and may range from 10
to 15 levels.
Simplify the data type being initialized
to reduce the levels of nesting, or
assign initial values in separate
statements after the declaration.
C1055 compiler limit : out of keys
The file being compiled contained too
many symbols.
Try to separate it into two files that
can be compiled independently.
C1056 compiler limit : out of macro expansion
space
The compiler overflowed an internal
buffer during the expansion of a macro.
Simplify the macro and/or shorten its
text.
C1057 unexpected end-of-file in macro
expansion (missing ')'?)
The compiler has encountered the end of
the source file while gathering the
arguments of a macro invocation. Usually
this is the result of a missing closing
parenthesis on the macro invocation.
C1059 compiler is out of near heap space
The compiler ran out of storage for
items that it stores in the "near"
(default data segment) heap.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1059 (continued)
One of the following may be a solution:
■ Eliminate unnecessary include files,
especially unneeded function prototypes.
■ Split the function existing at the
given line number into two or more
functions.
■ Split the current file into two or
more files and compile them separately.
C1060 compiler is out of far heap space
The compiler ran out of storage for
items that it stores in the far heap.
Usually this is the result of having too
many symbols.
One of the following may be a solution:
■ Eliminate unnecessary include files,
especially unneeded #define directives
and function prototypes.
■ Eliminate some global variables.
■ Split the current file into two or
more files and compile them separately.
■ Remove other programs or drivers
running in the system which could be
consuming significant amounts of memory.
C1061 compiler limit : blocks nested too
deeply
Nested blocks in the program exceeded
the nesting limit allowed by the
compiler.
Rewrite the program, putting one or more
nested blocks into a separate function.
C1062 error writing to preprocessor output
file
The compilation command included the /P
option to produce a preprocessor output
file, but not enough room was available
to hold the file.
C1063 compiler limit : compiler stack overflow
The program was too complex and caused
the compiler stack to overflow.
Simplify the program, making it more
modular, and recompile.
C1064 compiler limit : token overflowed
internal buffer
The compiler read an identifier that is
longer than the internal buffer used for
identifier names.
Shorten the name and recompile.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1068 cannot open file 'filename'
The compiler cannot open the given file.
There are several possible causes for
this error:
■ The file does not exist.
■ The file is marked read-only.
■ Not enough file handles exist.
C1069 write error on file 'filename'
An error occurred while the compiler
tried to write to the file. One possible
cause of this error is insufficient disk
space.
C1070 mismatched #if/#endif pair in file '
filename'
The preprocessor found the #if, #ifdef,
or #ifndef directive, but did not find a
corresponding #endif directive in the
same source file.
C1071 unexpected end-of-file found in comment
The compiler found the end of a file
while scanning a comment.
Probably a comment was not terminated.
Start at the end of the file and search
backward for the beginning of a comment.
A comment begins with /* and ends with
*/, as in
/* This is a comment */
A comment cannot be split across files.
C1072 'filename' : cannot read file
The compiler encountered an error when
trying to read a file.
Check the file-access attributes and be
sure the disk does not have a bad sector.
C1090 'segment' : data allocation exceeds 64K
The size of the named segment exceeds
64K.
This error occurs with _based allocation.
C1126 'identifier' : automatic allocation
exceeds 'size'
The space allocated for the local
variables of a function exceeded the
given limit.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
C1127 'segment' : segment redefinition
A segment was overwritten by another
with the same name.
For example, compiling in large model
with
#pragma alloc_text("TEXT", func1)
creates two segments, the default
segment module_TEXT and the specified
segment _TEXT. However, in small model,
the default segment is _TEXT, and the
specified segment _TEXT will overwrite
the default segment.
D.1.2 Compilation Error Messages
The messages listed below indicate that your program has errors. When the
compiler encounters any of the errors listed in this section, it continues
parsing the program (if possible) and outputs additional error messages.
However, no object file is produced.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2000 UNKNOWN ERROR Contact Microsoft Product
Support Services
The compiler detected an unknown error
condition.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
C2001 newline in constant
A string constant was continued onto a
second line without either a backslash
or closing and opening quotes.
To break a string constant onto two
lines in the source file:
■ End the first line with the
line-continuation character, a backslash
(\ ).
or
■ Close the string on the first line
with a double quotation mark, and open
the string on the next line with another
quotation mark.
It is not sufficient to end the first
line with \n, the escape sequence for
embedding a newline character in a
string constant.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2001 (continued)
The following two examples demonstrate
causes of this error:
printf("Hello,
world");
or
printf("Hello,\n
world");
The following two examples show ways to
correct this error:
printf("Hello,\
world");
or
printf("Hello,"
" world");
Note that any spaces at the beginning of
the next line after a line-continuation
character are included in the string
constant. Note, also, that neither
solution actually places a newline
character into the string constant. To
embed this character:
printf("Hello,\n\
world");
or
printf("Hello,\
\nworld");
or
printf("Hello,\n"
"world");
or
printf("Hello,"
"\nworld");
C2003 expected 'defined id'
An identifier was expected after the
preprocessor operator defined.
C2004 expected 'defined(id)'
An identifier was expected after the
left parenthesis following the
preprocessor operator defined.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2005 #line expected a line number, found '
token'
A #line directive lacked the required
line-number specification.
C2006 #include expected a file name, found '
token'
An #include directive lacked the
required file-name specification.
C2007 #define syntax
An identifier was expected following
#define in a preprocessing directive.
C2008 'character' : unexpected in macro
definition
The given character was found
immediately following the name of the
macro.
C2009 reuse of macro formal 'identifier'
The given identifier was used more than
once in the formal-parameter list of a
macro definition.
C2010 'character' : unexpected in macro
formal-parameter list
The given character was used incorrectly
in the formal-parameter list of a macro
definition.
C2012 missing name following '<'
An #include directive lacked the
required file-name specification.
C2013 missing '>'
The closing angle bracket (>) was
missing from an #include directive.
C2014 preprocessor command must start as first
non-white-space
Non-white-space characters appeared
before the number sign (#) of a
preprocessor directive on the same line.
C2015 too many characters in constant
A character constant contained more than
one character.
Note that an escape sequence (for
example, \t for tab) is converted to a
single character.
C2016 no closing single quotation mark
A newline character was found before the
closing single quotation mark of a
character constant.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2017 illegal escape sequence
An escape sequence appeared where one
was not expected.
An escape sequence (a backslash (\)
followed by a number or letter) may
occur only in a character or string
constant.
C2018 unknown character 'hexnumber'
The ASCII character corresponding to the
given hexadecimal number appeared in the
source file but is an illegal character.
One possible cause of this error is
corruption of the source file. Edit the
file and look at the line on which the
error occurred.
C2019 expected preprocessor directive, found '
character'
The given character followed a number
sign (#), but it was not the first
letter of a preprocessor directive.
C2021 expected exponent value, not 'character'
The given character was used as the
exponent of a floating-point constant
but was not a valid number.
C2022 'number' : too big for character
The octal number following a backslash
(\) in a character or string constant
was too large to be represented as a
character.
C2025 'identifier' : enum/struct/union type
redefinition
The given identifier had already been
used for an enumeration, structure, or
union tag.
C2026 'identifier' : member of enum
redefinition
The given identifier has already been
used for an enumeration constant, either
within the same enumeration type or
within another visible enumeration type.
C2027 use of undefined enum/struct/union '
identifier'
The given identifier referred to a
structure or union type that was not
defined.
C2028 struct/union member needs to be inside a
struct/union
Structure and union members must be
declared within the structure or union.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2028 (continued)
This error may be caused by an
enumeration declaration containing a
declaration of a structure member, as in
the following example:
enum a {
january,
february,
int march; /* Illegal
structure declaration */
};
C2030 'identifier' : struct/union member
redefinition
The identifier was used for more than
one member of the same structure or
union.
C2031 'identifier' : function cannot be
struct/union member
The given function was declared to be a
member of a structure or union.
To correct this error, use a pointer to
the function instead.
C2033 'identifier' : bit field cannot have
indirection
The given bit field was declared as a
pointer (*), which is not allowed.
C2034 'identifier' : type of bit field too
small for number of bits
The number of bits specified in the
bit-field declaration exceeded the
number of bits in the given base type.
C2035 struct/union 'identifier' : unknown size
The given structure or union had an
undefined size.
Usually this occurs when referencing a
declared but not defined structure or
union tag.
For example, the following causes this
error:
struct s_tag *ps;
ps = &my_var;
*ps = 17; /* This line causes the error
*/
C2037 left of 'operator' specifies undefined
struct/union 'identifier'
The expression before the
member-selection operator ( -> or .)
identified a structure or union type
that was not defined.
C2038 'identifier' : not struct/union member
The given identifier was used in a
context that required a structure or
union member.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2041 illegal digit 'character' for base '
number'
The given character was not a legal
digit for the base used.
C2042 signed/unsigned keywords mutually
exclusive
The keywords signed and unsigned were
both used in a single declaration, as in
the following example:
unsigned signed int i;
C2043 illegal break
A break statement is legal only within a
do, for, while, or switch statement.
C2044 illegal continue
A continue statement is legal only
within a do, for, or while statement.
C2045 'identifier' : label redefined
The label appeared before more than one
statement in the same function.
C2046 illegal case
The keyword case may appear only within
a switch statement.
C2047 illegal default
The keyword default may appear only
within a switch statement.
C2048 more than one default
A switch statement contained more than
one default label.
C2049 case value 'value' already used
The case VALUE was already used in this
switch statement.
C2050 nonintegral switch expression
A switch expression did not evaluate to
an integral value.
C2051 case expression not constant
Case expressions must be integral
constants.
C2052 case expression not integral
Case expressions must be integral
constants.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2054 expected '(' to follow 'identifier'
The context requires parentheses after
the function IDENTIFIER.
One cause of this error is omitting an
equal sign (=) on a complex
initialization, as in the following
example:
int array1[] /* Missing = */
{
1,2,3
};
C2055 expected formal-parameter list, not a
type list
An argument-type list appeared in a
function definition instead of a formal-
parameter list.
C2056 illegal expression
An expression was illegal because of a
previous error, which may not have
produced an error message.
C2057 expected constant expression
The context requires a constant
expression.
C2058 constant expression is not integral
The context requires an integral
constant expression.
C2059 syntax error : 'token'
The token caused a syntax error.
C2060 syntax error : end-of-file found
The compiler expected at least one more
token.
Some causes of this error include:
■ Omitting a semicolon, as in
int *p
■ Omitting a closing brace (}) from the
last function, as in
main() {
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2061 syntax error : identifier 'identifier'
The identifier caused a syntax error.
C2062 type 'type' unexpected
The compiler did not expect the given
type to appear here, possibly because it
already had a required type.
C2063 'identifier' : not a function
The given identifier was not declared as
a function, but an attempt was made to
use it as a function.
C2064 term does not evaluate to a function
An attempt was made to call a function
through an expression that did not
evaluate to a function pointer.
C2065 'identifier' : undefined
An attempt was made to use an identifier
that was not defined.
C2066 cast to function type is illegal
An object was cast to a function type,
which is illegal.
However, it is legal to cast an object
to a function pointer.
C2067 cast to array type is illegal
An object was cast to an array type.
C2068 illegal cast
A type used in a cast operation was not
legal for this expression.
C2069 cast of void term to nonvoid
The void type was cast to a different
type.
C2070 illegal sizeof operand
The operand of a sizeof expression was
not an identifier or a type name.
C2071 'identifier' : illegal storage class
The given storage class cannot be used
in this context.
C2072 'identifier' : initialization of a
function
An attempt was made to initialize a
function.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2075 'identifier' : array initialization
needs curly braces
There were no braces around the given
array initializer.
C2076 'identifier' : struct/union
initialization needs curly braces
There were no braces around the given
structure or union initializer.
C2077 nonscalar field initializer 'identifier'
An attempt was made to initialize a
bit-field member of a structure with a
non- scalar value.
C2078 too many initializers
The number of initializers exceeded the
number of objects to be initialized.
C2079 'identifier' uses undefined struct/union
'name'
The identifier was declared as structure
or union type name, which had not been
defined.
C2080 illegal far _fastcall function
A far _fastcall function may not be
compiled with the /Gw option, or with
the /Gq option if stack checking is
enabled.
C2082 redefinition of formal parameter '
identifier'
A formal parameter to a function was
redeclared within the function body.
C2084 function 'function' already has a body
The function has already been defined.
C2085 'identifier' : not in formal-parameter
list
The identifier was declared in a
function definition, but not in the
formal- parameter list.
A common cause of this error is the
omission of a semicolon at the end of a
function prototype, as in the following
example:
void func1( void )
void main( void )
{
}
With the semicolon missing, the compiler
assumes that func1 is a function
definition, not a prototype, and that
the function main is being defined
within the function func1. It generates
C2085 on the identifier main.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2086 'identifier' : redefinition
The given identifier was defined more
than once, or a subsequent declaration
differed from a previous one.
The following are ways to cause this
error:
int a;
char a;
main()
{
}
or
main()
{
int a;
int a;
}
However, the following does not cause
this error:
int a;
int a;
main()
{
}
C2087 'identifier' : missing subscript
The definition of an array with multiple
subscripts was missing a subscript value
for a dimension other than the first
dimension.
The following is an example of an
illegal definition:
int func(a)
char a[10][];
{ }
The following is an example of a legal
definition:
int func(a)
char a[][5];
{ }
C2090 function returns array
A function cannot return an array. It
can return a pointer to an array.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2091 function returns function
A function cannot return a function. It
can return a pointer to a function.
C2092 array element type cannot be function
Arrays of functions are not allowed.
Arrays of pointers to functions are
allowed.
C2093 cannot use address of automatic variable
as static initializer
The program tried to use the address of
an automatic variable in the initializer
of a static item, as in the following
example:
func()
{
int i;
static int *ip=&i;
.
.
.
}
C2094 label 'identifier' was undefined
The function did not contain a statement
labeled with the given identifier.
C2095 'function' : actual has type void :
parameter 'number'
An attempt was made to pass a void
argument to a function. The given number
indicates which argument was in error.
Formal parameters and arguments to
functions cannot have type void. They
can, however, have type void * (pointer
to void).
C2096 struct/union comparison illegal
Two structures or unions cannot be
compared. Individual members of
structures and unions can be compared.
C2097 illegal initialization
One of the following initializations was
attempted:
■ A variable using a nonconstant value
■ A short address with a long address
■ A local struct/union/array with a
nonconstant expression when compiling
with the /Za option
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2097 (continued)
■ An expression containing a comma
operator
■ An expression that is neither constant
nor symbolic
C2098 nonaddress expression
An address was expected as the
initialization expression.
C2099 nonconstant initializer
An initializer used a nonconstant offset.
C2100 illegal indirection
The indirection operator (*) was applied
to a nonpointer value.
C2101 '&' on constant
The address-of operator (&) did not have
an lvalue as its operand.
C2102 '&' requires lvalue
The address-of operator (&) must be
applied to an lvalue expression.
C2103 '&' on register variable
An attempt was made to take the address
of a register variable.
C2104 '&' on bit field ignored
An attempt was made to take the address
of a bit field.
C2105 'operator' needs lvalue
The given operator did not have an
lvalue operand.
C2106 'operator' : left operand must be lvalue
The left operand of the given operator
was not an lvalue.
C2107 illegal index, indirection not allowed
A subscript was applied to an expression
that did not evaluate to a pointer.
C2108 nonintegral index
A nonintegral expression was used in an
array subscript.
C2109 subscript on nonarray
A subscript was used on a variable that
was not an array.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2110 pointer + pointer
An attempt was made to add one pointer
to another using the plus (+) operator.
C2111 pointer + nonintegral value
An attempt was made to add a nonintegral
value to a pointer.
C2112 illegal pointer subtraction
An attempt was made to subtract pointers
that did not point to the same type.
C2113 pointer subtracted from nonpointer
The right operand in a subtraction
operation using the minus (-) operator
was a pointer, but the left operand was
not.
C2114 'operator' : pointer on left; needs
integral right
The left operand of the given operator
was a pointer; the right operand must be
an integral value.
C2115 'identifier' : incompatible types
An expression contained incompatible
types.
C2117 'operator' : illegal for struct/union
Structure and union type values are not
allowed with the given operator.
C2118 negative subscript
A value defining an array size was
negative.
C2119 typedef types both define indirection
Two typedef types were used to declare
an item and both typedef types had
indirection.
For example, the declaration of p in
the following example is illegal:
typedef int *p_int;
typedef short *p_short;
p_short p_int p; /* Illegal */
C2120 void illegal with all types
The void type was used in a declaration
with another type.
C2121 'operator' : bad left/right operand
The left or right operand of the given
operator was illegal for that operator.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2124 divide or mod by zero
A constant expression was evaluated and
found to have a zero denominator.
C2125 'identifier' : allocation exceeds 64K
The given item exceeded the size limit
of 64K.
C2127 parameter allocation exceeds 32K
The storage space required for the
parameters to a function exceeded the
limit of 32K.
C2128 'identifier' : huge array cannot be
aligned to segment boundary
The given huge array was large enough to
cross two segment boundaries, but could
not be aligned to both boundaries to
prevent an individual array element from
crossing a boundary.
If the size of a huge array causes the
array to cross two boundaries, the size
of each array element must be a power of
two, so that a whole number of elements
will fit between two segment boundaries.
C2129 static function 'function' not found
A forward reference was made to a static
function that was never defined.
C2130 #line expected a string containing the
file name, found 'token'
The optional token following the line
number on a #line directive was not a
string.
C2131 more than one memory attribute
More than one of the keywords _near,
_far, _huge, or _based were applied to
an item, as in the following example:
typedef int _near nint;
nint _far a; /* Illegal */
C2132 syntax error : unexpected identifier
An identifier appeared in a
syntactically illegal context.
C2133 'identifier' : unknown size
An attempt was made to declare an
unsized array as a local variable.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2134 'identifier' : struct/union too large
The size of a structure or union
exceeded the 64K compiler limit.
C2136 'function' : prototype must have
parameter types
A function prototype declarator had
formal-parameter names, but no types
were provided for the parameters.
A formal parameter in a function
prototype must either have a type or be
represented by an ellipsis (...) to
indicate a variable number of arguments
and no type checking.
One cause of this error is a misspelling
of a type name in a prototype that does
not provide the names of formal
parameters.
C2137 empty character constant
The illegal empty-character constant ('')
was used.
C2138 unmatched close comment '*/'
The compiler detected an open-comment
delimiter (/*) without a matching
close-comment delimiter (*/). This error
usually indicates an attempt to use
illegal nested comments.
C2139 type following 'identifier' is illegal
Two types were used in the same
declaration.
For example:
int double a;
C2140 argument cannot be function type
A function was declared as a formal
parameter of another function, as in the
following example:
int func1(a)
int a( );
C2141 value out of range for enum constant
An enumeration constant had a value
outside the range of values allowed for
type int.
C2142 ellipsis requires three periods
The compiler detected a token consisting
of two periods ( .. ) and assumed that
an ellipsis ( ... ) was intended.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2143 syntax error : missing 'token1' before '
token2'
The compiler expected token1 to appear
before token2.
This message may appear if a required
closing brace, right parenthesis, or
semicolon is missing.
C2144 syntax error : missing 'token' before
type 'type'
The compiler expected the given token to
appear before the given type name.
This message may appear if a required
closing brace, right parenthesis, or
semicolon is missing.
C2145 syntax error : missing 'token' before
identifier
The compiler expected the given token to
appear before an identifier.
This message may appear if a semicolon
(;) does not appear after the last
declaration of a block.
C2146 syntax error : missing 'token' before
identifier 'identifier'
The compiler expected the given token to
appear before the given identifier.
C2147 unknown size
An attempt was made to increment an
index or pointer to an array whose base
type has not yet been declared.
C2148 array too large
An array exceeded the maximum legal size
of 64K.
Either reduce the size of the array, or
declare it with _huge.
C2149 'identifier' : named bit field cannot
have 0 width
The given named bit field had zero width.
Only unnamed bit fields are allowed to
have zero width.
C2150 'identifier' : bit field must have type
int, signed int, or unsigned int
The ANSI C standard requires bit fields
to have types of int, signed int, or
unsigned int. This message appears only
when compiling with the /Za option.
C2151 more than one language attribute
More than one keyword specifying a
calling convention for a function was
given.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2152 'identifier' : pointers to functions
with different attributes
An attempt was made to assign a pointer
to a function declared with one calling
convention (_cdecl, _fortran, _pascal,
or _fastcall) to a pointer to a function
declared with a different calling
convention.
C2153 hex constants must have at least 1 hex
digit
The hexadecimal constants 0x, 0X and \x
are illegal. At least one hexadecimal
digit must follow the "x" or "X".
C2154 'segment' : does not refer to a segment
name
A _based allocated variable must be
allocated in a segment unless it is
extern and uninitialized.
C2156 pragma must be outside function
A pragma that must be specified at a
global level, outside a function body,
occurred within a function.
For example, the following causes this
error:
main()
{
#pragma optimize("l", on)
}
C2157 'function' : must be declared before use
in pragma list
The function name in the list of
functions for an alloc_text pragma has
not been declared prior to being
referenced in the list.
C2158 'identifier' : is a function
The given identifier was specified in
the list of variables in a same_seg
pragma but was previously declared as a
function.
C2159 more than one storage class specified
A declaration contained more than one
storage class, as in
extern static int i;
C2160 ## cannot occur at the beginning of a
macro definition
A macro definition began with a
token-pasting operator (##), as in
#define mac(a,b) ##a
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2161 ## cannot occur at the end of a macro
definition
A macro definition ended with a
token-pasting operator (##), as in
#define mac(a,b) a##
C2162 expected macro formal parameter
The token following a stringizing
operator (#) was not a formal-parameter
name.
For example:
define print(a) printf(#b)
C2163 'function' : not available as an
intrinsic function
A function specified in the list of
functions for an intrinsic or function
pragma is not one of the functions
available in intrinsic form.
C2164 'function' : intrinsic function not
declared
The given function was not declared
before being used in an intrinsic pragma.
This error appears only when compiling
with the /Oi option.
C2165 'keyword' : cannot modify pointers to
data
The _fortran, _pascal, _cdecl, or
_fastcall keyword was used illegally to
modify a pointer to data, as in the
following example:
char _pascal *p;
C2166 lvalue specifies 'const' object
An attempt was made to modify an item
declared with const type.
C2167 'function' : too many actual parameters
for intrinsic function
A reference to the intrinsic function
name contained too many actual
parameters.
C2168 'function' : too few actual parameters
for intrinsic function
A reference to the intrinsic function
name contained too few actual parameters.
C2169 'function' : intrinsic function, cannot
be defined
An attempt was made to provide a
function definition for a function
already declared as an intrinsic.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2170 'identifier' : not declared as a
function, cannot be intrinsic
The intrinsic pragma was used for an
item other than a function, or for a
function that does not have an intrinsic
form.
C2171 'operator' : illegal operand
The given unary operator was used with
an illegal operand type, as in the
following example:
int (*fp)();
double d,d1;
.
.
.
fp++;
d = ~d1;
C2172 'function' : actual is not a pointer :
parameter 'number'
An attempt was made to pass an argument
that was not a pointer to a function
that expected a pointer. The given
number indicates which argument was in
error.
C2173 'function' : actual is not a pointer :
parameter 'number1', parameter list '
number2'
An attempt was made to pass a nonpointer
argument to a function that expected a
pointer.
This error occurs in calls that return a
pointer to a function. The first number
indicates which argument was in error;
the second number indicates which
argument list contained the invalid
argument.
C2174 'function' : actual has type void :
parameter 'number1', parameter list '
number2'
An attempt was made to pass a void
argument to a function. Formal
parameters and arguments to functions
cannot have type void. They can, however,
have type void * (pointer to void).
This error occurs in calls that return a
pointer to a function. The first number
indicates which argument was in error;
the second number indicates which
argument list contained the invalid
argument.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2175 'function' : unresolved external
The given function is not defined in the
source file, or built into the QuickC
programming environment, or present in
the Quick library (if any) that was
loaded.
This error occurs only for single-module
programs created in the QuickC
environment. To solve this problem,
either define the function in the source
file, load a Quick library containing
the function, or (if the function is a
standard C library function) create a
program list for the program.
This error can also occur if you are
using graphics functions and did not
build GRAPHICS.LIB or PGCHART.LIB into
your combined library during the SETUP
operation. If this is the case, add
GRAPHICS.LIB or PGCHART.LIB to your
program list and rebuild your program.
C2176 static huge data not supported
Declarations of _huge arrays are not
supported in QuickC. Declare a _huge
pointer to the data item, and allocate
such an array dynamically using halloc(
).
C2177 constant too big
Information was lost because a constant
value was too large to be represented in
the type to which it was assigned.
C2178 'identifier' : storage class for
same_seg variables must be extern
The given variable was specified in a
same_seg pragma, but it was not declared
with extern storage class.
C2179 'identifier' : was used in same_seg, but
storage class is no longer extern
The given variable was specified in a
same_seg pragma, but it was redeclared
with a storage class other than extern.
C2180 controlling expression has type 'void'
The controlling expression in an if,
while, for, or do statement had void
type. The expression was either a
function with void return type or an
expression cast to void.
C2182 'identifier' : has type 'void'
The given variable was declared with the
void keyword. The void keyword can be
used only in function declarations.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2185 'identifier' : illegal _based allocation
A _based allocated variable that
explicitly has extern storage class and
is uninitialized may not have a base of
any of the following:
■ (_segment) & var
■ _segname("_STACK")
■ (_segment)_self
■ void
If the variable does not explicitly have
extern storage class or it is
uninitialized, then its base must use
_segname("string") where string is any
segment name or reserved segment name
except "_STACK".
C2187 cast of near function pointer to far
function pointer
An attempt was made to cast a near
function pointer as a far function
pointer.
C2189 #error : 'string'
An #error directive was encountered. The
string is the descriptive text supplied
in the directive.
C2193 'identifier' : already in a segment
A variable in the same_seg pragma has
already been allocated in a segment,
using _based.
C2194 'segment' : is a text segment
The given text segment was used where a
data, const, or bss segment was expected.
C2195 'segment' : is a data segment
The given data segment was used where a
text segment was expected.
C2196 /ML cannot be used with floating point
The /ML command-line option requires
alternate math. QuickC does not support
alternate math. The /ML option is
allowed with only when no floating-point
code is used.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2200 'function' : function has already been
defined
A function name passed as an argument in
an alloc_text pragma has already been
defined.
C2201 'function' : storage class must be
extern
A function declaration appears within a
block, but the function is not declared
extern. This causes an error if the /Za
option is in effect.
For example, the following causes this
error when compiled with /Za:
main()
{
static int func1();
}
C2205 'identifier' : cannot initialize extern
block-scoped variables
A variable with extern storage class may
not be initialized in a function.
C2206 'function' : typedef cannot be used for
function definition
A typedef was used to define a function
type.
For example:
typedef int functyp();
functyp func1
{ }
C2207 'member' in struct/union 'tag' has a
zero-sized array
The given member in the given structure
or union contains an array without a
subscript or with a zero subscript. Such
an array is legal only as the last
member of a structure or union.
C2208 no members defined using this type
An enum, struct, or union was defined
without any members. This is an error
only when compiling with the /Za option;
otherwise, it is a warning.
C2209 type cast in _based construct must be
(_segment)
The only type allowed within a cast in a
_based declarator is (_segment).
C2210 'identifier' : must be near/far data
pointer
The base in a _based declarator may not
be an array, a function, or a _based
pointer.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2211 (_segment) applied to function
identifier 'function'
The item cast in a _based declarator
must not be a function.
C2212 'identifier' : _based not available for
functions/pointers to functions
Functions cannot be _based allocated.
Use the alloc_text pragma.
C2213 'identifier' : illegal argument to
_based
A symbol used as a base must have type
_segment or be a near or far pointer.
C2214 pointers based on void require the use
of :>
A _based pointer based on void cannot be
dereferenced. Use the base (:>) operator
to create an address that can be
dereferenced.
C2215 :> operator only for objects based on
void
The right operand of the base (:>)
operator must be a pointer based on void,
as in
char _based(void) *cbvpi
C2216 'attribute1' may not be used with '
attribute2'
The given function attributes are
incompatible.
Some combinations of attributes that
cause this error are
■ _saveregs and _interrupt
■ _fastcall and _saveregs
■ _fastcall and _interrupt
■ _fastcall and _export
C2217 'attribute1' must be used with '
attribute2'
The first function attribute requires
the second attribute to be used.
Some causes for this error include the
following:
■ An _interrupt function explicitly
declared as near. Interrupt functions
must
be far.
■ An _interrupt function or a function
with a variable number of arguments,
when that function is declared with the
_fortran, _pascal, or _fastcall
attribute. Functions declared with the
_interrupt attribute or with a variable
number of arguments must use the C
calling conventions. Remove the
_fortran, _pascal, or _fastcall
attribute from the function declaration.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2218 type in _based construct must be void
The only type allowed within a _based
construct is void.
C2219 syntax error : type qualifier must be
after '*'
Either const or volatile appeared where
a type or qualifier is not allowed, as
in
int (const *p);
C2220 warning treated as error - no object
file generated
When the compiler option /WX is used,
the first warning generated by the
compiler causes this error message to be
displayed.
Either correct the condition that caused
the warning, or compile at a lower
warning level or without /WX.
C2221 '.' : left operand points to
struct/union, use '->'
The left operand of the member-selection
(.) operator must be a struct/union type.
It cannot be a pointer to a struct/union
type.
This error usually means that a '->'
operator must be used.
C2222 '->' : left operand has struct/union
type, use '.'
The left operand of the '->' operator
must be a pointer to a struct/union type.
It cannot be a struct/union type.
This error usually means that a
member-selection (.) operator must be
used.
C2223 left of '-> member' must point to
struct/union
The left operand of the '->' operator is
not a pointer to a struct/union type.
This error can occur when the left
operand is an undefined variable.
Undefined variables have type int.
C2224 left of '.member' must have struct/union
type
The left operand of the member-selection
(.) operator is not a struct/union type.
This error can occur when the left
operand is an undefined variable.
Undefined variables have type int.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2225 'tagname' : first member of struct is
unnamed
The struct with the given tag started
with an unnamed member (an alignment
member). All struct definitions must
start with a named member.
C2400 in-line syntax error in 'context', found
'token'
The given token caused a syntax error
within the given context.
C2401 'identifier' : register must be base in
'context'
The register used within an indirect
memory operand must be a base register
in this context.
C2402 'identifier' : register must be index in
'context'
The register used within an indirect
memory operand must be an index register
in this context.
C2403 'identifier' : register must be
base/index in 'context'
The register used within an indirect
memory operand must be either a base or
index register in this context.
C2404 'identifier' : illegal register in '
context'
This register in this context is illegal.
C2405 illegal short forward reference with
offset
Short forward references must refer only
to a label. An additional offset cannot
be used.
C2406 'identifier' : name undefined in '
context'
The identifier used with the SIZE or
LENGTH operator, or as a specifier with
the member-selection operator (.), was
not defined.
C2407 illegal float register in 'context'
An NDP register was specified in an
illegal context.
C2408 illegal type on PTR operator in 'context
'
The first argument of the PTR operator
was not a legal type specification.
C2409 illegal type used as operator in '
context'
A type was used within the given context
as an operator.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2410 'identifier' : ambiguous member name in
'context'
The given identifier within the given
context is a member of more than one
structure or union.
Use a struct/union specifier in the
operand that caused the error. A struct/
union specifier is an identifier with
structure or union type, either a
typedef name or a variable of the same
type as the structure or union being
referenced. The specifier token must be
the left operand of the first
member-selection (.) operator on the
operand.
C2411 'identifier' : illegal struct/union
member in 'context'
Either the given identifier used with
this context is not a member of a
visible structure or union, or the
identifier is not a member of the
structure or union specified with the
member-selection (.) operator.
C2412 'identifier' : case insensitive label
redefined
The given label was defined more than
once within the current function. Change
the spelling of the label and its
references.
C2413 'token' : illegal align size
The alignment size used with the ALIGN
directive was either missing or outside
the valid range.
C2414 illegal number of operands
The operating code does not support the
number of operands used.
Check an assembly reference manual to
determine the correct number of operands
for this instruction.
It is possible that the instruction is
supported with a different number of
operands on a later processor. The
problem can be solved by compiling with
the /G1 or /G2 option, but then only
machines with the newer processor will
be able to execute the extended
instruction.
C2415 improper operand type
The operating code does not use operands
of this type.
Check an assembly reference manual to
determine the correct types of operands
for this instruction.
It is possible that the instruction is
supported with additional operand types
on a later processor. The problem can be
solved by compiling with the /G1 or /G2
option, but then only machines with the
newer processor will be able to execute
the extended instruction.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2416 'identifier' : illegal opcode for
processor
The instruction is legal on a later
processor but not on the current
processor.
Check an assembly reference manual to
determine which processors support this
operating code.
The problem can be solved by compiling
with the /G1 or /G2 option, but then
only machines with the newer processor
will be able to execute the extended
instruction.
C2417 divide by zero in 'context'
The second argument to the division (/)
operator used within the given context
is zero.
C2418 'identifier' : not in a register
An in-line assembler instruction
referenced a variable with register
storage class that has not actually been
allocated in a register.
To correct this, remove the register
keyword from the variable definition,
and make sure that this instruction is
legal with a memory operand.
C2419 mod by zero in 'context'
The second argument to the MOD operator
used within the given context is zero.
C2420 'identifier' : illegal symbol in '
context'
The given identifier is illegal within
the given context.
C2421 PTR operator used with register in '
context'
The PTR operator must not be used with a
register operand.
C2422 illegal segment override in 'context'
An illegal segment override was used
within the given context.
C2424 'token' : improper expression in '
context'
The given token was used to form an
improper expression within the given
context.
C2425 'token' : nonconstant expression in '
context'
The given token was used to form a
nonconstant expression within the given
context.
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
C2426 'token' : illegal operator in 'context'
The given token must not be used as an
operator within the given context. For
example, index operators may not be
nested.
C2427 'identifier' : jump referencing label is
out of range
A branch to the specified label is
farther than allowed.
For example, if the following condition
causes this error:
jz label1
inc AX
.
.
.
label1: inc CX
then the error can be corrected by
either removing excess code between the
branch and the label or inverting the
jump, as in
jnz label2
jmp label1
label2: inc AX
.
.
.
label1: inc CX
C2429 'label' : illegal far label reference
FAR PTR may not be used on jumps or
calls to labels. Far references to
functions are allowed as long as the
function has been declared.
D.1.3 Warning Messages
The messages listed in this section indicate potential problems but do not
hinder compiling and linking. The number in parentheses at the end of a
warning message description gives the minimum warning level that must be set
for the message to appear.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4000 UNKNOWN WARNING Contact Microsoft
Product Support Services
The compiler detected an unknown error
condition.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package. (1)
C4001 nonstandard extension used - 'extension'
The given nonstandard language extension
was used when the /Ze option was
specified.
If the /Za option has been specified,
this condition generates a syntax error.
(1,4)
C4002 too many actual parameters for macro '
identifier'
The number of actual arguments specified
with the given identifier was greater
than the number of formal parameters
given in the macro definition of the
identifier.
The additional actual parameters are
collected but ignored during expansion
of the macro. (1)
C4003 not enough actual parameters for macro '
identifier'
The number of actual arguments specified
with the given identifier was less than
the number of formal parameters given in
the macro definition of the identifier.
When a formal parameter is referenced in
the definition and the corresponding
actual parameter has not been provided,
empty text is substituted in the macro
expansion. (1)
C4004 missing ')' after 'defined'
The closing parenthesis was missing from
an #if defined phrase.
The compiler assumes a right parenthesis,
after the first identifier it finds. It
then attempts to compile the remainder
of the line, which may result in another
warning or error. (1)
The following example causes this
warning and a fatal error:
#if defined( ID1 ) || ( ID2 )
The compiler assumed a right parenthesis
after ID1, then found a mismatched
parenthesis in the remainder of the line.
The following avoids this problem:
#if defined( ID1 ) || defined( ID2 )
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4005 'identifier' : macro redefinition
The given identifier was defined twice.
The compiler assumed the new macro
definition.
To eliminate the warning, either remove
one of the definitions or use an #undef
directive before the second definition.
This warning is caused in situations
where a macro is defined both on the
command line and in the code with a
#define directive. (1)
C4006 #undef expected an identifier
The name of the identifier whose
definition was to be removed was not
given with the #undef directive. The
#undef was ignored. (1)
C4007 'identifier' : must be 'attribute'
The attribute of the given function was
not explicitly stated. The compiler
forced the attribute.
For example, the function main must have
the _cdecl attribute. (2)
C4008 'identifier' : _fastcall attribute on
data ignored
The _fastcall attribute on the given
data identifier was ignored. (2)
C4009 string too big, trailing characters
truncated
A string exceeded the compiler limit of
2,047 on string size. The excess
characters at the end of the string were
truncated.
To correct this problem, break the
string into two or more strings. (1)
C4011 identifier truncated to 'identifier'
Only the first 31 characters of an
identifier are significant. The
characters after the limit were
truncated.
This may mean that two identifiers that
are different before truncation may have
the same identifier name after
truncation. (1)
C4015 'identifier' : bit-field type must be
integral
The given bit field was not declared as
an integral type. The compiler assumed
the base type of the bit field to be
unsigned.
Bit fields must be declared as unsigned
integral types. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4016 'function' : no function return type,
using int as default
The given function had not yet been
declared or defined, so the return type
was unknown. A default return type of
int was assumed. (3)
C4017 cast of int expression to far pointer
A far pointer represents a full
segmented address. On an 8086/8088
processor, casting an int value to a far
pointer may produce an address with a
meaningless segment value.
The compiler extended the int expression
to a four-byte value. (1)
C4020 'function' : too many actual parameters
The number of arguments specified in a
function call was greater than the
number of parameters specified in the
function prototype or function
definition.
The extra parameters were passed
according to the calling convention used
on the function. (1)
C4021 'function' : too few actual parameters
The number of arguments specified in a
function call was less than the number
of parameters specified in the function
prototype or function definition.
Only the provided actual parameters are
passed. If the called function
references a variable that has not been
passed, the results are undefined and
may be unexpected. (1)
C4022 'function' : pointer mismatch :
parameter 'number'
The pointer type of the given parameter
was different from the pointer type
specified in the argument-type list or
function definition.
The parameter will be passed without
change. Its value will be interpreted as
a pointer within the called function. (1)
C4023 'function' : _based pointer passed to
unprototyped function: parameter 'number
'
When in a near data model, only the
offset portion of a _based pointer is
passed to an unprototyped function. If
the function expects a far pointer, the
resulting code will be wrong. In any
data model, if the function is defined
to take a _based pointer with a
different base, the resulting code may
be unpredictable.
If a prototype is used before the call,
the call will be generated correctly. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4024 'function' : different types : parameter
'number'
The type of the given parameter in a
function call did not agree with the
type given in the argument-type list or
function definition.
The parameter will be passed without
change. The function will interpret the
parameter's type as the type expected by
the function. (1)
C4026 function declared with formal argument
list
The function was declared to take
arguments, but the function definition
did not declare formal parameters.
Subsequent calls to this function will
assume the function takes no arguments.
(1)
C4027 function declared without formal
argument list
The function was declared to take no
arguments (the argument-type list
consisted of the word void), but formal
parameters were declared in the function
definition, or arguments were given in a
call to the function. Subsequent calls
to this function will assume the
function takes parameters of the types
of the given formal arguments. (1)
C4028 parameter 'number' declaration different
The type of the given parameter did not
agree with the corresponding type in the
argument-type list or with the
corresponding formal parameter.
The original declaration was used. (1)
C4029 declared parameter list different from
definition
The types in the argument list given in
a function declaration did not agree
with the types of the formal parameters
given in the function definition.
The parameter list of the definition is
used instead of the parameter list of
the declaration. (1)
C4030 first parameter list longer than the
second
A function was declared more than once
with different parameter lists.
The first declaration was used. (1)
C4031 second parameter list is longer than the
first
A function was declared more than once
with different parameter lists.
The first declaration was used. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4032 unnamed struct/union as parameter
The type of the structure or union being
passed as an argument was not named, so
the declaration of the formal parameter
cannot use the name and must declare the
type.
The parameter was commented out.
This warning occurs only when using the
/Zg option for generating function
prototypes. (1)
C4033 function must return a value
A function is expected to return a value
unless it is declared as void.
An undefined value will be returned when
this function is called. (1)
C4034 sizeof returns 0
The sizeof operator was applied to an
operand that yielded a size of zero.
This warning is informational. (1)
C4035 'function' : no return value
A function declared to return a value
did not do so.
An undefined value will be returned when
this function is called. (3)
C4040 memory attribute on 'identifier' ignored
The _near, _far, _huge, or _based
keyword has no effect in the declaration
of the given identifier and is ignored.
One cause of this warning is a huge
array that is not declared globally.
Declare huge arrays outside of main. (1)
C4042 'identifier' : has bad storage class
The storage class specified for
identifier cannot be used in this
context. (1)
The default storage class for this
context was used in place of the illegal
class:
■ If identifier was a function, the
compiler assumed extern class.
■ If identifier was a formal parameter
or local variable, the compiler assumed
auto class.
■ If identifier was a global variable,
the compiler assumed the variable was
declared with no storage class.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4044 _huge on 'identifier' ignored, must be
an array
The compiler ignored the _huge memory
attribute on the given identifier. Only
arrays may be declared with the _huge
memory attribute. On pointers, _huge
must be used as a modifier, not as a
memory attribute. (1)
C4045 'identifier' : array bounds overflow
Too many initializers were present for
the given array. The excess initializers
were ignored. (1)
C4047 'operator' : different levels of
indirection
An expression involving the specified
operator had inconsistent levels of
indirection.
If both operands are of arithmetic type,
or if both are not (such as array or
pointer), then they are used without
change. If one is near and one is far,
the near operand is extended using the
value of DS. If one is arithmetic and
one is not, the arithmetic operand is
converted to the type of the other
operand. (1)
For example, the following code causes
this warning but is compiled without
change:
char **p;
char *q;
p = q; /* Warning */
C4048 array's declared subscripts different
An expression involved pointers to
arrays of different size.
The pointers were used without
conversion. (1)
C4049 'operator' : indirection to different
types
The pointer expressions used with the
given operator had different base types.
The expressions were used without
conversion. (1)
For example, the following code causes
this warning:
struct ts1 *s1;
struct ts2 *s2;
s2 = s1; /* Warning */
C4050 'operator' : different code attributes
The function-pointer expressions used
with operator had different code
attributes. The attribute involved is
either _export or_loadds.
This is a warning and not an error,
because _export and _loadds affect only
entry sequences and not calling
conventions. (4)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4051 type conversion, possible loss of data
Two data items in an expression had
different base types, causing the type
of one item to be converted. During the
conversion, a data item was truncated.
(2)
C4053 at least one void operand
An expression with type void was used as
an operand.
The expression was evaluated using an
undefined value for the void operand. (1)
C4054 insufficient memory may affect
optimization
Not enough memory was available to do
all requested optimizations. This
message appears if available memory is
within 64K of the absolute minimum that
will accommodate the executable file. (1)
C4056 floating-point overflow
The compiler generated a floating-point
exception while doing constant
arithmetic on floating-point items at
compile time. (2)
For example:
float fp_val = 1.0e100;
In this example, the floating-point
constant 1.0e100 exceeds the maximum
allowable value for a double-precision
data item.
C4058 address of automatic (local) variable
taken, DS!= SS
The program was compiled with the
default data segment (DS) not equal to
the stack segment (SS), and the program
tried to point to an automatic (local)
variable with a near pointer.
Dereferencing a pointer to that address
will give an unpredictable result. (1)
C4059 segment lost in conversion
The conversion of a far pointer (a full
segmented address) or _based pointer to
a near pointer (a segment offset) or
_based pointer resulted in the loss of
the segment address. (2)
C4061 long/short mismatch in argument :
conversion supplied
The base types of the actual and formal
arguments of a function were different.
The actual argument is converted to the
type of the formal parameter. (1)
C4062 near/far mismatch in argument :
conversion supplied
The pointer sizes of the actual and
formal arguments of a function were
different. The actual argument is
converted to the type of the formal
parameter. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4063 'function' : function too large for
post-optimizer
Not enough space was available to
optimize the given function. (2)
One of the following may be a solution:
■ Recompile with fewer optimizations.
■ Divide the function into two or more
smaller functions.
C4065 recoverable heap overflow in
post-optimizer - some optimizations may
be missed
Some optimizations were skipped because
not enough space was available for
optimization. (2)
One of the following may be a solution:
■ Recompile with fewer optimizations.
■ Divide the function into two or more
smaller functions.
C4066 local symbol-table overflow - some local
symbols may be missing in listings
The listing generator ran out of heap
space for local variables, so the source
listing may not contain symbol-table
information for all local variables. (2)
C4067 unexpected characters following '
directive' directive - newline expected
Extra characters following a
preprocessor directive were ignored.
This warning appears only when compiling
with the /Za option. (1)
For example, the following code causes
this warning:
#endif NO_EXT_KEYS
To remove the warning, compile with /Ze
or use comment delimiters:
#endif /* NO_EXT_KEYS */
C4068 unknown pragma
The compiler did not recognize a pragma
and ignored it. (1)
C4069 conversion of near pointer to long
integer
The compiler converted a 16-bit near
pointer to a long integer by extending
the high-order word with the current
data-segment value, not with zeros. (2)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4071 'function' : no function prototype given
The given function was called before the
compiler found the corresponding
function prototype.
The function will be called using the
default rules for calling a function
without a prototype. (2)
C4072 'function' : no function prototype on
_fastcall function
A _fastcall function was called without
first being prototyped.
Functions that are _fastcall should be
prototyped to guarantee that the
registers assigned at each point of call
are the same as the registers assumed
when the function is defined. A function
defined in the new ANSI style is a
prototype.
A prototype must be added when this
warning appears, unless the function
takes no arguments or takes only
arguments that cannot be passed in the
general-purpose registers. (1)
C4073 scoping too deep, deepest scoping merged
when debugging
Declarations appeared at a static
nesting level greater than 13. As a
result, all declarations beyond this
level will seem to appear at the same
level. (1)
C4076 'type' : may be used on integral types
only
The signed or unsigned type modifier was
used with a nonintegral type. The given
qualifier was ignored. (1)
The following example causes this
warning:
unsigned double x;
C4077 unknown check_stack option
An unknown option was given with the old
form of the check_stack pragma. With the
old form, the argument to the pragma
must be empty, +, or -. (1)
For example, the following causes this
warning:
#pragma check_stack yes
The following code corrects this
situation:
#pragma check_stack + /* Old form */
or
#pragma check_stack (on) /* New form */
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4078 case constant 'value' too big for the
type of switch expression
A value appearing in a case statement
was larger than the size of the type in
the switch expression. The compiler
converted the case value to the type of
the switch expression.
A problem can occur when two case
constants have different values before
being cast but the same value afterward.
(1)
C4079 unexpected token 'token'
An unexpected separator token was found
in the argument list of a pragma.
The remainder of the pragma was ignored.
(1)
C4080 expected identifier for segment name,
found 'token'
The first argument in the argument list
for the alloc_text pragma is missing a
segment name. This happens if the first
token in the argument list is not an
identifier.
The pragma was ignored. (1)
C4081 expected a comma, found 'token'
A comma was missing between two
arguments of a pragma.
The pragma was ignored. (1)
C4082 expected an identifier, found 'token'
An identifier was missing from the
argument list.
The remainder of the pragma was ignored.
(1)
C4083 expected '(', found 'token'
A left parenthesis was missing from a
pragma's argument list.
The pragma was ignored. (1)
The following example causes this
warning:
#pragma check_pointer on)
C4084 expected a pragma keyword, found 'token'
The token following #pragma was not
recognized as a directive.
The pragma was ignored. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4084 (continued)
The following example causes this
warning:
#pragma (on)
C4085 expected [on | off]
The pragma expected an on or off
parameter, but the specified parameter
was unrecognized or missing.
The pragma was ignored. (1)
C4086 expected [1 | 2 | 4]
The pragma expected a parameter of
either 1, 2, or 4, but the specifed
parameter was unrecognized or missing.
(1)
C4087 'function' : declared with void
parameter list
The given function was declared as
taking no parameters, but a call to the
function specified actual parameters.
The extra parameters were passed
according to the calling convention used
on the function. (1)
The following example causes this
warning:
int f1(void);
f1(10);
C4088 'function' : pointer mismatch :
parameter 'number', parameter list '
number'
The argument passed to the given
function had a different level of
indirection from the given parameter in
the function definition.
The parameter will be passed without
change. Its value will be interpreted as
a pointer within the called function. (1)
C4089 'function' : different types : parameter
'number', parameter list 'number'
The argument passed to the given
function did not have the same type as
the given parameter in the function
definition.
The parameter will be passed without
change. The function will interpret the
parameter's type as the type expected by
the function. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4090 different const/volatile qualifiers
A pointer to an item declared as const
was assigned to a pointer that was not
declared as const. As a result, the
const item pointed to could be modified
without being detected.
The expression was compiled without
modification. (1)
The following example causes this
warning:
const char *p = "abcde";
int str(char *s);
str(p);
C4091 no symbols were declared
The compiler detected an empty
declaration, as in the following
example:
int ;
The declaration was ignored. (2)
C4092 untagged enum/struct/union declared no
symbols
The compiler detected an empty
declaration using an untagged structure,
union, or enumerated variable.
The declaration was ignored. (2)
For example, the following code causes
this warning:
struct {
.
.
.
};
C4093 unescaped newline in character constant
in inactive code
The constant expression of an #if, #elif,
#ifdef, or #ifndef preprocessor
directive evaluated to 0, making the
code that follows inactive. Within that
inactive code, a newline character
appeared within a set of single or
double quotation marks.
All text until the next double quotation
mark was considered to be within a
character constant. (3)
C4095 expected ')', found 'token'
More than one argument was given for a
pragma that can take only one argument.
The compiler assumed the expected
parenthesis and ignored the remainder of
the line. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4096 'attribute1' must be used with '
attribute2'
The use of attribute2 requires the use
of attribute1.
For example, using a variable number of
arguments (...) requires that _cdecl be
used. Also, _interrupt functions must be
_far and _cdecl.
The compiler assumed attribute1 for the
function. (2)
C4098 void function returning a value
A function declared with a void return
type also returned a value.
A function was declared with a void
return type but was defined as a value.
The compiler assumed the function
returns a value of type int. (1)
C4100 'identifier' : unreferenced formal
parameter
The given formal parameter was never
referenced in the body of the function
for which it was declared.
This warning is informational. (3)
C4101 'identifier' : unreferenced local
variable
The given local variable was never used.
This warning is informational. (4)
C4102 'label' : unreferenced label
The given label was defined but never
referenced.
This warning is informational. (3)
C4104 'identifier' : near data in same_seg
pragma, ignored
The given near variable was specified in
a same_seg pragma.
The identifier was ignored. (1)
C4105 'identifier' : code modifiers only on
function or pointer to function
The given identifier was declared with a
code modifier that can be used only with
a function or function pointer.
The code modifier was ignored. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4106 pragma requires integer between 1 and
127
An integer constant in the range 1-127
must be specified with the page and skip
pragmas.
The compiler assumed 1 was specified. (1)
C4107 pragma requires integer between 15 and
255
An integer constant in the range 15-255
must be specified with the pagesize
pragma.
The compiler assumed 63 was specified.
(1)
C4108 pragma requires integer between 79 and
132
An integer constant in the range 79-132
must be specified with the linesize
pragma.
The compiler assumed 79 was specified.
(1)
C4109 unexpected identifier 'identifier'
The pragma contained an unexpected token.
The pragma was ignored. (1)
C4110 unexpected token 'int constant'
The pragma contained an unexpected
integer constant.
The pragma was ignored. (1)
C4111 unexpected token 'string'
The pragma contained an unexpected
string.
The pragma was ignored. (1)
C4112 macro name 'name' is reserved, 'command'
ignored
The given command attempted to define or
undefine the predefined macro name or
the preprocessor operator 'defined'. The
given command is displayed as either
#define or #undef, even if the attempt
was made using command-line options.
The command was ignored. (1)
C4113 function parameter lists differed
A function pointer was assigned to a
function pointer, but the parameter
lists of the functions do not agree.
The expression was compiled without
modification. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4114 same type qualifier used more than once
A type qualifier (const, volatile,
signed, or unsigned) was used more than
once in the same type.
The second occurrence of the qualifier
was ignored. (1)
C4115 'tag' : type definition in formal
parameter list
The given tag was used to define a
struct, union, or enum in the formal
parameter list of a function.
The compiler assumed the definition was
at the global level. (1)
C4116 (no tag) : type definition in formal
parameter list
A struct, union, or enum type with no
tag was defined in the formal parameter
list of a function.
The compiler assumed the definition was
at the global level. (1)
C4118 pragma not supported
A pragma that the compiler does not
support was used. The pragma was ignored.
This warning appears at level 1, except
on #pragma comment( ), which causes a
level 3 warning. (1, 3)
C4119 different bases 'name1' and 'name2'
specified
The _based pointers in the expression
have different symbolic bases. There may
be truncation or loss in the code
generated. (1)
C4120 _based/unbased mismatch
The expression contains a conversion
between a _based pointer and another
pointer that is unbased. Some
information may have been truncated.
This warning commonly occurs when a
_based pointer is passed to a function
that accepts a near or far pointer. (1)
C4123 different base expressions specified
The expression contains a conversion
between _based pointers, but the base
expressions of the _based pointers are
different. Some of the _based
conversions may be unexpected. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4124 _fastcall with stack checking is
inefficient
The _fastcall keyword is used for
generating fast code, but stack checking
causes slower code to be generated.
Use the /Gs option or the check_stack
pragma to turn off stack checking when
using _fastcall.
This warning is informational and is
issued only for the first function
declared under these conditions. (1)
C4125 decimal digit terminates octal escape
sequence
An octal escape sequence in a character
or string constant was terminated with a
decimal digit.
The compiler evaluated the octal number
without the decimal digit, and assumed
the decimal digit was a character. (4)
The following example causes this
warning:
char array1[] = "\709";
If the digit 9 was intended as a
character and was not a typing error,
correct the example as follows:
char array[] = "\0709"; /* String
containing "89" */
C4126 'flag' : unknown memory model flag
The flag used with the /A option was not
recognized and was ignored. (1)
C4127 conditional expression is constant
The controlling expression of an if
statement or while loop evaluates to a
constant.
As a result, the code in the body of the
if statement or while loop is either
always executed or never executed.
This warning is informational. (4)
C4128 storage-class specifier after type
A storage-class specifier (auto, extern,
register, static) appears after a type
in a declaration. The compiler assumed
the storage class specifier occurred
before the type.
New-style code places the storage-class
specifier first. (4)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4129 'character' : unrecognized character
escape sequence
The character following a backslash in a
character or string constant was not
recognized as a valid escape sequence.
As a result, the backslash is ignored
and not printed, and the character
following the backslash is printed.
To print a single backslash (\), specify
a double backslash (\\). (4)
C4130 'operator' : logical operation on
address of string constant
The operator was used with the address
of a string literal. Unexpected code was
generated. (4)
For example, the following code causes
this warning:
char *pc;
pc = "Hello";
if (pc == "Hello") ...
The if statement compares the value
stored in the pointer pc to the
address of the string "Hello", which is
separately allocated each time it occurs
in the code. It does not compare the
string pointed to by pc with the
string "Hello".
To compare strings, use the strcmp
function.
C4131 'function' : uses old-style declarator
The function declaration or definition
is not a prototype. (4)
New-style function declarations are in
prototype form.
■ Old style:
int addrec( name, id )
char *name;
int id;
{ }
■ New style:
int addrec( char *name, int id )
{ }
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4132 'object' : const object should be
initialized
The value of a const object cannot be
changed, so the only way to give the
const object a value is to initialize it.
It is not possible to assign a value to
object. (4)
C4135 conversion between different integral
types
Information was lost between two
integral types. (4)
For example, the following code causes
this warning:
int intvar;
long longvar;
intvar = longvar;
If the information is merely interpreted
differently, this warning is not given,
as in the following example:
unsigned uintvar = intvar;
C4136 conversion between different floating
types
Information was lost or truncated
between two floating types. (4)
For example, the following code causes
this warning:
double doublevar;
float floatvar;
floatvar = doublevar;
Note that unsuffixed floating-point
constants have type double, so the
following code causes this warning:
floatvar = 1.0;
If the floating-point constant should be
treated as float type, use the F (or
f ) suffix on the constant to prevent
the following warning:
floatvar = 1.0F;
C4137 'function' : no return value from
floating-point function
The given function had no return
statement.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4137 (continued)
A long double function returns its value
on the floating-point stack or the
emulated stack. If the function does not
return a value, a run-time
floating-point stack underflow may occur.
(1)
C4138 '*/' found outside of comment
The compiler found a closing comment
delimiter (*/) without a preceding
opening delimiter. It assumed a space
between the asterisk (*) and the forward
slash ( / ). (1)
The following example causes this
warning:
int */*Comment*/ptr;
In this example, the compiler assumed a
space before the first comment delimiter
( /* ), and issued the warning but
compiled the line normally. To remove
the warning, insert the assumed space.
Usually, the cause of this warning is an
attempt to nest comments.
To comment out sections of code that may
contain comments, enclose the code in an
#if/#endif block and set the controlling
expression to zero, as in
#if 0
int my_variable; /* Declaration
currently not needed */
#endif
C4139 'hexnumber' : hex escape sequence is out
of range
A hex escape sequence appearing in a
character or string constant was too
large to be converted to a character.
If in a string constant, the compiler
cast the low byte of the hexadecimal
number to a char. If in a char constant,
the compiler made the cast and then sign
extended the result. If in a char
constant and compiled with the /J option,
the compiler cast the value to an
unsigned char. (1)
For example, '\x1ff' is out of range for
a character. Note that the following
code causes this warning:
printf("\x7Bell\n");
The number 7Be is a legal hex number,
but is too large for a character. To
correct this example, use three hex
digits:
printf("\x007Bell\n");
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4140 'function' redefined : preceding
references may be invalid
The compiler issues this warning if a
function definition changes between
incremental compilations.
References previous to the redefinition
use the previous definition. Subsequent
references use the new definition. (1)
For example:
main()
{
func1 ();
}
int func1 ()
{ }
If this program is compiled with the /Gi
option, and later the func1 definition
is changed to long func1, the compiler
issues this message to warn that calls
to func1 may be of the wrong type.
Be sure that function calls reference
the correct type; if not, recompile
without /Gi. To avoid the problem
altogether, use function prototypes.
C4185 near call to 'function' in different
segment
The given function was specified in an
alloc_text pragma without being declared
with _far, and then was called from the
text segment.
The compiler generated a near call.
Although this is a warning message
rather than an error message, the
resulting code will not work correctly.
(1)
C4186 string too long - truncated to 40
characters
The string argument for a title or
subtitle pragma exceeded the maximum
allowable length and was truncated. (1)
C4200 local variable 'identifier' used without
having been initialized
A reference was made to a local variable
that had not been assigned a value. As a
result, the value of the variable is
unpredictable.
This warning is given only when
compiling with global register
allocation turned on (/Oe). (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4201 local variable 'identifier' may be used
without having been initialized
A reference was made to a local variable
that might not have been assigned a
value. As a result, the value of the
variable may be unpredictable.
This warning is given only when
compiling with the global register
allocation turned on (/Oe). (3)
C4202 unreachable code
The flow of control can never reach the
indicated line.
This warning is given only when
compiling with one of the global
optimizations (/Oe, /Og, or /Ol). (4)
C4203 'function' : function too large for
global optimizations
The named function was too large to fit
in memory and be compiled with the
selected optimization. The compiler did
not perform any global optimizations
(/Oe, /Og, or /Ol). Other /O
optimizations, such as /Oa and /Oi, are
still performed. (1)
One of the following may remove this
warning:
■ Recompile with fewer optimizations.
■ Divide the function into two or more
smaller functions.
C4204 'function' : in-line assembler precludes
global optimizations
The use of in-line assembly in the named
function prevented the specified global
optimizations (/Oe, /Og, or /Ol) from
being performed. (3)
C4205 statement has no effect
The indicated statement will have no
effect on the program execution. (4)
Some examples of statements with no
effect:
1;
a + 1;
b == c;
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4206 assignment within conditional expression
The test value in a conditional
expression was the result of an
assignment.
This warning is informational.
An assignment has a value (the value at
the left side of the assignment) that
can be used legally in another
expression, including a test expression.
However, the intention may have been to
test a relation instead of an assignment.
(4)
For example, the following line, which
causes this warning, assigns b to a
and compares the value of a with 0:
if (a = b) ...
However, the following line tests
whether a and b are equal:
if (a == b) ...
C4209 comma operator within array index
expression
The value used as an index into an array
was the last one of multiple expressions
separated by the comma operator.
An array index legally may be the value
of the last expression in a series of
expressions separated by the comma (,)
operator. However, the intent may have
been to use the expressions to specify
multiple indexes into a multidimensional
array. (4)
For example, the following line, which
causes this warning, is legal in C, and
specifies the index c into array a:
a[b,c]
However, the following line uses both b
and c as indexes into a two-
dimensional array:
a[b][c]
C4300 insufficient memory to process debugging
information
The program was compiled with the /Zi
option, but not enough memory was
available to create the required
debugging information. (2)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4300 (continued)
One of the following may be a solution:
■ Split the current file into two or
more files and compile them separately.
■ Remove other programs or drivers
running in the system which could be
consuming significant amounts of memory.
C4301 loss of debugging information caused by
optimization
Some optimizations, such as code motion,
cause references to nested variables to
be moved. The information about the
level at which the variables are
declared may be lost. As a result, all
declarations will seem to be at nesting
level 1. (2)
C4323 potential divide by 0
The second operand in a divide operation
evaluated to zero at compile time,
giving undefined results. (3)
The 0 operand may have been generated by
the compiler, as in the following
example:
func1() { int i,j,k; i /= j && k; }
C4324 potential mod by 0
The second operand in a remainder
operation evaluated to zero at compile
time, giving undefined results. (3)
C4401 'identifier' : member is bit field
The identifier is a bit field. A
bit-field member cannot be accessed
within in-line assembly code. The last
packing boundary before the bit-field
member was used. (1)
C4402 must use PTR operator
A type was used on an operand without a
PTR operator.
The compiler assumed a PTR operator was
used. (1)
C4403 illegal PTR operator
A type was used on an operand with the
PTR operator.
The compiler assumed a PTR operator was
not used. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4404 period on directive ignored
The period preceding the directive was
ignored. (3)
C4405 'identifier' : identifier is reserved
word
The identifier is a reserved word. Use
of it in this way may cause
unpredictable results. (1)
C4406 operand on directive ignored
The directive does not take any operands,
but an operand was specified.
The compiler ignored the operand. (1)
C4407 operand size conflict
The size of the operands should match
but did not.
If the first operand was a register or
the second operand as immediate, the
size of the first operand was used.
Otherwise, the size of the second
operand was used. (2)
C4409 illegal instruction size
The instruction did not have a form with
the specified size. The smallest legal
size was used. (1)
C4410 illegal size for operand
One of the operands on this instruction
had an incorrect size. The smallest
legal size for the operand was used. (1)
C4411 'identifier' : symbol resolves to
displacement register
The identifier is a local symbol that
resolves to a displacement register and
therefore may be used on an operand with
another symbol.
This warning is informational. (1)
C4413 'function' : redefined, preceding
references may be invalid
The compiler issues this warning if a
function definition changes between
incremental compilations. (1)
Number Warning Message
────────────────────────────────────────────────────────────────────────────
C4413 (continued)
The following example illustrates this:
main()
{
func1();
}
int func1()
{
}
If this program is compiled with the /Gi
option, then the func1 definition is
changed to long func1, and the compiler
issues this message to warn that calls
to func1 may be of the wrong type.
Be sure that function calls reference
the correct type. If not, recompile
without /Gi. To avoid the problem
altogether, use function prototypes.
C4414 'function' : short jump to function
converted to near
Short jumps generate a one-byte
instruction. The instruction includes a
short offset that represents the
distance between the jump and the
function definition. The compiler must
generate a special record for the jump,
which requires the JMP instruction to be
either NEAR or FAR, but not SHORT. The
compiler made the conversion. (3)
For example, the following code causes
this warning:
main()
{
_asm jmp SHORT main
}
D.1.4 Compiler Limits
To operate the Microsoft QuickC Compiler, you must have sufficient disk
space available for the compiler to create temporary files used in
processing. The space required is approximately two times the size of the
source file.
Table D.1 summarizes the limits imposed by the QuickC Compiler. If your
program exceeds one of these limits, an error message will inform you of the
problem.
Table D.1 Limits Imposed by the QuickC Compiler
╓┌──────────────┌────────────────────────┌───────────────────────────────────╖
Program Item Description Limit
────────────────────────────────────────────────────────────────────────────
Constants Maximum size of a ─
constant is determined
Program Item Description Limit
────────────────────────────────────────────────────────────────────────────
constant is determined
by its type; see Table
4.1, "Basic Data Types,"
in the C for Yourself
manual for details
Identifiers Maximum length of an 31 bytes (additional characters
identifier are discarded)
Declarations Maximum level of 10 levels
nesting for
structure/union
definitions
Preprocessor Maximum size of a 1,024 bytes
directives macro definition
Maximum length of an 256 bytes
actual preprocessor
Program Item Description Limit
────────────────────────────────────────────────────────────────────────────
actual preprocessor
argument
Maximum number of 20 paths
search paths for
include files
Maximum number of macro 30 definitions
definitions in
/D options
Maximum number of 31 parameters
formal parameters to a
macro definition
Maximum length of an 256 bytes
actual preprocessor
argument
Program Item Description Limit
────────────────────────────────────────────────────────────────────────────
Maximum level of 32 levels
nesting for #if, #ifdef,
and
#ifndef directives
Maximum level of 10 levels
nesting for include
files, counting the
open
source file
Maximum number of 20 paths
search paths for
include files
────────────────────────────────────────────────────────────────────────────
The compiler does not set explicit limits on the length of a string or on
the number and complexity of declarations, definitions, and statements in an
individual function or in a program. If the compiler encounters a function
or program that is too large or too complex to be processed, it produces an
error message to that effect.
D.2 Command-Line Errors
Messages that indicate errors on the command line used to invoke the
compiler have one of the following formats:
command line error D2xxx: messagetext Error
command line warning D4xxx: messagetext Warning
The compiler issues a warning message and, if possible, continues
processing. In some cases, command-line errors are fatal and the compiler
terminates processing.
D.2.1 Command-Line Error Messages
When the QCL compiler encounters any of the errors listed in this section,
it terminates, producing no object file.
Number Command-Line Message
────────────────────────────────────────────────────────────────────────────
D2000 UNKNOWN ERROR Contact Microsoft Product
Support Services
An unexpected error occurred in the QCL
driver.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
D2002 conflict in memory-model specification
More than one memory-model specification
was encountered.
The following is an example of a command
line that causes this error:
qcl /AS /AM program.c
If the CL environment variable is
currently set for a memory-model option,
and the CL command is given with another
memory-model option, this error will
occur.
Number Command-Line Message
────────────────────────────────────────────────────────────────────────────
D2003 missing source file name
The QCL command line contains options
but no source-file name.
Note that the QCL command by itself,
with no options or source-file
specification, will print a brief
message about the command-line syntax.
D2008 limit of 'option' exceeded at 'string'
The limit of the /D, /I, or /U option
was exceeded.
Reduce the number of identifiers you
define or undefine, or the number of
directories to search for include files,
to less than 30 each.
D2011 only one floating-point option allowed
Both of the floating-point options, /FPi
and /FPi87, were specified.
Specify only one of the floating-point
options.
D2012 too many linker flags on command line
More than 128 options were passed to the
linker.
D2013 incomplete model specification
A customized memory model was
incompletely specified with the /Astring
option.
Two types of options begin with /A:
■ The /Astring customized memory-model
option requires three letters in the
string. The letters specify the
code-pointer size, data-pointer size,
and data-segment setup attributes of the
memory model.
■ The /Ax option for specifying a
standard memory model requires one
uppercase letter. If the letter is
lowercase, the option is interpreted as
an incomplete specification of a
customized memory model. For example:
qcl /As
A single lowercase letter can be used
only if it is a segment setup option,
and is used in combination with a
standard memory model.
D2016 'option1' and 'option2' are incompatible
Two incompatible command-line options
were specified.
Number Command-Line Message
────────────────────────────────────────────────────────────────────────────
D2018 cannot open linker response file
The compiler cannot open a response file
to specify the object-file names for the
linker.
Set the TMP environment variable to a
valid drive and directory, where the
compiler can create a temporary response
file for the linker.
D2019 cannot overwrite the source/object file,
'filename'
The input-file name was specified as an
output-file name. The compiler will not
allow the source or object file to be
overwritten by one of the compiler
output files.
D2020 'option' option requires extended
keywords to be enabled (/Ze)
Either the /Gr or /Gc option was
specified on the command line in
combination with the /Za option, which
disables extended keywords.
The /Gr option requires the extended
keyword _fastcall to be enabled, and the
/Gc option requires the extended
keywords _pascal and _fortran. Extended
keywords are enabled by default, or if
the /Ze option is specified.
D2021 invalid numerical argument 'number'
A number greater than 65,534 was
specified as a numerical argument.
D2022 cannot open help file, QCL.MSG
The /HELP option was given, but the file
containing the command-line options was
not in the current directory or in any
of the directories specified by the PATH
environment variable.
D2027 could not execute 'component'
The QCL driver was unable to execute one
of the compiler components or the linker,
possibly for one of the following
reasons:
■ There is not enough memory to load the
component.
■ The given component is for the wrong
operating system.
■ The given component is corrupted.
D2031 too many flags/files on command line
There are more than 128 arguments
combined from the command line and the
CL environment variable.
Reduce the number of arguments. You can
do this by compiling fewer files at one
time.
D.2.2 Command-Line Warning Messages
The messages listed in this section indicate potential problems, but the
errors do not hinder compilation and linking.
Number Command-Line Warning Message
────────────────────────────────────────────────────────────────────────────
D4000 UNKNOWN WARNING Contact Microsoft
Product Support Services
An unexpected warning occurred in the
QCL driver.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
D4002 ignoring unknown flag 'option'
The command-line option specified by
option is not recognized by the QCL
driver.
D4003 different processors selected for code
generation
More than one /Gn option was specified
with conflicting specifications. The
last processor selector on the command
line is used.
For example, the following command line
can cause this error:
qcl /G2 /G0 program.c
In this example, the /G0 processor
selector is used.
D4005 could not locate 'component'; Please
enter new file name (full path) or
CTRL+C to quit:
The QCL driver was unable to find the
program specified by component in the
search path.
D4007 /C ignored (must also specify /P or /E
or /EP)
The /C option must be used in
conjunction with one of the preprocessor
output flags (/P, /E, or /EP).
Note that the /C option is different
from the /c option. Arguments to the QCL
driver are case sensitive.
Number Command-Line Warning Message
────────────────────────────────────────────────────────────────────────────
D4009 threshold only for far/huge data,
ignored
The /Gt option cannot be used in memory
models that have near data pointers. It
can be used only in compact, large, and
huge models, or a customized memory
model that uses far data pointers.
D4014 invalid value 'number1' for 'option';
default 'number2' is used
An invalid value was given for an option
that only accepts certain specific
values. The value actually used by the
compiler is number2.
The following example can cause this
warning:
qcl /Zp3 program.c
In this example, 3 is an invalid value.
In the /Zpn option, the value n of may
be 1, 2, or 4 only.
D4020 unsupported switch 'option'
The given option is not supported by QCL.
D.3 Run-Time Errors
Run-time error messages fall into four categories:
1. Floating-point exceptions generated by the 8087/287 hardware or the
emulator.
2. Error messages generated by the run-time library to notify you of
serious errors.
3. Error messages generated by program calls to error-handling routines
in the C run-time library─the abort, assert, and perror routines.
These routines print an error message to standard error output
whenever the program calls the given routine.
4. Error messages generated by calls to math routines in the C run-time
library. On error, the math routines return an error value, and some
print a message to the standard error output. See the online help or
the Microsoft C Run-Time Library Reference (sold separately) for
descriptions of the math routines and corresponding error messages.
D.3.1 Math Error Messages
The error messages below correspond to floating-point exceptions generated
by the 8087/287/387 hardware. Refer to the Intel documentation for your
processor for a detailed discussion of hardware exceptions. These errors may
also be detected by the floating-point emulator or alternate math library.
Using C's default 8087/287 control-word settings, the following exceptions
are masked and do not occur:
Exception Default Masked Action
────────────────────────────────────────────────────────────────────────────
Denormal Exception masked
Underflow Result goes to 0.0
Inexact Exception masked
The following errors do not occur with code generated by the Microsoft
QuickC Compiler or provided in the standard C library:
Square root
Stack underflow
Unemulated
A floating-point error message takes the following general form:
run-time error M61nn: MATH
- floating-point error: messagetext
The floating-point exceptions are listed and described below.
Number Math Error Message
────────────────────────────────────────────────────────────────────────────
M6101 invalid
An invalid operation occurred. This
error usually occurs when operating on a
NAN (not a number) or infinity.
This error terminates the program with
exit code 129.
Number Math Error Message
────────────────────────────────────────────────────────────────────────────
M6102 denormal
A very small floating-point number was
generated which may no longer be valid
due to loss of significance. Denormals
are normally masked, causing them to be
trapped and operated upon.
This error terminates the program with
exit code 130.
M6103 divide by 0
An attempt was made to divide by zero in
a floating-point operation.
This error terminates the program with
exit code 131.
M6104 overflow
An overflow occurred in a floating-point
operation.
This error terminates the program with
exit code 132.
M6105 underflow
An underflow occurred in a
floating-point operation. An underflow
is normally masked, with the
underflowing value replaced by 0.0.
This error terminates the program with
exit code 133.
M6106 inexact
Loss of precision occurred in a
floating-point operation. This exception
is normally masked because almost any
floating-point operation can cause loss
of precision.
This error terminates the program with
exit code 134.
M6107 unemulated
An attempt was made to execute an
8087/287/387 instruction that is invalid
or is not supported by the emulator.
This error terminates the program with
exit code 135.
M6108 square root
The operand in a square-root operation
was negative.
This error terminates the program with
exit code 136.
Note that the sqrt function in the C
run-time library checks the argument
before performing the operation and
returns an error value if the operand is
negative.
Number Math Error Message
────────────────────────────────────────────────────────────────────────────
M6110 stack overflow
A floating-point expression caused a
stack overflow on the 8087/287/387
coprocessor or the emulator.
Stack-overflow exceptions are trapped up
to a limit of seven levels in addition
to the eight levels normally supported
by the 8087/287/387 coprocessor.
This error terminates the program with
exit code 138.
M6111 stack underflow
A floating-point operation resulted in a
stack underflow on the 8087/287/387
coprocessor or the emulator.
This error is often caused by a call to
a long double function that does not
return a value. For example, the
following gives this error when compiled
and run:
long double ld() {};
main ()
{
ld();
}
This error terminates the program with
exit code 139.
D.3.2 Run-Time Error Messages
The following messages may be generated at run time when your program has
serious errors.
A run-time error message takes the following general form:
run-time error R6nnn- messagetext
Number Run-Time Error Message
────────────────────────────────────────────────────────────────────────────
R6000 stack overflow
The program has run out of stack space.
This can occur when a program uses a
large amount of local data or is heavily
recursive.
Recompile using the /F compiler option,
or relink using the linker /STACK option
to allocate a larger stack.
Number Run-Time Error Message
────────────────────────────────────────────────────────────────────────────
R6001 null pointer assignment
The contents of the NULL segment have
changed in the course of program
execution. The program has written to
this area, usually by an inadvertent
assignment through a null pointer.
The NULL segment is a location in low
memory that is not normally used. The
contents of the NULL segment are checked
upon program termination. If a change is
detected, the error message is printed
and the exit code is 255.
Note that the program can contain null
pointers without causing this error. The
error appears only when the program
writes to memory through a null pointer.
It reflects a potentially serious error
in the program. Although a program that
produces this error may appear to
operate correctly, it may cause problems
in the future and may fail to run in a
different operating environment.
R6002 floating-point support not loaded
The program needs the floating-point
library, but the library was not loaded.
This occurs in two situations:
1. The program was compiled or linked with an option (such as /FPi87)
that required an 8087/287/387 coprocessor, but the program was run on
a machine that did not have a coprocessor installed.
Either recompile the program with the /FPi option or install a
coprocessor.
2. A format string for one of the routines in the printf or scanf
families contains a floating-point format specification, and there are
no floating-point values or variables in the program. The compiler
attempts to minimize the size of a program by loading floating-point
support only when necessary. Floating-point format specifications
within format strings are not detected, so the necessary
floating-point routines are not loaded.
Use a floating-point argument to correspond to the floating-point
format specification, or perform a floating-point assignment elsewhere
in the program. This causes floating-point support to be loaded.
R6003 integer divide by 0
An attempt was made to divide an integer
by 0, giving an undefined result.
Number Run-Time Error Message
────────────────────────────────────────────────────────────────────────────
R6005 not enough memory on exec
Not enough memory remained to load the
program being spawned.
This error occurs when a child process
spawned by one of the exec library
routines fails and the operating system
could not return control to the parent
process.
R6006 invalid format on exec
The file to be executed by one of the
exec functions was not in the correct
format for an executable file.
This error occurs when a child process
spawned by one of the exec library
routines fails and the operating system
could not return control to the parent
process.
R6007 invalid environment on exec
During a call to one of the exec
functions, the operating system found
that the child process was given an
invalid environment block.
This error occurs when a child process
spawned by one of the exec library
routines fails and the operating system
could not return control to the parent
process.
R6008 not enough space for arguments
There was enough memory to load the
program but not enough room for the argv
vector.
There are several ways to correct this
problem:
■ Increase the amount of memory
available to the program.
■ Reduce the number and size of
command-line arguments.
■ Reduce the environment size, removing
unnecessary variables.
■ Rewrite either the _setargv or the
_setenvp routine.
R6009 not enough space for environment
There was enough memory to load the
program but not enough room for the envp
vector.
Number Run-Time Error Message
────────────────────────────────────────────────────────────────────────────
R6009 (continued)
There are several ways to correct this
problem:
■ Increase the amount of memory
available to the program.
■ Reduce the number and size of
command-line arguments.
■ Reduce the environment size, removing
unnecessary variables.
■ Rewrite either the _setargv or the
_setenvp routine.
R6010 abnormal program termination
This error is displayed by the abort( )
routine. The program terminates with
exit code 3, unless an abort( ) signal
handler has been defined by using the
signal( ) function.
R6012 illegal near-pointer use
A null near pointer was used in the
program.
This error occurs only if pointer
checking is in effect. Pointer checking
is set with the /Zr option or the
check_pointer pragma.
R6013 illegal far-pointer use
An out-of-range far pointer was used in
the program.
This error occurs only if pointer
checking is in effect. Pointer checking
is set with the /Zr option or the
check_pointer pragma.
D.4 QLINK Error Messages
This section lists and describes error messages generated by the QuickC
linker (QLINK), and the special incremental linker (ILINK) that is invoked
when you compile QuickC programs with the /Gi or /Li option. Note that in
most cases, QuickC invokes QLINK if ILINK fails.
Fatal errors cause the linker to stop execution. Fatal error messages have
the following format:
location : error L1 xxx : messagetext
For QLINK, fatal error numbers range from L1000 to L1199. For ILINK, the
incremental linker, fatal error numbers range from L1200 to L1249.
Nonfatal errors indicate problems in the executable file. QLINK produces the
executable file. Nonfatal error messages have the following format:
location : error L2xxx : messagetext
Nonfatal errors generated by ILINK are numbered from L1250 to L1299.
Warnings indicate possible problems in the executable file. QLINK produces
the executable file. Warnings have the following format:
location : warning L4xxx : messagetext
Warning numbers less than L4200 apply to QLINK. Those numbers greater than
L4200 apply to ILINK.
In all three kinds of messages, location is the input file associated with
the error, or QLINK if there is no input file. If the input file is an
.OBJ or .LIB file, and a module name is associated with the error, the
module name is enclosed in parentheses, as shown in the following examples:
SLIBC.LIB(_file)
MAIN.OBJ(main.c)
TEXT.OBJ
The following error messages may appear when you link object files.
D.4.1 Fatal Error Messages
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1001 'option' : option name ambiguous
A unique option name did not appear
after the option indicator.
An option is specified by a
forward-slash indicator ( / ) and a name.
The name can be specified by an
abbreviation of the full name, but the
abbreviation must be unambiguous.
For example, many options begin with the
letter N, so the following command
causes this error:
QLINK /N main;
L1002 'option' : unrecognized option name
An unrecognized name followed the option
indicator.
An option is specified by a
forward-slash indicator ( / ) and a name.
The name can be specified by a legal
abbreviation of the full name.
For example, the following command
causes this error:
QLINK /NODEFAULTLIBSEARCH main
L1003 /QUICKLIB, /EXEPACK incompatible
The linker cannot be given both the /Q
option and the /E option.
L1004 'value' : invalid numeric value
An incorrect value appeared for one of
the linker options. For example, a
character string was given for an option
that requires a numeric value.
L1005 'option' : packing limit exceeds 65536
bytes
The value supplied with the /PACKCODE or
/PACKDATA option exceeds the limit of
65,536 bytes.
L1006 /STACKSIZE : stack size exceeds 65535
bytes
The value given as a parameter to the
/STACK option exceeds the maximum
allowed.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1007 /OVERLAYINTERRUPT : interrupt number
exceeds 255
A number greater than 255 was given as
the /OVERLAYINTERRUPT option value.
Check The MS-DOS Encyclopedia or other
DOS technical manual for information
about interrupts.
L1008 /SEGMENTS : segment limit set too high
The /SEGMENTS option specified a limit
on the number of definitions of logical
segments that was impossible to satisfy.
L1009 'value' : CPARMAXALLOC : illegal value
The value specified in the /CPARMAXALLOC
option was not in the range 1-65,535.
L1020 no object modules specified
No object-file names were specified to
the linker.
L1021 cannot nest response files
A response file occurred within a
response file.
L1022 response line too long
A line in a response file was longer
than 255 characters.
L1023 terminated by user
CTRL+C was entered.
L1024 nested right parentheses
The contents of an overlay were typed
incorrectly on the command line.
L1025 nested left parentheses
The contents of an overlay were typed
incorrectly on the command line.
L1026 unmatched right parenthesis
A right parenthesis was missing from the
contents specification of an overlay on
the command line.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1027 unmatched left parenthesis
A left parenthesis was missing from the
contents specification of an overlay on
the command line.
L1030 missing internal name
An IMPORTS statement specified an
ordinal in the module-definition file
without including the internal name of
the routine.
The name must be given if an ordinal is
specified.
L1031 module description redefined
A DESCRIPTION statement in the
module-definition file was specified
more than once.
L1032 module name redefined
The module name was specified more than
once (in a NAME or LIBRARY statement).
L1040 too many exported entries
The program exceeded the limit of 65,535
exported names.
L1041 resident-name table overflow
The size of the resident-name table
exceeds 65,535 bytes.
An entry in the resident-name table is
made for each exported routine
designated RESIDENTNAME, and consists of
the name plus three bytes of information.
The first entry is the module name.
Reduce the number of exported routines
or change some to nonresident status.
L1042 nonresident-name table overflow
The size of the nonresident-name table
exceeds 65,535 bytes.
An entry in the nonresident-name table
is made for each exported routine not
designated RESIDENTNAME, and consists of
the name plus three bytes of information.
The first entry is the DESCRIPTION
statement.
Reduce the number of exported routines
or change some to resident status.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1043 relocation table overflow
More than 32,768 long calls, long jumps,
or other long pointers appeared in the
program.
Try replacing long references with short
references where possible, and recreate
the object module.
L1044 imported-name table overflow
The size of the imported-names table
exceeds 65,535 bytes.
An entry in the imported-names table is
made for each new name given in the
IMPORTS section, including the module
names, and consists of the name plus one
byte.
Reduce the number of imports.
L1045 too many TYPDEF records
An object module contained more than 255
TYPDEF records. These records describe
communal variables.
This error can appear only with programs
produced by the Microsoft FORTRAN
Compiler or other compilers that support
communal variables. (TYPDEF is a DOS
term. It is explained in the Microsoft
MS-DOS Programmer's Reference and in
other reference books on DOS.)
L1046 too many external symbols in one module
An object module specified more than the
limit of 1,023 external symbols.
Break the module into smaller parts.
L1047 too many group, segment, and class names
in one module
The program contained too many group,
segment, and class names.
Reduce the number of groups, segments,
or classes. Recreate the object file.
L1048 too many segments in one module
An object module had more than 255
segments.
Split the module or combine segments.
L1049 too many segments
The program had more than the maximum
number of segments.
Use the /SEGMENTS option when linking to
specify the maximum legal number of
segments. The range of possible settings
is 0-3,072. The default is 128.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1050 too many groups in one module
QLINK encountered more than 21 group
definitions (GRPDEF) in a single module.
Reduce the number of group definitions
or split the module. (Group definitions
are explained in the Microsoft MS-DOS
Programmer's Reference and in other
reference books on DOS.)
L1051 too many groups
The program defined more than 20 groups,
not counting DGROUP.
Reduce the number of groups.
L1052 too many libraries
An attempt was made to link with more
than 32 libraries.
Combine libraries, or use modules that
require fewer libraries.
L1053 out of memory for symbol table
The program had more symbolic
information (such as public, external,
segment, group, class, and file names)
than could fit in available memory.
Try freeing memory by linking from the
DOS command level instead of from a
makefile or the QuickC environment.
Otherwise, combine modules or segments
and try to eliminate as many public
symbols as possible.
L1054 requested segment limit too high
QLINK did not have enough memory to
allocate tables describing the number of
segments requested. The number of
segments is the default of 128 or the
value specified with the /SEGMENTS
option.
Try linking again by using the /SEGMENTS
option to select a smaller number of
segments (for example, use 64 if the
default was used previously), or free
some memory by eliminating resident
programs or shells.
L1056 too many overlays
The program defined more than 63
overlays.
L1057 data record too large
An LEDATA record (in an object module)
contained more than 1,024 bytes of data.
This is a translator error. (LEDATA is a
DOS term explained in the Microsoft
MS-DOS Programmer's Reference and in
other DOS reference books.)
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1057 (continued)
Note which translator (compiler or
assembler) produced the incorrect object
module. Please report the circumstances
of the error to Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L1061 out of memory for /INCREMENTAL
The linker ran out of memory when trying
to process the additional information
required for ILINK support.
Disable incremental linking.
L1062 too many symbols for /INCREMENTAL
The program had more symbols than can be
stored in the .SYM file.
Reduce the number of symbols or disable
incremental linking.
L1063 out of memory for CodeView information
The linker was given too many object
files with debug information, and the
linker ran out of space to store them.
Reduce the number of object files that
have full debug information by compiling
some files with either /Zd instead of
/Zi or with no CodeView option at all.
L1064 out of memory
The linker was not able to allocate
enough memory from the operating system
to link the program.
Reduce the size of the program in terms
of code, data, and symbols.
L1070 'segment' : segment size exceeds 64K
A single segment contained more than 64K
of code or data.
Try changing the memory model to use far
code or data as appropriate. If the
program is in C, use the /NT option or
the #pragma alloc_text to build smaller
segments.
L1071 segment _TEXT larger than 65520 bytes
This error is likely to occur only in
small-model C programs, but it can occur
when any program with a segment named
_TEXT is linked using the /DOSSEG option
of the QLINK command.
Small-model C programs must reserve code
addresses 0 and 1; this range is
increased to 16 for alignment purposes.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1071 (continued)
Try compiling and linking using the
medium or large model. If the program is
in C, use the /NT option or the #pragma
alloc_text to build smaller segments.
L1072 common area longer than 65536 bytes
The program had more than 64K of
communal variables. This error can occur
in a multi-module program when the total
size of communal variables for all
modules exceeds 64K.
L1074 'group' : group larger than 64K
The given group exceeds the limit of
65,535 bytes.
Reduce the size of the group, or remove
any unneeded segments from the group.
Refer to the map file for a listing of
segments.
L1078 file-segment alignment too small
The segment-alignment size given with
the /ALIGNMENT:number option was too
small.
Try increasing the number.
L1080 cannot open list file
The disk or the root directory was full.
Delete or move files to make space.
L1081 out of space for run file
The disk on which the .EXE file was
being written was full.
Free more space on the disk and restart
the linker.
L1083 cannot open run file
One of the following has occurred:
■ The disk or the root directory was
full. Delete or move files to make space.
■ Another process has opened the file as
a read-only file.
L1084 cannot create temporary file
The disk or root directory was full.
Free more space in the directory and
restart the linker.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1085 cannot open temporary file
The disk or the root directory was full.
Delete or move files to make space.
L1086 scratch file missing
An internal error has occurred.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L1087 unexpected end-of-file on scratch file
The disk with the temporary
linker-output file was removed.
L1088 out of space for list file
The disk where the listing file was
being written is full.
Free more space on the disk and restart
the linker.
L1089 'filename' : cannot open response file
The linker could not find the specified
response file.
Check that the name of the response file
is spelled correctly.
L1090 cannot reopen list file
The original disk was not replaced at
the prompt.
Restart the linker.
L1091 unexpected end-of-file on library
The disk containing the library was
probably removed.
Replace the disk containing the library
and run the linker again.
L1092 cannot open module-definition file
The linker could not open the
module-definition file specified on the
command line or in the response file.
L1093 'filename' : object not found
One of the object files specified in the
linker input was not found.
Restart the linker and specify the
object file.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1094 'filename' : cannot open file for
writing
The linker was unable to open the file
with write permission.
Check file permissions.
L1095 'filename' : out of space on file
The linker ran out of disk space for the
specified output file.
Delete or move files to make space.
L1100 stub .EXE file invalid
The file specified in the STUB statement
is not a valid real-mode executable file.
L1101 invalid object module
One of the object modules was invalid.
Check that the correct version of the
linker is being used.
If the error persists after recompiling,
note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L1102 unexpected end-of-file
An invalid format for a library was
encountered.
L1103 attempt to access data outside segment
bounds
A data record in an object module
specified data extending beyond the end
of a segment. This is a translator error.
Note which translator (compiler or
assembler) produced the incorrect object
module and the circumstances in which it
was produced. Please report this error
to Microsoft Corporation by following
the instructions in the Microsoft
Product Assistance Request form at the
back of one of your manuals.
L1104 'filename' : not valid library
The specified file was not a valid
library file. This error causes the
linker to abort.
L1105 invalid object due to aborted
incremental compile
Delete the object file, recompile the
program, and relink.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1113 unresolved COMDEF; internal error
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of one of your manuals.
L1114 file not suitable for /EXEPACK; relink
without
For the linked program, the size of the
packed load image plus packing overhead
was larger than that of the unpacked
load image.
Relink without the /EXEPACK option.
L1115 'option' : option incompatible with
overlays
The given option is not compatible with
overlays.
Remove the option or else do not use
overlaid modules.
L1123 'segment' : segment defined for both 16-
and 32-bit
This error can occur when a segment is
defined as a 32-bit assembly-language
module and as a 16-bit segment in a C
module (16 bits is the default in
QuickC).
Define the segment as either 16-bit or
32-bit.
L1127 far segment references not allowed with
/TINY
The /TINY option (causing the linker to
produce a .COM file) was used with
modules that have a far segment
reference.
Far segment references are not
compatible with the .COM file format.
High-level-language modules cause this
error (unless the language supports the
tiny memory model). Assembly code
referencing a segment address also
produces this error.
For example:
mov ax, seg mydata
L1200 .SYM seek error
The .SYM file could not be properly read.
Try performing a full link with the
/INCREMENTAL option.
L1201 .SYM read error
The .SYM file could not be properly read.
Try performing a full link with the
/INCREMENTAL option.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1202 .SYM write error
The disk is full, or the .SYM file
already exists and has the READONLY
attribute.
L1203 map for segment 'segment' exceeds 64K
The symbolic information associated with
the given segment exceeds 64K, which is
greater than ILINK can handle.
L1204 .ILK write error
The disk is full, or the .SYM file
already exists and has the READONLY
attribute.
L1205 fix-up overflow at 'offset' in segment
'segment'
A FIXUPP object record with the given
location referred to a target too far
away to be correctly processed.
This message indicates an error in
translation by the compiler or assembler.
L1206 .ILK seek error
The .ILK file is corrupted.
Perform a full link.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
L1207 .ILK file too large
The .ILK file is too large for ILINK to
process.
Perform a full link, or reduce the
number of modules in the project. The
size limit for a .ILK file is 64K.
L1208 invalid .SYM file
The .SYM file is invalid.
Delete the file and perform a full link.
If the problem persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1209 .OBJ close error
The operating system returned an error
when ILINK attempted to close one of the
.OBJ files.
L1210 .OBJ read error
The .OBJ file has an unreadable
structure.
Try rebuilding the .OBJ file and
performing a full link. This message
indicates an error in translation by the
compiler or assembler.
L1211 too many LNAMEs
An object module has more than 255 LNAME
records.
There may be too many logical segment
definitions with different class names,
or too many group definitions.
L1212 too many SEGDEFs
The given object module has more than
100 SEGDEF records. A SEGDEF record
defines logical segments.
L1213 too many GRPDEFs
The given object module has more than 10
GRPDEF records. A GRPDEF record defines
physical segments.
L1214 too many COMDEFs
The total number of COMDEF and EXTDEF
records exceeded the limit.
The limit on the total of COMDEF records
(communal data variables) and EXTDEF
records (external references) is 1,023.
Use fewer communal or external variables.
L1215 too many EXTDEFs
The total number of COMDEF and EXTDEF
records exceeded the limit.
The limit on the total of COMDEF records
(communal data variables) and EXTDEF
records (external references) is 1,023.
Use fewer communal or external variables.
L1216 symbol 'symbol' multiply defined
The given symbol is defined more than
once.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1217 internal error #3
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L1218 .EXE file too big, change alignment
The segment-sector alignment value in
the .EXE file is too small to express
the size of one of the segments.
Perform a full link and increase the
alignment value with the /ALIGNMENT
option to QLINK.
L1219 too many library files
The number of libraries (.LIB files)
exceeded ILINK's limit of 32 libraries.
Reduce the number of libraries.
L1220 seek error on library
A library (.LIB file) is corrupted.
Perform a full link and check the .LIB
files.
L1221 library close error
The operating system returned an error
when ILINK attempted to close one of the
libraries (.LIB files).
Perform a full link.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
L1222 error closing .EXE file
The operating system returned an error
when ILINK attempted to close the
exe-cutable file.
Perform a full link.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1223 cannot update time on 'filename'
The operating system returned an error
when ILINK attempted to update the time
on the given file. Possibly the file had
the READONLY attribute set.
L1224 invalid flag 'character'
The syntax on the ILINK command line was
incorrect.
L1225 only one /E command allowed
The ILINK command line contained more
than one /E option specification.
L1226 terminated by user
CTRL+C or CTRL+BREAK was pressed,
interrupting ILINK.
L1227 file 'filename' write protected
The .EXE, .ILK, or .SYM file that ILINK
attempted to update has the READONLY
attribute.
L1228 file 'filename' missing
ILINK could not find one of the .OBJ
files specified on the command line.
L1229 invalid .OBJ format
Possible causes of this error include
the following:
■ Error in compiler translation
■ Corrupted object file
■ Invalid object file (possibly text
file)
■ Missing or unreadable object file
L1230 invalid 'filename' record: position = '
address'
The given .OBJ file has an invalid
format or one unrecognized by ILINK.
This message may indicate an error in
translation by the compiler or assembler.
L1231 file 'filename' was not full linked
An .OBJ file specified in the ILINK
command line was not in the list of
files in the most recent full link.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1232 cannot run 'program'
ILINK is unable to execute a program
specified for execution with the /E
command-line option.
Make sure the program is in the search
path and is a .EXE or .COM file.
L1233 'program' returned 'returncode'
The given program was specified with the
/E option. When ILINK executed this
program, it terminated with the given
nonzero return code. ILINK cannot
continue to the next commands, if any.
L1234 error creating 'filename'
ILINK was unable to create the batch
file for executing the /E commands.
Make sure the environment variable TMP
or TEMP points to a directory that
exists and can be written to.
L1235 error writing to 'filename'
An error occurred while ILINK was
writing the batch file for executing the
/E commands.
Make sure the drive for TMP or TEMP or
the current drive has enough free space.
L1236 file name exceeds 260
A file name can only have 260 characters.
Reduce the length of the file name.
L1237 /I given, cannot proceed
The use specified in the command-line /I
option is preventing ILINK from calling
QLINK in case of incremental violation.
L1238 project file missing
No project name was specified on the
ILINK command line.
Check the syntax of the command line.
The project file must be listed after
any options and before an optional
module list.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
L1240 far references in STRUC fields not
supported
ILINK currently does not support STRUC
definitions like the following:
extrn func:FAR
rek STRUC
far_adr DD func ;
Initialized far address
; within a
STRUC
rek ENDS
To use ILINK, change the code to get rid
of the far address within the STRUC.
L1241 too many defined segments
ILINK has a limit of 255 physical
segments (that is, segments defined in
the object module as opposed to groups
or logical segments).
To use ILINK, reduce the number of
segments.
L1242 too many modules
The program exceeds ILINK's limit of
1,024 modules.
Reduce the number of modules.
L1243 cannot link 64K-length segments
The program has a segment larger than
65,535 bytes.
L1244 cannot link iterated segments
ILINK cannot handle programs linked with
the /EXEPACK linker option.
L1245 forward reference in STRUCT field not
supported
An .OBJ file contains a near fix-up (one
that does not force a .EXE fix-up) whose
target is a symbol in a .OBJ file which
ILINK cannot find. This is called a
"breaking" error.
Change the code by removing the forward
reference. Do this by reversing the
order of the .OBJ files and performing a
full link.
D.4.2 Error Messages
Number Error Message
────────────────────────────────────────────────────────────────────────────
L2000 imported starting address
The program starting address as
specified in the END statement in a MASM
file is an imported routine.
L2002 fix-up overflow at 'number' in segment '
segment'
This error message will be followed by
either
target external 'symbol'
or
frm seg name1, tgt seg name2, tgt offset
number
A fix-up overflow is an attempted
reference to code or data that is
impossible because the source location
(where the reference is made "from") and
the target address (where the reference
is made "to") are too far apart. Usually
the problem is corrected by examining
the source location.
Revise the source file and recreate the
object file. (For information about
frame and target segments, see the
Microsoft MS-DOS Programmer's Reference.)
L2003 intersegment self-relative fix-up at '
number' in segment 'segment'
The program issued a near call or jump
to a label in a different segment.
This error most often occurs when
specifically declaring an external
procedure to be near that should be
declared as far.
L2005 fix-up type unsupported at 'number' in
segment 'segment'
A fix-up type occurred that is not
supported by the linker. This is
probably a compiler error.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L2010 too many fix-ups in LIDATA record
The number of far relocations (pointer-
or base-type) in an LIDATA record
exceeds the limit imposed by the linker.
This is typically produced by the DUP
statement in a .ASM file. The limit is
dynamic: a 1,024-byte buffer is shared
by relocations and the contents of the
LIDATA record; there are eight bytes per
relocation.
Reduce the number of far relocations in
the DUP statement.
Number Error Message
────────────────────────────────────────────────────────────────────────────
L2011 'identifier' : NEAR/HUGE conflict
Conflicting NEAR and HUGE attributes
were given for a communal variable.
L2012 'arrayname' : array-element size
mismatch
A far communal array was declared with
two or more different array-element
sizes (for instance, an array was
declared once as an array of characters
and once as an array of real numbers).
This error occurs only with the
Microsoft FORTRAN Compiler and any other
compiler that supports far communal
arrays.
L2013 LIDATA record too large
An LIDATA record contained more than 512
bytes. This is probably a compiler error.
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
L2022 'routine' (alias 'internalname') :
export undefined
The internal name of the given exported
routine is undefined.
L2023 'routine' (alias 'internalname') :
export imported
The internal name of the given exported
routine conflicts with the internal name
of a previously imported routine. The
set of imported and exported names
cannot overlap.
L2024 'symbol' : special symbol already
defined
The program defined a symbol name
already used by the linker for one of
its own low-level symbols. For example,
the linker generates special symbols
used in overlay support and other
operations.
Choose another name for the symbol to
avoid conflict.
L2025 'symbol' : symbol defined more than once
The same symbol has been found in two
different object files.
L2026 entry ordinal 'number', name 'name' :
multiple definitions for same ordinal
The given exported name with the given
ordinal number conflicted with a
different exported name previously
assigned to the same ordinal. Only one
name can be associated with a particular
ordinal.
Number Error Message
────────────────────────────────────────────────────────────────────────────
L2027 'name' : ordinal too large for export
The given exported name was assigned an
ordinal that exceeded the limit of
65,535.
L2028 automatic data segment plus heap exceed
64K
The total size of data declared in
DGROUP, plus the value given in HEAPSIZE
in the module-definition file, plus the
stack size given by the /STACK option or
STACKSIZE module definition-file
statement, exceeds 64K.
Reduce near-data allocation, HEAPSIZE,
or stack.
L2029 'symbol' : unresolved external
A symbol was declared to be external in
one or more modules, but it was not
publicly defined in any module or
library.
The name of the unresolved external
symbol is given, then a list of object
modules which contain references to this
symbol. This message and the list are
written to the map file, if one exists.
L2041 stack plus data exceed 64K
If the total of near data and requested
stack size exceeds 64K, the program will
not run correctly. The linker checks for
this condition only when /DOSSEG is
enabled, which is the case in the
library start-up module for Microsoft
Language Libraries.
This is a fatal QLINK error.
L2043 Quick library support module missing
The required module QUICKLIB.OBJ was
missing.
The module QUICKLIB.OBJ must be linked
in when creating a Quick library.
L2044 'symbol' : symbol multiply defined, use
/NOE
The linker found what it interprets as a
public-symbol redefinition, probably
because a symbol defined in a library
was redefined.
Relink with the /NOEXTDICTIONARY (/NOE)
option. If error L2025 results for the
same symbol, then this is a genuine
symbol-redefinition error.
L2045 'segment' : segment with > 1 class name
not allowed with /INC
The program defined a segment more than
once, giving the segment different class
names. Different class names for the
same segment are not allowed when
linking with the /INCREMENTAL (/INC)
option.
Number Error Message
────────────────────────────────────────────────────────────────────────────
L2045 (continued)
Normally, this error should never appear
unless programming with MASM. For
example, the two MASM statements
_BSS segment 'BSS'
_BSS segment 'DATA'
have the effect of defining two distinct
segments with the same name but
different classes. This situation is
incompatible with the /INCREMENTAL
option.
L2048 Microsoft Overlay Manager module not
found
Overlays were designated, but the
Microsoft Overlay Manager module was not
found. This module is defined in the
default library.
L2049 no segments defined
No code or initialized data was defined
in the program. The resulting executable
file is not likely to be valid.
L2050 16/32-bit attribute conflict - segment:
'segment' in group: 'group'
A group cannot contain both 16-bit and
32-bit segments.
L2051 start address not equal to 0x100 for
/TINY
The program starting address, as
specified in the .COM file, must have a
starting value equal to 100 hex (0x100
or 0x0100). Any other value is illegal.
Put the following line of assembly
source code in front of the code
segment:
ORG 100h
L2052 'symbol' : unresolved external -
possible calling convention mismatch
A symbol was declared to be external in
one or more modules, but the linker
could not find it publicly defined in
any module or library.
The name of the unresolved external
symbol is given, then a list of object
modules which contain references to this
symbol. The error message and the list
are written to the map file, if one
exists.
This error occurs when a prototype for
an externally defined function is
omitted from a program that is compiled
with the _fastcall option (/Gr). The
calling convention for _fastcall does
not match the assumptions that are made
when a prototype is not included for an
external function.
Either include a prototype for the
function, or compile without the /Gr
option.
D.4.3 Warning Messages
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4000 seg disp. included near 'offset' in
segment 'segment'
This is the warning generated by the
/WARNFIXUP option. See Section 5.5.6,
"Fixups," for more information.
L4001 frame-relative fix-up, frame ignored
near 'offset' in segment 'segment'
A reference was made relative to a
segment that is different from the
target segment of the reference.
For example, if _id1 is defined in
segment _TEXT, the instruction call
DGROUP:_id1
produces this warning. The frame DGROUP
is ignored, so the linker treats the
call as if it were call
_TEXT:_id1.
L4002 frame-relative absolute fix-up near '
offset' in segment 'segment'
A reference was made relative to a
segment that was different from the
target segment of the reference, and
both segments are absolute (defined with
AT).
The linker treats the executable file as
if the file were to run in real mode
only.
L4003 intersegment self-relative fix-up at '
offset' in segment 'segment' pos: '
offset' target external 'name'
The linker found an intersegment
self-relative fixup.
This error may be caused by compiling a
small-model program with the /NT option.
L4004 possible fix-up overflow at 'offset' in
segment 'segment'
A near call/jump was made to another
segment which was not a member of the
same group as the segment from which the
call/jump was made.
This call/jump can cause an incorrect
address calculation when the distance
between the paragraph address (frame
number) of the segment group and the
target segment is greater than 64K, even
when the distance between the segment
where the call/jump was actually made
and the target segment is less than 64K.
L4010 invalid alignment specification
The number specified in the /ALIGNMENT
option must be a power of 2 in the range
2-32,768.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4011 PACKCODE value exceeding 65500
unreliable
The packing limit specified with the
/PACKCODE option was between 65,500 and
65,536. Code segments with a size in
this range are unreliable on some
steppings of the 80286 processor.
L4012 /HIGH disables /EXEPACK
The /HIGH and /EXEPACK options cannot be
used at the same time.
L4015 /CODEVIEW disables /DSALLOCATE
The /CODEVIEW and /DSALLOCATE options
cannot be used at the same time.
L4016 /CODEVIEW disables /EXEPACK
The /CODEVIEW and /EXEPACK options
cannot be used at the same time.
L4017 'option' : unrecognized option name;
option ignored
An unrecognized character followed the
option indicator ( / ).
An example of this warning is
QLINK /ABCDEF main;
L4019 /TINY disables /INCREMENTAL
A .COM file always requires a full link
and cannot be incrementally linked.
The /TINY and /INCREMENTAL options are
incompatible. When they are used
together, the linker ignores the
/INCREMENTAL option.
L4020 'segment' : code-segment size exceeds
65500
Code segments between 65,501 and 65,536
bytes in length may be unreliable on the
Intel 80286 processor.
L4021 no stack segment
The program did not contain a stack
segment defined with the STACK combine
type.
Normally, every program should have a
stack segment with the combine type
specified as STACK. This message may be
ignored if there is a specific reason
for not defining a stack or for defining
one without the STACK combine type.
Linking with versions of LINK earlier
than 2.40 might cause this message,
since these linkers search libraries
only once.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4023 'routine' ('internalname') : export
internal name conflict
The internal name of the given exported
routine conflicted with the internal
name of a previous import definition or
export definition.
L4024 'name' : multiple definitions for export
name
The given name was exported more than
once, an action that is not allowed.
L4025 'modulename'.'importname'('internalname')
: import internal name conflict
The internal name of the given imported
routine (import is either a name or a
number) conflicted with the internal
name of a previous export or import.
L4026 'modulename'.'importname'('internalname')
: self-imported
The given imported routine was imported
from the module being linked. This is
not supported on some systems.
L4027 'name' : multiple definitions for import
internal name
The given internal name was imported
more than once. Previous import
definitions are ignored.
L4028 'segment' : segment already defined
The given segment was defined more than
once in the SEGMENTS statement of the
module-definition file.
L4029 'segment' : DGROUP segment converted to
type DATA
The given logical segment in the group
DGROUP was defined as a code segment.
DGROUP cannot contain code segments
because the linker always considers
DGROUP to be a data segment. The name
DGROUP is predefined as the automatic
data segment.
The linker converts the named segment to
type "data."
L4030 'segment' : segment attributes changed
to conform with automatic data segment
The given logical segment in the group
DGROUP was given sharing attributes
(SHARED/NONSHARED) that differed from
the automatic data attributes as
declared by the DATA instance
specification (SINGLE/MULTIPLE). The
attributes are converted to conform to
those of DGROUP.
The name DGROUP is predefined as the
automatic data segment. DGROUP cannot
contain code segments because the linker
always considers DGROUP to be a data
segment.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4031 'segment' : segment declared in more
than one group
A segment was declared to be a member of
two different groups.
Correct the source file and recreate the
object files.
L4032 'segment' : code-group size exceeds
65500 bytes
The given code group has a size between
65,500 and 65,536 bytes, a size that is
unreliable on some steppings of the
80286 processor.
L4034 more than 239 overlay segments; extra
put in root
The link command line or response file
designated too many segments to go into
overlays.
The limit on the number of segments that
can go into overlays is 239. Segments
starting with the 240th segment are
assigned to the permanently resident
portion of the program (the root).
L4036 no automatic data segment
The application did not define a group
named DGROUP.
DGROUP has special meaning to the linker,
which uses it to identify the auto-
matic or default data segment used by
the operating system.
This warning will not be issued if DATA
NONE is declared.
L4040 stack size ignored for /TINY
The linker ignores stack size if the
/TINY option is given and if the stack
segment has been defined in front of the
code segment.
L4042 cannot open old version
The file specified in the OLD statement
in the module-definition file could not
be opened.
L4045 name of output file is 'filename'
The linker had to change the name of the
output file to the given file name.
If the output file is specified without
an extension, the linker assumes the
default extension .EXE. Creating a Quick
library, .DLL file, or .COM file forces
the
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4045 (continued)
linker to use an extension other than
.EXE. The output-file specifications and
corresponding extensions are listed
below:
Output -File Specification Extension
────────────────────────────────────────────────────────────────────────────
/TINY option .COM
/QUICKLIB option .QLB
LIBRARY statement in .DEF file .DLL
L4047 Multiple code segments in module of
overlaid program incompatible with
/CODEVIEW
When debugging with CodeView, if there
are multiple code segments defined in
one module (.OBJ file) by use of the
compiler #pragma alloc_text( ) and the
program is built as an overlaid program,
you can access the symbolic information
for only the first code segment in
overlay. Symbolic information for the
rest of the code segments in overlay is
not accessible.
L4050 too many public symbols for sorting
The linker uses the stack and all
available memory in the near heap to
sort public symbols for the /MAP option.
If the number of public symbols exceeds
the space available for them, this
warning is issued; the symbols are not
sorted in the map file, but are listed
in an arbitrary order.
Reduce the number of symbols.
L4051 'filename' : cannot find library
The linker could not find the specified
library file, possibly for one of the
following reasons:
■ The specified file does not exist.
Enter the name or full path
specification of a library file.
■ The LIB environment variable is not
set correctly. Check for typographical
errors, incorrect directory listings,
and the presence of a space, semicolon,
or hidden character at the end of the
line.
■ An earlier version of the linker is
being run. Check the path environment
variable, and delete or rename earlier
linkers.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4053 VM.TMP : illegal file name; ignored
VM.TMP appeared as an object-file name.
Rename the file and rerun the linker.
L4054 'filename' : cannot find file
The linker could not find the specified
file.
Enter a new file name, a new path
specification, or both.
L4201 fix-up frame relative to an (as yet)
undefined symbol - assuming ok
A reference was made relative to a
segment that is different from the
target segment of the reference.
This error occurs in either of the
following situations:
■ A frame-relative fixup.
For example, if _id1 is defined in segment _TEXT, the instruction call
DGROUP:_id1 produces this warning. The frame DGROUP is ignored, so the
linker treats the call as if it were call _TEXT:_id1.
■ A frame-relative absolute fixup.
Both segments are absolute (defined with AT). The linker treats the
executable file as if the file were to run in real mode only.
L4202 module contains TYPEDEFs - ignored
The .OBJ file contains type definitions.
ILINK ignores these records.
L4203 module contains BLKDEFs - ignored
The .OBJ file contains records no longer
supported by Microsoft language
compilers.
L4204 old .EXE free information lost
The free list in the .EXE file has been
corrupted. The free list represents
"holes" in the .EXE file made available
when segments moved to new locations.
L4205 file 'filename' has no useful
contribution
The given module makes no contribution
to any segment.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4206 main entry point moved
The program starting address changed.
Try performing a full link.
L4250 'number' undefined symbols
A number of symbols were referred to in
fix-ups but never publicly defined in
the program. The given number indicates
how many of these undefined symbols were
found.
L4251 invalid module reference 'library'
The program makes a dynamic-link
reference to a dynamic-link library that
is not recognized or declared by the
.EXE file.
L4252 file 'filename' does not exist
ILINK could not find the given file.
L4253 symbol 'symbol' deleted
A symbol was deleted from an
incrementally linked module.
L4254 new segment definition 'segment'
A segment was added to the program.
L4255 changed segment definition 'segment'
The segment contribution changed for the
given module. It contributed to a
segment to which it did not previously
contribute, or a segment contribution
was removed.
L4256 segment 'segment' grew too big
The given segment grew beyond the
padding for the given module.
L4257 new group definition 'group'
A new group was defined via the GROUP
directive in assembly language or via
the /ND compiler option for a C program.
L4258 group 'group' changed to include '
segment'
The list of segments included in the
given group changed.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4259 symbol 'symbol' changed
The given data symbol moved (is now at a
new address).
L4260 cannot add new communal data symbol '
symbol'
A new communal data symbol was added as
an uninitialized variable in C or with
the COMM feature in MASM.
L4261 communal variable 'identifier' grew too
big
The given communal variable changed size
too much.
L4262 invalid symbol type for 'symbol'
A symbol that was previously a code
symbol became a data symbol or vice
versa.
L4263 new CodeView symbolic information
A module previously compiled without /Zi
was compiled with /Zi.
L4264 new line-number information
A module previously compiled without /Zi
or /Zd was compiled with /Zi or /Zd.
L4265 new public CodeView information
New information on public symbol
addresses was added.
L4266 invalid .EXE file
The .EXE file is invalid.
Make sure the linker is current.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
L4267 invalid .ILK file
The .ILK file is invalid.
Make sure the linker is current.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
Number Warning Message
────────────────────────────────────────────────────────────────────────────
L4268 .SYM/.ILK mismatch
The .SYM and .ILK files are out of sync.
Make sure the linker is current.
If the error persists, note the
circumstances of the error and notify
Microsoft Corporation by following the
instructions in the Microsoft Product
Assistance Request form at the back of C
for Yourself, included in the QuickC
version 2.5 package.
L4269 library 'library' has changed
The given library has changed.
L4270 entry table expansion not implemented
The program call tree changed in such a
way that ILINK could not process it
correctly. This problem is caused by new
calls to a routine from another routine
that did not call it before.
Perform a full link.
L4272 .ILK read error
The .ILK file does not exist or was not
in the expected format.
L4273 out of memory
ILINK ran out of memory for processing
the input.
If ILINK is being run through the NMAKE
utility, try running ILINK outside of
NMAKE. Otherwise, perform a full link.
D.5 LIB Error Messages
Error messages generated by the Microsoft Library Manager, LIB, have one of
the following formats:
{filename | LIB} : fatal error U1xxx: messagetext
{filename | LIB} : warning U4xxx: messagetext
The message begins with the input-file name (filename), if one exists, or
with the name of the utility. If possible, LIB prints a warning and
continues operation. In some cases, errors are fatal and LIB terminates
processing. LIB may display the following error messages.
D.5.1 LIB Fatal Error Messages
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1150 page size too small
The page size of an input library was
too small, which indicates an invalid
input .LIB file.
U1151 syntax error : illegal file
specification
A command operator such as a minus sign
(-) was given without a following module
name.
U1152 syntax error : option name missing
A forward slash ( / ) was given without
an option after it.
U1153 syntax error : option value missing
The /PAGESIZE option was given without a
value following it.
U1154 option unknown
An unknown option was given. Currently,
LIB recognizes the /PAGESIZE,
/NOEXTDICTIONARY, /NOIGNORECASE, and
/IGNORECASE options.
U1155 syntax error : illegal input
The given command did not follow correct
LIB syntax as specified in Chapter 6,
"LIB."
U1156 syntax error
The given command did not follow correct
LIB syntax as specified in Chapter 6,
"LIB."
U1157 comma or newline missing
A comma or carriage return was expected
in the command line but did not appear.
This may indicate an inappropriately
placed comma, as in the following line:
LIB math.lib,-mod1+mod2;
The line should have been entered as
follows:
LIB math.lib -mod1+mod2;
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1158 terminator missing
Either the response to the "Output
library" prompt or the last line of the
response file used to start LIB did not
end with a carriage return.
U1161 cannot rename old library
LIB could not rename the old library to
have a .BAK extension because the .BAK
version already existed with read-only
protection.
Change the protection on the old .BAK
version.
U1162 cannot reopen library
The old library could not be reopened
after it was renamed to have a .BAK
extension.
U1163 error writing to cross-reference file
The disk or root directory was full.
Delete or move files to make space.
U1170 too many symbols
More than 4,609 symbols appeared in the
library file.
U1171 insufficient memory
LIB did not have enough memory to run.
Remove any shells or resident programs
and try again, or add more memory.
U1172 no more virtual memory
The current library exceeds the 512K
limit imposed by LIB.
Reduce the number of object modules.
U1173 internal failure
Note the circumstances of the failure
and notify Microsoft Corporation by
using the Microsoft Product Assistance
Request form at the back of C for
Yourself, included in the QuickC version
2.5 package.
U1174 mark: not allocated
Note the circumstances of the failure
and notify Microsoft Corporation by
using the Microsoft Product Assistance
Request form at the back of C for
Yourself, included in the QuickC version
2.5 package.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1175 free: not allocated
Note the circumstances of the failure
and notify Microsoft Corporation by
using the Microsoft Product Assistance
Request form at the back of C for
Yourself, included in the QuickC version
2.5 package.
U1180 write to extract file failed
The disk or root directory was full.
Delete or move files to make space.
U1181 write to library file failed
The disk or root directory was full.
Delete or move files to make space.
U1182 'filename' : cannot create extract file
The disk or root directory was full, or
the specified extract file already
existed with read-only protection.
Make space on the disk or change the
protection of the extract file.
U1183 cannot open response file
The response file was not found.
U1184 unexpected end-of-file on command input
An end-of-file character was received
prematurely in response to a prompt.
U1185 cannot create new library
The disk or root directory was full, or
the library file already existed with
read-only protection.
Make space on the disk or change the
protection of the library file.
U1186 error writing to new library
The disk or root directory was full.
Delete or move files to make space.
U1187 cannot open VM.TMP
The disk or root directory was full.
Delete or move files to make space.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1188 cannot write to VM
Note the circumstances of the failure
and notify Microsoft Corporation by
using the Microsoft Product Assistance
Request form at the back of C for
Yourself, included in the QuickC version
2.5 package.
U1189 cannot read from VM
Note the circumstances of the failure
and notify Microsoft Corporation by
using the Microsoft Product Assistance
Request form at the back of C for
Yourself, included in the QuickC version
2.5 package.
U1200 'name' : invalid library header
The input library file had an invalid
format. It was either not a library file,
or it had been corrupted.
U1203 'name' : invalid object module near '
location'
The module specified by name was not a
valid object module.
U2152 'filename' : cannot create listing
The directory or disk was full, or the
cross-reference listing file already
existed with read-only protection.
Make space on the disk or change the
protection of the cross-reference
listing file.
U2155 'modulename' : module not in library;
ignored
The specified module was not found in
the input library.
U2157 'filename' : cannot access file
LIB was unable to open the specified
file.
U2158 'libraryname' : invalid library header;
file ignored
The input library had an incorrect
format.
U2159 'filename' : invalid format 'hexnumber';
file ignored
The signature byte or word hexnumber of
the given file was not one of the
following recognized types: Microsoft
library, Intel library, Microsoft object,
or XENIX archive.
D.5.2 LIB Warning Messages
Number Warning Message
────────────────────────────────────────────────────────────────────────────
U4150 'modulename' : module redefinition
ignored
A module was specified to be added to a
library, but a module with the same name
was already in the library, or a module
with the same name was found more than
once in the library.
U4151 'name' : symbol defined in module name,
redefinition ignored
The specified symbol was defined in more
than one module.
U4153 number1 : number2 : page size too small;
ignored
The value specified in the /PAGESIZE
option was less than 16.
U4155 'modulename' : module not in library
A module specified to be replaced does
not already exist in the library. LIB
adds the module anyway.
U4156 output-library specification ignored
An output library was specified in
addition to a new library name. For
example, specifying
LIB new.lib+one.obj,new.lst,new.lib
where new.lib does not already exist
causes this error.
U4157 insufficient memory, extended dictionary
not created
Insufficient memory prevented LIB from
creating an extended dictionary. The
library is still valid, but the linker
will not be able to take advantage of
the extended dictionary to speed linking.
U4158 internal error, extended dictionary not
created
An internal error prevented LIB from
creating an extended dictionary. The
library is still valid, but the linker
will not be able to take advantage of
the extended dictionary to speed linking.
D.6 NMAKE Error Messages
Error messages from the NMAKE utility have one of the following formats:
{filename | NMAKE} : fatal error U1xxx: messagetext
{filename | NMAKE} : warning U4xxx: messagetext
The message begins with the input-file name (filename) and line number, if
one exists, or with the name of the utility.
NMAKE generates the following error messages.
D.6.1 Fatal Error Messages
Number Fatal<|>Error<|>Message
────────────────────────────────────────────────────────────────────────────
U1000 syntax error: ')' missing in macro
invocation
A left parenthesis (( ) appeared without
a matching right parenthesis ( )) in a
macro invocation. The correct form is $(
name), or $n for one-character names.
U1001 syntax error: illegal character '
character' in macro
A nonalphanumeric character other than
an underscore (_) appeared in a macro.
U1002 syntax error: invalid macro invocation
'$'
A single dollar sign ($) appeared
without a macro name associated with it.
The correct form is $(name). To use a
dollar sign in the file, type it twice (
$$) or precede it with a caret (^).
U1003 syntax error: '=' missing in macro
The equal sign (=) was missing in a
macro definition.
The correct form is
name = value
U1004 syntax error: macro name missing
A macro invocation appeared without a
name.
The correct form is
$(name)
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1005 syntax error: text must follow ':' in
macro
A string substitution was specified for
a macro, but the string to be changed in
the macro was not specified.
U1006 syntax: missing closing double quotation
mark
An opening double quotation mark (")
appeared without a closing double
quotation mark.
U1007 double quotation mark not allowed in
name
The specified target name or file name
contained a double quotation mark (").
Double quotation marks can surround a
file name but not be contained within it.
U1017 unknown directive '!directive'
The directive specified is not one of
the recognized directives.
U1018 directive and/or expression part missing
The directive was incompletely specified.
The expression part is required.
U1019 too many nested if blocks
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1020 end-of-file found before next directive
A directive, such as !ENDIF, was missing.
U1021 syntax error: else unexpected
An !ELSE directive was found that was
not preceded by !IF, !IFDEF, or !IFNDEF,
or the directive was placed in a
syntactically incorrect place.
U1022 missing terminating character for
string/program invocation : 'char'
The closing double quotation mark (") in
a string comparison in a directive was
missing, or the closing bracket ( ] ) in
a program invocation in a directive was
missing.
U1023 syntax error present in expression
An expression is invalid.
Check the allowed operators and operator
precedence.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1024 illegal argument to !CMDSWITCHES
An unrecognized command switch was
specified.
U1031 file name missing (or macro is null)
An include directive was found, but the
name of the file to be included was
missing, or the macro expanded to
nothing.
U1033 syntax error: 'string' unexpected
The specified string is not part of the
valid syntax for a makefile.
U1034 syntax error: separator missing
The colon (:) that separates target(s)
and dependent(s) is missing.
U1035 syntax error: expected ':' or '='
separator
Either a colon (:), implying a
dependency line, or an equal sign (=),
implying a macro definition, was
expected.
U1036 syntax error: too many names to left of
'='
Only one string is allowed to the left
of a macro definition.
U1037 syntax error: target name missing
A colon (:) was found before a target
name was found.
At least one target is required.
U1038 internal error: lexer
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1039 internal error: parser
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1040 internal error: macro expansion
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1041 internal error: target building
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1042 internal error: expression stack
overflow
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1043 internal error : temp file limit
exceeded
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1044 internal error : too many levels of
recursion building a target
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1045 'internal error message'
Note the circumstances of the error and
notify Microsoft Corporation by
following the instructions in the
Microsoft Product Assistance Request
form at the back of C for Yourself,
included in the QuickC version 2.5
package.
U1050 'user-specified text'
The message specified with the !ERROR
directive is displayed.
U1051 out of memory
The program ran out of space in the far
heap.
Split the description file into smaller
and simpler pieces.
U1052 file 'filename' not found
The file was not found.
The file name may not be properly
specified in the makefile.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1053 file 'filename' unreadable
The file cannot be read.
The following are possible causes of
this error:
■ The file does not have appropriate
attributes for reading.
■ A bad area exists on disk.
■ A bad file-allocation table exists.
■ The file is locked.
U1054 cannot create in-line file 'filename'
NMAKE failed in its attempt to create
the file given by name.
The following are possible causes of
this error:
■ The file already exists with a
read-only attribute.
■ There is insufficient disk space to
create the file.
U1055 out of environment space
The environment space limit was reached.
Restart the program with a larger
environment space or with fewer
environment variables.
U1056 cannot find command processor
The command processor was not found.
NMAKE uses COMMAND.COM or CMD.EXE as a
command processor to execute commands.
It looks for the command processor first
by the full path name given by the
COMSPEC environment variable. If COMSPEC
does not exist, NMAKE searches the
directories specified by the PATH
environment variable.
U1057 cannot delete temporary file 'filename'
NMAKE failed to delete the temporary
in-line file.
U1058 terminated by user
Execution of NMAKE was aborted by CTRL+C
or CTRL+BREAK.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1060 unable to close file : 'filename'
NMAKE encountered an error while closing
a file.
One of the following may have occurred:
■ The file is a read-only file.
■ There is a locking or sharing
violation.
■ The disk is full.
U1061 /F option requires a file name
The /F command-line option requires the
name of the description file to be
specified.
To use standard input, specify '-' as
the description file name.
U1062 missing file name with /X option
The /X command-line option requires the
name of the file to which diagnostic
error output should be redirected.
To use standard input, specify '-' as
the output file name.
U1063 missing macro name before '='
NMAKE detected an equal sign (=) without
a preceding name.
This error can occur in a recursive call
when the macro corresponding to the
macro name expands to nothing.
U1064 MAKEFILE not found and no target
specified
No description file was found, and no
target was specified.
A description file can be specified
either with the /F option or through the
default file MAKEFILE. Note that NMAKE
can create a target using an inference
rule even if no description file is
specified.
U1065 invalid option 'option'
The option specified is not a valid
option for NMAKE.
U1066 option '/N' not supported; use NMAKE
NMAKE's shell program NMK.COM does not
support the /N option.
Use NMAKE /N.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1070 cycle in macro definition 'macroname'
A circular definition was detected in
the macro definition specified.
Circular definitions are invalid.
U1071 cycle in dependency tree for target '
targetname'
A circular dependency was detected in
the dependency tree for the specified
target.
Circular dependencies are invalid.
U1072 cycle in include files : 'filename'
A circular inclusion was detected in the
include file specified. The named file
includes a file which eventually
includes the named file.
U1073 don't know how to make 'targetname'
The specified target does not exist, and
there are no commands to execute or
inference rules given for it.
U1074 macro definition too long
The value of a macro definition would
overflow an internal buffer.
U1075 string too long
The text string would overflow an
internal buffer.
U1076 name too long
The macro name, target name, or
build-command name would overflow an
internal buffer.
Macro names may not exceed 128
characters.
U1077 'program' : return code 'value'
The given program invoked from NMAKE
failed, returning the error code value.
U1078 constant overflow at 'directive'
A constant in the directive's expression
was too big.
U1079 illegal expression : divide by zero
present
An expression tried to divide by zero.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1080 operator and/or operand out of place :
usage illegal
The expression incorrectly used an
operator or operand.
Check the allowed set of operators and
their order of precedence.
U1081 'program' : program not found
NMAKE could not find the given program
in order to run it.
Make sure that the program is in the
current path and has the correct
extension.
U1082 'command' : cannot execute command : out
of memory
NMAKE cannot execute the given command
because there is not enough memory.
Free memory and run NMAKE again.
U1083 target macro '$(macroname)' expands to
nothing
A target was specified as a macro name
that has not been defined or has null
value.
NMAKE cannot process a null target.
U1084 in-line file not allowed in inference
rules
In-line file syntax is not allowed in
inference rules and can be used only in
a target-dependency block.
U1085 cannot mix implicit and explicit rules
A regular target was specified along
with the target for a rule.
A rule has the form
.fromext.toext
U1086 inference rule cannot have dependents
Dependents are not allowed when an
inference rule is being defined.
U1087 cannot have : and :: dependents for same
target
A target cannot have both a single-colon
(:) and a double-colon (::) dependency.
U1088 invalid separator '::' on inference rule
Inference rules can use only a
single-colon (:) separator.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1089 cannot have build commands for
pseudotarget 'targetname'
Pseudotargets (for example, .PRECIOUS or
.SUFFIXES) cannot have build commands
specified.
U1090 cannot have dependents for pseudotarget
'targetname'
The specified pseudotarget (for example,
.SILENT or .IGNORE) cannot have a
dependent.
U1091 invalid suffixes in inference rule
The suffixes being used in the inference
rule are not part of the .SUFFIXES list.
U1092 too many names in rule
An inference rule cannot have more than
one pair of extensions as a target.
U1093 cannot mix special pseudotargets
It is illegal to list two or more
pseudotargets together.
U1094 syntax error : only (no)keep allowed
here
Something other than KEEP or NOKEEP
appeared at the end of the syntax for
creating an in-line file.
The syntax for generating an in-line
file allows an action to be specified
after the second pair of angle brackets.
Valid actions are KEEP and NOKEEP. Other
actions are errors.
The KEEP option specifies that NMAKE
should leave the in-line file on disk.
The NOKEEP option causes NMAKE to delete
the file before exiting. The default is
NOKEEP.
U1095 expanded command line 'commandline' too
long
After macro expansion, the command line
exceeded the length limit of 128
characters.
If the command is a QLINK command line,
use a response file.
U1096 cannot open file 'filename'
The given file could not be opened,
either because the disk was full or
because the file has been set to be
read-only.
Number Fatal Error Message
────────────────────────────────────────────────────────────────────────────
U1097 extmake syntax usage error, no dependent
No dependent was given.
In extmake syntax, the target under
consideration must have either an
implicit dependent or an explicit
dependent.
U1098 extmake syntax in 'string' incorrect
The part of the string shown contains an
extmake syntax error.
D.6.2 Compilation Error Message
Number Compilation Error Message
────────────────────────────────────────────────────────────────────────────
U2001 no more file handles (too many files
open)
NMAKE could not find a free file handle.
One of the following may be a solution:
■ Reduce recursion in the build
procedures.
■ Increase the number of file handles by
changing the FILES setting in CONFIG.SYS
to allow a larger number of open files.
FILES = 20 is the recommended setting.
D.6.3 Warning Messages
Number Warning Message
────────────────────────────────────────────────────────────────────────────
U4001 command file can be invoked only from
command line
A command file cannot be invoked from
within another command file. Such an
invocation is ignored.
The command file should contain the
entire remaining command line.
U4002 resetting value of special macro '
macroname'
The value of a macro such as $(MAKE) was
changed within a description file.
The name by which this program was
invoked is not a tagged section in the
TOOLS.INI file.
U4003 no match found for wild card 'filename'
There are no file names that match the
specified target or dependent file with
the wild-card characters asterisk (*)
and question mark (?).
Number Warning Message
────────────────────────────────────────────────────────────────────────────
U4004 too many rules for target 'targetname'
Multiple blocks of build commands were
specified for a target using single
colons (:) as separators.
U4005 ignoring rule 'rule' (extension not in
.SUFFIXES)
The rule was ignored because the
suffix(es) in the rule are not listed in
the .SUFFIXES list.
U4006 special macro undefined : 'macroname'
The special macro name is undefined and
expands to nothing.
U4007 file name 'filename' too long;
truncating to 8.3
The base name of the file has more than
eight characters, or the extension has
more than three characters. NMAKE
truncates the name to an eight-character
base and a three-character extension.
U4008 removed target 'target'
Execution of NMAKE was interrupted while
NMAKE was trying to build the given
target; therefore the target was
incomplete. Because the target was not
specified in the .PRECIOUS list, NMAKE
has deleted it.
U4009 duplicate in-line file 'filename'
The given file name is the same as the
name of an earlier in-line file.
Reusing this name caused the earlier
file to be overwritten. This will
probably cause unexpected results.
Glossary
────────────────────────────────────────────────────────────────────────────
The definitions in this glossary are intended primarily for use with this
manual. Neither individual definitions nor the list of terms is
comprehensive.
8087 or 80287 coprocessor
See "math coprocessor."
ANSI (American National Standards Institute)
The national institute responsible for defining programming-language
standards to promote portability of these languages between different
computer systems.
argument
A value passed to a function. In the QuickC Compiler Tool Kit, a string or
value that modifies the effects of a compiler, linker, or utility option.
arithmetic conversion
Conversion operations performed on items of integral and floating-point
types used in expressions.
ASCII (American Standard Code for Information Interchange)
A set of 256 codes that many computers use to represent letters, digits,
special characters, and other symbols. Only the first 128 of these codes are
standardized; the remaining 128 are special characters that are defined by
the computer manufacturer.
base name
The portion of the file name that precedes the file-name extension. For
example, samp is the base name of the file samp.c.
batch file
A text file containing DOS commands that can be invoked from the DOS com-
mand line.
block
A sequence of declarations, definitions, and statements enclosed within
braces ({ }).
canonical frame number
Part of the starting address for a segment. The canonical frame number
specifies the address of the first paragraph in memory that contains one or
more bytes of the segment.
child process
A new process started by a currently running process.
compact memory model
A memory model that allows for more than one data segment and only one code
segment.
constant expression
Any expression that evaluates to a constant. A constant may involve integer
constants, character constants, floating-point constants, enumeration
constants, type casts to integral and floating-point types, and other
constant expressions.
coprocessor
See "math coprocessor."
declaration
A construct that associates the name and the attributes of a variable,
function, or type.
definition
A construct that initializes and allocates storage for a variable or that
specifies the name, formal parameters, body, and the return type of a
function.
dependency line
A line in an NMAKE description file that defines one or more targets and the
files they depend on.
dependents
The files that, when modified, cause NMAKE to update a target.
description block
A dependency line in an NMAKE description file and all the statements
(commands, comments, and directives) that apply to it.
description file
The text file that NMAKE reads to determine what to do. A description file
is sometimes called a makefile.
directive
An instruction to the C preprocessor to perform a specific action on
source-program text before compilation. For the NMAKE utility, an
instruction that gives information about which commands to execute or how to
execute them.
emulator
A floating-point-math package that provides software emulation of the
operations of a math coprocessor.
environment variable
A variable stored in the environment table that provides DOS with
information (where to find executable files and library files, where to
create temporary files, etc.).
errorlevel code
See "exit code."
escape character
A character that, when used immediately preceding a special character,
causes the special character to lose its special meaning.
executable image
The code and data that make up an executable file; that is, a compiled,
linked program that DOS can execute.
exit code
A code returned by a program to DOS indicating whether the program ran
successfully.
expression
A combination of operands and operators that yields a single value.
external level
The parts of a C program outside the function declarations.
formal parameters
Variables that receive values passed to a function when the function is
called.
function
A collection of declarations and statements that has a unique name and can
return a value.
function body
A statement block containing the local variable declarations and statements
of a function.
function call
An expression that passes control and arguments (if any) to a function.
function declaration
A declaration that establishes the name, return type, and storage class of a
function that is defined explicitly elsewhere in the program.
function definition
A definition that specifies a function's name, its formal parameters, the
declarations and statements that define what it does, and (optionally) its
return type and storage class.
function prototype
A function declaration that includes a list of the names and types of formal
parameters in the parentheses following the function name.
global region
The area of a source file between the beginning of the file and the first
curly brace of a function, or between the ending curly brace of a function
and the beginning curly brace of another function. If no edits have occurred
within a global region, incremental compilation is usually possible.
heap
An area of memory set aside for dynamic allocation by a program.
huge memory model
A memory model that allows for more than one code segment. Individual data
items may exceed 64K in length.
include file
A text file that is merged into another text file through use of the
#include preprocessor directive.
incremental compilation
The compilation mode, specified by the /Gi option to the QCL command, in
which only changed functions are recompiled.
incremental linking
The process of linking with ILINK instead of QLINK, in which only changed
modules are relinked. This process requires that the /INC option to the
QLINK command be specified first. The actual use of ILINK is then specified
by the /Gi and /Li options to the QCL command.
inference rule
A template that the NMAKE utility follows to update a target in the absence
of explicit commands.
internal level
The parts of a C program within function declarations.
keyword
A word with a special, predefined meaning for the QuickC compiler.
large memory model
A memory model that allows for more than one segment of code and more than
one segment of data, but with no individual data items exceeding 64K.
level
See "internal level"; "external level."
library
A file containing compiled modules. Also called an object-code library. The
linker extracts modules from the library and combines them with object files
to create executable program files. A load library is a library specified in
the object-files field as input to the linker. The linker links every module
in a load library into the executable file.
load-time-relocation table
A table of references, relative to the start of the program, that are
resolved when the program is loaded into memory.
loop optimization
Optimization that reduces the amount of code executed for each loop
iteration in a program, thereby increasing the speed with which the loop
executes.
lvalue
An expression (such as a variable name) that refers to a memory location and
is required as the left-hand operand of an assignment operation or as the
single operand of a unary operator.
macro
An identifier defined in a #define preprocessor directive to represent
another series of tokens. For the NMAKE utility, a name defined on the
command line or in a description file to represent another string.
math coprocessor
Hardware products that provide very fast and very precise floating-point
number processing. Examples include the Intel 8087 and 80287 coprocessors.
medium memory model
A memory model that allows for more than one code segment and only one data
segment.
member
One of the elements of a structure or union.
memory model
One of the models that specifies how memory is set up for program code and
data. (For descriptions of standard memory models, see "tiny memory model";
"small memory model"; "medium memory model"; "compact memory model"; "large
memory model"; "huge memory model.")
module-description table (MDT)
A file created or updated during incremental compilation that saves
information about changes to a source file.
NAN (not a number)
The 8087 or 80287 coprocessor generates NANs when the result of an operation
cannot be represented in the IEEE format. For example, if you try to add two
positive numbers whose sum is larger than the maximum value permitted by the
processor, the coprocessor returns a NAN instead of the sum.
newline character
The character used to mark the end of a line in a text file, or the escape
sequence (\n) used to represent this character.
null character
The ASCII character encoded as the value 0, represented as an escape
sequence (\0) in a source file.
null pointer
A pointer to nothing, expressed as the value 0.
object code
Relocatable machine code, created by a compiler.
object file
A file containing relocatable machine code, created as the result of
compiling a source file.
object module
A component of a library. An object file becomes an object module when it is
loaded into a library.
operand
A constant or variable value that is manipulated in an expression.
operator
One or more symbols that specify how the operand or operands of an
expression are manipulated.
overlay
Part of a program that is read into memory from disk only if and when it is
needed.
parent process
A process that generates a child process using one of the spawn, exec, or
system families of run-time-library functions.
pointer
A variable containing the address of another variable, function, or
constant.
pragma
An instruction to the compiler to perform an action at compile time.
precedence
The relative position of an operator in the hierarchy that determines the
order in which expressions are evaluated.
preprocessor
A text processor that manipulates the contents of a C source file during the
first phase of compilation.
preprocessor directive
See "directive."
prototype
See "function prototype."
pseudotarget
A target, in an NMAKE description file, that is not a file but is used as a
label for performing a set of commands.
QCL
The command that invokes the Microsoft QuickC compiler to compile and link
programs.
relocatable
Not containing absolute addresses; therefore, eligible to be placed in
memory at any location.
response file
A file that contains command-line arguments or responses to program prompts.
Response files may be used as input to QLINK, LIB, and NMAKE.
run time
The time during which a previously compiled and linked program is executing.
run-time library
A file containing the routines needed to implement certain functions of the
Microsoft QuickC language.
scope
The parts of a program in which an item can be referenced by name. The scope
of an item may be limited to the file, function, block, or function
prototype in which it appears.
segment
An area of memory, less than or equal to 64K long, that usually contains
either code or data. In the tiny memory model, a segment may contain both.
small memory model
A memory model that allows for only one code segment and only one data
segment.
source file
A text file containing C-language code.
stack
A dynamically shrinking and expanding area of memory in which data items are
stored in consecutive order and removed on a last in, first out basis.
stack probe
A short routine called on entry to a function to verify that there is enough
room in the program stack to allocate local variables required by the
function and, if so, to allocate those variables.
static
A storage class that allows variables to keep their values even after the
program exits the block in which the variable is declared.
string
An array of characters, terminated by a null character (\0).
string constant
A string of characters and escape sequences enclosed in double quotation
marks (" "). Every string constant is an array of elements of type char.
subscript expression
An expression, usually used to reference array elements, representing an
address that is offset from a specified base address by a given number of
positions.
target
The object of an NMAKE description block.
tiny memory model
A memory model that allows for only one segment, which contains both code
and data, and that produces a .COM file.
type cast
An operation in which a value of one type is converted to a value of a
different type.
type checking
An operation in which the compiler verifies that the operands of an operator
are valid or that the actual arguments in a function call are of the same
types as the corresponding formal parameters in the function definition and
function prototype.
type declaration
A declaration that defines the name and members of a structure or union
type, or the name and enumeration set of an enumeration type.
unary expression
An expression consisting of a single operand preceded or followed by a unary
operator.
unary operator
An operator that takes a single operand. Unary operators in the C language
are the complement operators (- ~ !), indirection operator (*), increment
(++) and decrement (- -) operators, address-of operator (&), and sizeof
operator. The unary plus operator (+) is legal but has no effect.
unresolved reference
A reference to a global or external variable or function that cannot be
found, either in the modules being linked or in the libraries that are
linked with those modules.
white-space character
A space, tab, line-feed, carriage-return, form-feed, vertical-tab, or
new-line character.
wild card
One of the DOS characters (? and *) that can be expanded into one or more
characters in file-name references.
INDEX
──────────────────────────────────────────────────────────────────────────
{} (braces), NMAKE character
:: (double colon), NMAKE separator
-* (minus sign-asterisk), LIB command symbol
command-line example
described
list
-+ (minus sign-plus sign), LIB command symbol
$@ macro
$* macro
$? macro
$@ macro
$* macro
$? macro
$< macro
$? macro
* (asterisk), LIB command symbol
@ (at sign), NMAKE special character
\ (backslash), NMAKE continuation character
^ (caret), NMAKE escape character
: (colon)
NMAKE separator
QLINK command symbol
, (comma)
LIB command symbol
QLINK command symbol
- (dash)
NMAKE special character
QCL option character
$ (dollar sign), NMAKE macros, used in
! (exclamation point)
NMAKE directives, used in
NMAKE special character
/ (forward slash), option character (QCL)
- (minus sign), LIB command symbol
# (number sign), NMAKE comment character
+ (plus sign)
LIB command symbol
QLINK command symbol
; (semicolon);LIB command symbol
; (semicolon);NMAKE command separator
; (semicolon);QLINK command symbol
$** macro
80186 processor
80286 processor
8087/80287 coprocessor, suppressing use of
$$@ macro
A
/A option
ILINK
NMAKE
&(ampersand), LIB continuation symbol
/AC option (QCL)
Addresses
components
far
huge
near
segment start
AFLAGS, NMAKE macro
/AH option (QCL)
/AL option (QCL)
Alignment types
/AM option (QCL)
Ampersand (&), LIB continuation symbol
Archives, XENIX
Argument-type list
defined
Arguments
QLINK options
variable number of
/AS option (QCL)
AS, NMAKE macro
Assembly-language files, specifying
Asterisk (*), LIB command symbol
/Astring option (QCL)
/AT option (QCL)
At sign (@), NMAKE special character
B
/BA option (QLINK)
Backslash (\), NMAKE continuation character
Batch files, exit codes
/batch option (QCL)
BEGDATA class name
Braces ({}), NMAKE character
BSS class name
C
/C option
ILINK
NMAKE
/c option
QCL
/C option
QCL
Calling conventions
Canonical frame number
see Frame number; see
Caret (^), NMAKE escape character
Case sensitivity
QLINK
CC, NMAKE macro
_cdecl keyword
/Za option, used with
defined
include files, used in
CFLAGS, NMAKE macro
char type, changing default
_CHAR_UNSIGNED predefined identifier
check_pointer pragma
check_stack pragma
Class names
!CMDSWITCHES directive (NMAKE)
/CO option (QLINK)
CODE class name
Code segment
colon (:)
NMAKE separator
Colon (:)
QLINK command symbol
.COM file, creating
.COM files, creating
Combine types
COMMON
PRIVATE
PUBLIC
STACK
Comma (, )
LIB command symbol
QLINK command symbol
Command line
error messages
LIB
NMAKE
defining macros on
described
rules for
special characters
QLINK
Commands
CL, defined. See QCL command
NMAKE description file
QCL, described
Comments
NMAKE description file
preserving
COMMON combine type
Compact memory model
see Memory models, compact; see
Compatibility, floating-point options
Compilation
conditional
defined
error messages
incremental
suppressing
Compiler error messages
categories
command line
compilation
fatal
warning
Compiler limits
Compiler options
see QCL options; see
Consistency checking, LIB
Controlling
data loading
executable-file loading
number of segments
preprocessor
stack size
Conversion, pointer arguments
Coprocessor, 8087/80287, suppressing use of
/CP option (QLINK)
Cross-reference listing file, LIB
Customized memory models. See Memory models, customized
D
/D option
NMAKE
QCL
Dash (-)
NMAKE special character
QCL option character
Data segment
_DATA segment
Data segment
Debugging
/CODEVIEW option (QLINK)
/Zi and /Zd options
incrementally linked programs
QCL option for
Declarations, maximum level of nesting
Defaults
LIB responses
libraries
ignoring
suppressing selection
NMAKE, MAKEFILE
QLINK responses
Dependency lines
Dependents
described
directory searches
macros for
specifying
Description blocks
defined
described
inference rules, used with
multiple for one target
Description files (NMAKE)
backslash as continuation character
command lines
comments
described
error handling
macro definitions in
omitting commands from
specifying
DGROUP segments
Directives (NMAKE)
!CMDSWITCHES
!ELSE
!ENDIF
!ERROR
!IF
!IFDEF
!IFNDEF
!INCLUDE
!UNDEF
defined
described
using
/DO option (QLINK)
Document conventions
Dollar sign ($), NMAKE macros
.DOSSEG directive
/DS option (QLINK)
DS register
E
/E option
ILINK
NMAKE
QCL
QLINK
80186 processor
80286 processor
8087/80287 coprocessor, suppressing use of
_edata linker variable
!ELSE directive (NMAKE)
Emulator, floating-point
_end linker variable
!ENDIF directive (NMAKE)
Environment variables
CL
INCLUDE
LIB
LINK
NO87
TMP
/EP option (QCL)
!ERROR directive (NMAKE)
Error handling, NMAKE
Error level codes
see Exit codes; see
Error messages
compiler
categories
command line
compilation
correctable
fatal
warning
floating-point exceptions
ILINK
LIB
NMAKE
QLINK
run-time
types of
Escape character, NMAKE
Exceptions, listed
Exclamation point (!)
NMAKE directives, used in
NMAKE special character
Executable files
contents
creating
extensions
loading
naming
default
QCL
QLINK
packing
QLINK, specifying with
prompts
response file
Executable image
Execution-time optimization
Exit codes
DOS batch files, used with
error level
NMAKE
programs for
using
Expressions
Extensions
.SUFFIXES list
default, QLINK
executable files
inference rules
libraries
LIB, used with
QLINK, used with
listing files, defaults for
map files
object files
F
/F option
NMAKE
QCL
QLINK
Far calls
_far keyword
/Za option, used with
default addressing conventions
effects
data declarations
function declarations
library routines, used with
restriction for in-memory programs
small-model programs
Far pointers
_fastcall keyword
Fatal error messages
/Fe option (QCL)
File names
extensions
path names
uppercase and lowercase letters in
Files
see also ; see also
object
defined
RMFIXUP.OBJ
source, defined
temporary, space requirements
FIXSHIFT utility
Fixups
Floating-point
operations
error messages
exceptions
options
/Fm option (QCL)
/Fo option (QCL)
_fortran keyword
Forward slash (/), QCL option character
/FPi option (QCL)
/FPi87 option (QCL)
Frame number
Functions
arguments, variable number of
calling conventions
declaring near and far
G
/G0 option (QCL)
/G1 option (QCL)
/G2 option (QCL)
/Gc option (QCL)
/Gd option (QCL)
/Ge option (QCL)
/Gi option (QCL)
Global region
Global symbols
see Public symbols; see
/Gr option (QCL)
Graphics, Hercules
Groups
DGROUP
linking procedures, used in
/Gs option (QCL)
/Gt option (QCL)
/Gw option (QCL)
/GW option (QCL)
H
/HE option (QLINK)
/HELP option
ILINK
NMAKE
QCL
Hercules display adapter
/HI option (QLINK)
Huge arrays
_huge keyword
default addressing conventions
described
Huge memory model
see Memory models; see
I
/I option
ILINK
NMAKE
QCL
Identifiers
length, maximum
predefined
listed
MSDOS
M_I286
M_I8086
M_I86
M_I86xM
NO_EXT_KEYS
removing definitions of
_CHAR_UNSIGNED
!IF directive (NMAKE)
!IFDEF directive (NMAKE)
!IFNDEF directive (NMAKE)
.IGNORE pseudotarget
Ignoring
case, QLINK
default libraries, QLINK
ILINK
command
error messages
options
In-line instructions
/INC option (QLINK)
!INCLUDE directive (NMAKE)
INCLUDE environment variable
NMAKE, used with
overriding
Include files
defined
directory specification
search paths
maximum number of
specifying
Incremental compilation
Incremental linking
Incremental violations
/INF option (QLINK)
Inference rules
defined
defining
described
precedence
predefined
Instruction sets
80186 processor
80286 processor
8086/8088 processor
Invoking
LIB
command line
prompts
response file
NMAKE
command line
response file
QCL
QLINK
command line
prompts
response file
J
/J option (QCL)
K
Keywords
defined
_cdecl
_far. See _far keyword
_fastcall
_fortran
_huge. See _huge keyword
_near. See _near keyword
_pascal
L
Language extensions
disabling
listed
Large memory model
see Memory models, large; see
/Lc option (QCL)
/Li option (QCL)
/LI option (QLINK)
LIB command symbols
asterisk (*)
listed
minus sign (-)
minus sign-asterisk (-*)
minus sign-plus sign (-+)
plus sign (+)
LIB
command syntax
consistency checking
default responses
environment variable
error messages
extending lines
input
libraries
combining
creating
index
listing files
modules
adding and deleting
adding
copying
deleting
extracting
moving
replacing
operations, order of
output
running
command line
prompts
response file
Libraries
see also LIB; see also
8087/80287 coprocessor
automatic object-file processing
creating
/Zl, compiling modules with
described
defined
emulator
Intel
load
mLIBC7.LIB
mLIBCE.LIB
modifying
naming
object code
regular
run time, defined
search
order
paths
specifying
QCL command line
QLINK command line
QLINK prompts
QLINK response file
standard
listed
overriding
selecting
uses of
Limits
arguments
compiler
macros
/link option (QCL)
Linker utility
see QLINK; see
Linking
defined
incremental
Listing files
LIB
preprocessed
Load libraries, QLINK
Loop optimization
/Lr option (QCL)
M
/M option (QLINK)
Macros
NMAKE
$$@
$*
$**
$<
$?
$@
AFLAGS
AS
CC
CFLAGS
defined
defining
dependent names, used for
inherited
MAKE
MAKEDIR
MAKEFLAGS
modifiers
precedence of definitions
precedence
predefined
substitution
target names, used for
testing definition
undefined
user-defined
using
preprocessor, limits
MAKE macro
MAKEDIR macro
MAKEFILE
MAKEFLAGS macro
Map files
/MAP (/M) option (QLINK)
/MAP (/M) option, (QLINK)
contents
creating
QCL
QLINK
extensions
format
frame numbers, obtaining
line numbers
naming with QLINK
MDT (module-description table)
MDT
see Module-description table; see
Medium memory model
see Memory models, medium; see
Memory addresses
see Addresses; see
Memory models
compact
customized
default libraries
default
defined
described
huge
large
medium
mixed
packing segments
small
standard
tiny
variable-stack files
Microsoft QLINK
see QLINK; see
Minus sign (-), LIB command symbol
Minus sign-asterisk (-*), LIB command symbol
command-line example
described
list
Minus sign-plus sign (-+), LIB command symbol
mLIBC7.LIB
MLIBC7.LIB
mLIBCE.LIB
MLIBCE.LIB
Module description table (MDT)
Module-description table (MDT)
Mouse
MSDOS predefined identifier
MSHERC.COM
M_I286 predefined identifier
M_I8086 predefined identifier
M_I86 predefined identifier
M_I86xM predefined identifier
N
/N option (NMAKE)
Names
executable files
code segment, changing
data segment, changing
DOS file
executable files
map files
object files
Naming conventions
/ND option (QCL)
_near keyword
/Za option, used with
default addressing conventions
effects in
data declarations
function declarations
Near pointer
Nesting, declarations
NMAKE directives
!CMDSWITCHES
!ELSE
!ENDIF
!ERROR
!IF
!IFDEF
!IFNDEF
!INCLUDE
!UNDEF
defined
described
listed
operators
using
NMAKE options
/A
/C
/D
/E
/F
/HELP
/I
/N
/NOLOGO
/P
/Q
/R
/S
/T
/X
NMAKE
command line
commands
modifying
specifying
comments in description file
controlling
execution
input
output
dependency lines
dependents
defined
specifying
description blocks
description file
backslash as continuation character
command line
described
error handling
specifying
double-colon (::) separator
error handling
error messages
escape character
exit codes
in-line files
inference rules
defined
defining
precedence
predefined
using
invoking
macro substitution
macros. See Macros, NMAKE
options. See NMAKE options
pseudotargets
response files
special characters
targets
command line
defined
description blocks
specifying
wildcards
NO87 environment variable
/NOD option (QLINK)
default libraries, overriding
described
/NOF option (QLINK)
/NOG option (QLINK)
/NOI option
QLINK
/NOL option
QLINK
/nologo option (QCL)
/NOLOGO option
ILINK
NMAKE
/NON option (QLINK)
/NOP option (QLINK)
NO_EXT_KEYS
/NT option (QCL)
NULL constant
Number sign (#), NMAKE comment character
O
/O option
QCL
/O option
QLINK
Object files
creating
default
extensions
library names
names
defined
inference rules, specified in
LIB input
linking
QCL command line
QLINK command line
QLINK prompts
QLINK response file
naming
/Fo options
default
RMFIXUP.OBJ
variable stack
Object modules
defined
libraries
deleting from
extracting and deleting from
including in
QLINK
listing (LIB)
/Od option (QCL)
/Oi option (QCL)
/Ol option (QCL)
/On option (QCL)
Optimization
far calls
QCL options, used for
Options, LIB
see LIB options; see
Options, QCL
see QCL options; see
Options, QLINK
see QLINK options; see
/Ot option (QCL)
Overlays
debugging
defined
interrupt number, setting
overlay-manager prompts
QLINK, specifying
restrictions
using
/Ox option (QCL)
P
/P option
NMAKE
QCL
pack pragma
/PACKC option (QLINK)
/PACKD option (QLINK)
Packing
contiguous segments
executable files, QLINK
structure members
/PADC option (QLINK)
/PADD option (QLINK)
Palettes
defined
Paragraph space
_pascal keyword
Path names, QCL command line
/PAU option (QLINK)
Physical coordinates
defined
Plus sign (+)
LIB command symbol
QLINK command symbol
Pointers
keywords, _near, _far, _huge
arguments, size conversion
checking
null
subtracting in huge-model programs
Pragmas
check_pointer
check_stack
pack
.PRECIOUS pseudotarget
Preprocessor
limits
listings, creating
predefined identifiers, removing definitions of
preserving comments
PRIVATE combine type
Processors
80186
80286
8086/8088
listings, creating
Pseudotargets
PUBLIC combine type
Public symbols
LIB
QCL
QLINK
Q
/Q option (NMAKE)
QCL command
batch mode operation
command line, described
exit codes
file names
path names
QCL options
/AC
/AH
/AL
/AM
/AS
/Astring
/AT
/batch
/c
/C
/c
/C
/D
/E
/EP
/F
/Fe
/Fm
/Fo
/FPi
/FPi87
/G0
/G1
/G2
/Gc
/Gd
/Ge
/Gi
/Gr
/Gs
/Gt
/Gw
/GW
/HELP
/I
/J
/Lc
/Li
/link
/Lr
/ND
/nologo
/NT
/O
/Od
/Oi
/Ol
/On
/Ot
/Ox
/P
/Ta
/Tc
/U and /u
/V
/W options
/X
/Za
/Zd
/Ze
/Zi
/Zl
/Zp
/Zr
/Zs
8086/8088, 80186, or 80286 processors
assembly language file, specifying
C calling convention
case sensitivity of
CL environment variable, specified in
code segments, naming
command line, order on
constants
data segments, naming
data threshold, setting
debugging, preparing for
default char type, changing
executable files, naming
floating-point
coprocessor
default
emulator
in-line instructions
libraries
format
FORTRAN/Pascal calling convention
include files, searching for
incremental compilation
language extensions, disabling
libraries
floating-point
omitting
standard
listing
map files, creating
memory models
choosing
compact
default libraries
huge
large
medium
small
tiny
variable-stack files
object files, naming
optimization
execution time
maximum
summary
turning off
option characters
output files, naming
predefined identifiers, removing
preprocessor listings
creating
naming
preserving comments
register calling convention
source file, specifying
stack checking
structures, packing
syntax checking
warning levels
QLINK listing files
see Map files; see
QLINK options
.COM file
/BATCH (/BA)
/CODEVIEW (/CO)
/CPARMAXALLOC (/CP)
/DOSSEG (/DO)
/DSALLOCATE (/DS)
/EXEPACK (/E)
/FARCALLTRANSLATION (/F)
/HELP (/HE)
/HIGH (/HI)
/INCREMENTAL (/INC)
/INFORMATION (/INF)
/LINENUMBERS (/LI)
/MAP (/M)
/NODEFAULTLIBRARYSEARCH (/NOD)
default libraries, overriding
described
/NODEFAULTLIBRARYSEARCH (NOD)
described
/NOFARCALLTRANSLATION (/NOF)
/NOGROUPASSOCIATION (/NOG)
/NOIGNORECASE (/NOI)
/NOLOGO (/NOL)
/NONULLSDOSSEG (/NON)
/NOPACKCODE (/NOP)
/OVERLAYINTERRUPT (/O)
/PACKCODE (/PACKC)
/PACKCODE (/PACKC). See also /FARCALLTRANSLATION; /NOPACKCODE
/PACKDATA (/PACKD)
/PADCODE (/PADC)
/PADDATA (/PADD)
/PAUSE (/PAU)
/SEGMENTS (/SE)
/STACK (/ST)
/TINY (/T)
abbreviations
batch mode, running in
case sensitivity
command line, specifying on
compatibility, preserving
controlling process
data loading
debugging
default libraries, ignoring
displaying with /HELP (/HE)
environment variable, using
executable files
loading
modifying
packing
format
line numbers, displaying
linker prompting, preventing
map file
numerical arguments
optimizing
ordering segments
overlay interrupt, setting
paragraph space, allocating
pausing
process information, displaying
QCL, used with
segments
stack size, setting
QLINK
defaults
command line
responses
environment variable
error messages
executable file
exiting
file-name conventions
granularity
libraries
load
overriding
regular
search path
map file
memory requirements
modules, moving
operation
overlays
running
described
prompts
QCL command line
QLINK command line
response file
segments
alignment types
combine types
fixups
frame number
groups
ordering
temporary output file
R
/R option (NMAKE)
Recursion
References
Register calling convention
Registers, DS
Regular libraries, QLINK command line
Relocatable, defined
Relocation information
Response files
LIB
NMAKE
QLINK
Return codes
see Exit codes; see
RMFIXUP.OBJ file
Run-time error messages
S
/S option (NMAKE)
/SE option (QLINK)
Search paths
dependents
include files
libraries
overlays
Segment lists, map files
Segments
alignment types
classes
combining
data threshold, effect of
default names
default
defined
maximum number
order
packing
padding
setup codes
Semicolon
LIB command symbol
NMAKE command separator
QLINK command symbol
sizeof operator
Small memory model
see Memory models, small; see
Source files, specifying
Special characters, NMAKE
Special keywords, turning off
/ST option (QLINK)
STACK
class name
combine type
Stack
defined
probes
size, setting
variable
Standard output device
Structures, packing
.SUFFIXES pseudotarget
Swapping disks during linking
Switches
see Options; see
Symbol tables
T
/T option (QLINK)
/T option
NMAKE
/Ta option (QCL)
Targets
default
defined
macros for
specifying
description blocks
multiple description blocks
/Tc option (QCL)
Temporary files
_TEXT segment
Tiny memory model
see Memory models, tiny; see
TMP environment variable
TOOLS.INI file
!INCLUDE directive, used with
described
ignoring inference rules and macros in
macros
redefining CC in
U
/U and /u options (QCL)
!UNDEF directive (NMAKE)
Uppercase letters, use of
V
/V option (QCL)
/V option
ILINK
Variable-stack files
Variables, special
_edata
_end
Version string, embedding
VM.TMP file
W
/W options (QCL)
Warning error messages
controlling
described
format
listed
Wildcards in NMAKE
Windows functions calls
X
/X option
ILINK
NMAKE
QCL
Z
/Za option (QCL)
/Zd option (QCL)
/Ze option (QCL)
/Zi option (QCL)
/Zl option (QCL)
/Zp option (QCL)
/Zr option (QCL)
/Zs option (QCL)