Build Tools
Build Tools Help

Categories of Options

  Compiler Options

  Linker Options

Alphabetical Reference

  Compiler Options

  Linker Options

  Module-Definition Statements

  Resource Compiler

Other Topics

  Using the Resource Compiler

  Using Search Plus


Compiler Option Quick Reference

Compiler Options A [image] F

/C	/EP	/Fe	/Fp
/c	/F	/FI	/FR
/D	/FA	/Fm	/Fr
/E	/Fd	/Fo
Compiler Options G [image] N

/G	/Gr	/HELP	/MD
/Gd	/Gs	/I	/ML
/Ge	/Gy	/J	/MT
/Gf	/Gz	/LD	/nologo
/Gh	/H	/link
Compiler Options O [image] V

/O1	/Op[-]	/Tc	/vmg
/O2	/Os	/Tp	/vmm
/Oa	/Ot	/U	/vms
/Ob	/Ow	/u	/vmv
/Od	/Ox	/V
/Og	/Oy[-]	/vd
/Oi	/P	/vmb
Compiler Options W [image] Z

/W	/Yu	/Ze	/Zp
/w	/YX	/Zg	/Zs
/X	/Z7	/Zi	/?
/Yc	/Za	/Zl
/Yd	/Zd	/Zn


Compiler Option Quick Reference

Compiler Options A [image] F

/C	/Fd
/c	/Fe
/D	/FI
/E	/Fm
/EP	/Fo
/F	/Fp
/FA	/FR
/Fa	/Fr
Compiler Options G [image] N

/G	/HELP
/Gd	/I
/Ge	/J
/Gf	/LD
/Gh	/link
/Gr	/MD
/Gs	/ML
/Gy	/MT
/Gz	/nologo
/H
Compiler Options O [image] V

/O1	/P
/O2	/Tc
/Oa	/Tp
/Ob	/U
/Od	/u
/Og	/V
/Oi	/vd
/Op[-]	/vmb
/Os	/vmg
/Ot	/vmm
/Ow	/vms
/Ox	/vmv
/Oy[-]
Compiler Options W [image] Z

/W	/Zd
/w	/Ze
/X	/Zg
/Yc	/Zi
/Yd	/Zl
/Yu	/Zn
/YX	/Zp
/Z7	/Zs
/Za	/?


Compiler Option Categories

  Code Generation

  Custom Options

  Custom Options (C++)

  Debug Options

  Listing Files

  Optimizations

  Precompiled Headers

  Preprocessor

  Runtime


Compiler Option Categories

  Code Generation

  Custom Options

  Custom Options (C++)

  Debug Options

  Listing Files

  Optimizations

  Precompiled Headers

  Preprocessor

  Runtime


Linker Option Quick Reference
Linker Option Alphabetical Reference

/ALIGN	/MAP
/BASE	/NODEFAULTLIB
/COMMENT	/NOLOGO
/DEBUG	/OPT
/DEBUGTYPE	/ORDER
/DEF	/OUT
/DEFAULTLIB	/SECTION
/DLL	/STACK
/ENTRY	/STUB
/EXPORT	/SUBSYSTEM
/FIXED	/VERBOSE
/FORCE	/VERSION
/IMPLIB	/WARN
/INCLUDE


Linker Option Quick Reference
Linker Option Alphabetical Reference

/ALIGN	/MAP
/BASE	/NODEFAULTLIB
/COMMENT	/NOLOGO
/DEBUG	/OPT
/DEBUGTYPE	/ORDER
/DEF	/OUT
/DEFAULTLIB	/SECTION
/DLL	/STACK
/ENTRY	/STUB
/EXPORT	/SUBSYSTEM
/FIXED	/VERBOSE
/FORCE	/VERSION
/IMPLIB	/WARN
/INCLUDE


Linker Option Categories

  Debug

  Image Attributes

  Input

  Miscellaneous

  Output


Linker Option Categories

  Debug

  Image Attributes

  Input

  Miscellaneous

  Output


Module-Definition Statements

 CODE

 DATA

 DESCRIPTION

 EXPORTS

 LIBRARY

 NAME

 SECTIONS

 STACKSIZE

 VERSION


Module-Definition Statements

 CODE

 DATA

 DESCRIPTION

 EXPORTS

 LIBRARY

 NAME

 SECTIONS

 STACKSIZE

 VERSION


Using the Resource Compiler

  Including Resources in an Application

  Creating a Resource-Definition File

  Preprocessing Directives

  Single-Line Statements

  Multiline Statements

  Sample Resource-Definition File

  Using RC (The RC Command Line)

  Defining Names for the Preprocessor

  Renaming the Compiled Resource File

  Searching for Files

  Displaying Progress Messages

  Common Statement Parameters

  Common Resource Attributes

  Preprocessing Reference


Using the Resource Compiler

  Including Resources in an Application

  Creating a Resource-Definition File

  Preprocessing Directives

  Single-Line Statements

  Multiline Statements

  Sample Resource-Definition File

  Using RC (The RC Command Line)

  Defining Names for the Preprocessor

  Renaming the Compiled Resource File

  Searching for Files

  Displaying Progress Messages

  Common Statement Parameters

  Common Resource Attributes

  Preprocessing Reference


Resource Compiler Statements
Resource Compiler Reference

Resources

  ACCELERATORS Resource

  CURSOR Resource

  DIALOG Resource

  FONT Resource

  ICON Resource

  MENU Resource

  MESSAGETABLE Resource

  POPUP Resource

  RCDATA Resource

  STRINGTABLE Resource

  User-Defined Resource

  VERSIONINFO Resource

Controls

  AUTO3STATE Control

  AUTOCHECKBOX Control

  AUTORADIOBUTTON Control

  COMBOBOX Control

  CONTROL: General Control

  CTEXT Control

  DEFPUSHBUTTON Control

  EDITTEXT Control

  GROUPBOX Control

  ICON Control

  LISTBOX Control

  LTEXT Control

  PUSHBOX Control

  PUSHBUTTON Control

  RADIOBUTTON Control

  RTEXT Control

  SCROLLBAR Control

  STATE3 Control

Statements

  EXSTYLE Statement

  FONT Statement

  LANGUAGE Statement

  MENU Statement

  MENUITEM Statement

  STYLE Statement

  VERSION Statement


Resource Compiler Reference
Resource-Compiler Reference

Resources

  ACCELERATORS Resource

  CURSOR Resource

  DIALOG Resource

  FONT Resource

  ICON Resource

  MENU Resource

  MESSAGETABLE Resource

  POPUP Resource

  RCDATA Resource

  STRINGTABLE Resource

  User-Defined Resource

  VERSIONINFO Resource

Controls

  AUTO3STATE Control

  AUTOCHECKBOX Control

  AUTORADIOBUTTON Control

  COMBOBOX Control

  CONTROL: General Control

  CTEXT Control

  DEFPUSHBUTTON Control

  EDITTEXT Control

  GROUPBOX Control

  ICON Control

  LISTBOX Control

  LTEXT Control

  PUSHBOX Control

  PUSHBUTTON Control

  RADIOBUTTON Control

  RTEXT Control

  SCROLLBAR Control

  STATE3 Control

Statements

  EXSTYLE Statement

  FONT Statement

  LANGUAGE Statement

  MENU Statement

  MENUITEM Statement

  STYLE Statement

  VERSION Statement


Compiler Options Dialog
C/C++ Compiler Options Dialog

Use the Compiler Options dialog box to set compiler options, either for builds with debugging information or for release builds. Select the category of options that you want set in the Categories list box. Then set the options in the Category group.

The options are set identically for all source files in the project.

An option marked with an asterisks in a list box is the default option for the compiler. This is the option that is implied by the compiler if no option of that type is set in the options string. It is not the default option for the current project type.

The Compiler Options dialog box resolves conflicts among the option types automatically.

Note  Using the controls in the Compiler Options dialog box to set the options string sent to the compiler ensures that the options are known options and that they have the correct form. It also ensures that the options string is internally consistent [image] that is, that options which require or exclude other options are correctly set. You can type any options in the Other Options text box under the Custom Options category, but the dialog box does not ensure that these options are valid or set properly.

Options

  Build Options

  Options String

  Category

  Category Settings

  Use Project Defaults

  Compiler Options Categories

Tips

In the Compiler Options dialog box, you set the values for Compiler options used to build either debug or release versions of projects, by selecting the Debug or Release option button and then choosing the appropriate Compiler options. In the Project dialog box under the Options menu, you specify whether to build a debug or a release version of a project by selecting either the Debug or Release option button.

Pressing F1 when the focus is in the Compiler Options dialog box gives you information about the item which currently has the focus.

You can select an option in the Options String text box and then press F1 to get information about that option. Double-click an option to select it.

The values of the project default options are stored in the MSVC.INI  file. This file is created during installation, and Visual Workbench does not subsequently alter the options in it. If it is deleted, Visual Workbench recreates it.

If you explicitly select either the Optimizing code generator or the Fast code generator (rather than the default choice, Auto Select) in the Code Generation category, options not compatible with those choices are disabled in the dialog box.


Build Options
The type of options displayed in the Options String and set in the Category Settings:

Debug Specific. Options to be used only when you want to include debugging information in your build.

Release Specific. Options to be used only when you want to build a release version.

Common to Both. Options that are used in conjunction with the Release or Debug options for your debug or release builds.


Options String
Internal representation of the string to be passed to the compiler.


Category
List of categories of options to set for a given project type. Select a category to display the controls to set options in the Category Settings group.


Category Settings
Controls to set options in a given category.


Use Project Defaults
Resets all options to the default values for the project. These are the same options that are set when you create a new project of a given type.

Note  These options may be different from the options marked with asterisks in the Category Settings group. Those options marked with asterisks are the implied defaults used by the compiler if no option of that type is set explicitly.

The values of the project default options are stored in the NT Registry. The entries are created during installation, and Visual Workbench does not subsequently alter the options in them. If they are deleted, Visual Workbench recreates them.


Use Project Defaults Button
Use Project Defaults

Resets all options to the default values for the project. These are the same options that are set when you create a new project of a given type.

Note  These options may be different from the options marked with asterisks in the Category Settings group. Those options marked with asterisks are the implied defaults used by the compiler if no option of that type is set explicitly.

The values of the project default options are stored in the NT Registry. The entries are created during installation, and Visual Workbench does not subsequently alter the options in them. If they are deleted, Visual Workbench recreates them.


Compiler: Build Options

You use the Build Options buttons to set the values for compiler options used to build either debug or release versions of projects. You select an option button and then select compiler options to use with that type of build. For instance, if you select the Debug option button, the compiler options that you subsequently select are used to build your project only when you select the Debug Build Mode in the Project Options dialog box. The Release button has a similar effect.

When you select the Common to Both option button, all the compiler options that you subsequently select are used for both Debug builds and for Release builds, along with the respective sets of options chosen for those build modes.


Build Options: Debug

Select Debug to set the options that are used exclusively with the Debug build mode.

Note  All project types define _DEBUG by default for compiler options in the Debug build mode. This is used by the Microsoft Foundation Class libraries and may be disregarded or removed if your project does not use the class libraries. You can open the Compiler Options dialog box and use the Individual Symbols to Undefine edit box in the Preprocessor category to remove it.


Build Options: Release

Select Release to set the options that are used exclusively with the Release build mode.

Note  All project types define NDEBUG by default for compiler options in the Release build mode.


Build Options: Common
Build Options: Common to Both

Select Common to Both to set the options that are used in conjunction with either the selected Debug or Release options, depending on the build mode set in the Project Options dialog box.


Compiler: Code Generation

The Code Generation category includes options for compiling for different CPU types, for selecting calling conventions, and for setting alignment boundaries for structures.

CPU (/G{3|4|5})

The CPU options (/Gn) specify the target processor. The compiler generates instructions for the processor specified by n. /G4 is on by default.

CPU List Box

List Entry	Option	Instructions Generated
80386	/G3	80386
80486	/G4	80486
Pentium	/G5	Pentium
Calling Convention (/Gd, /Gr, /Gz)

The calling convention options determine the order in which arguments passed to functions are pushed on the stack, and which function, calling or called, removes the arguments from the stack.

Calling Convention List Box

List Entry	Option	Calling Convention	Naming Convention
C/C++ (_cdecl)	/Gd	Calling function removes arguments from the stack	Leading underscore added to names; case not altered
C/C++ (_fastcall)	/Gr	Called function removes arguments from the stack; some actual parameters passed in ECX and EDX registers	Leading at-sign and trailing at-sign followed by the size of the arguments in bytes added to names; case not altered
C/C++ (_stdcall)	/Gz	Called function removes arguments from the stack if there is a function prototype and the function has a fixed number of arguments; otherwise the calling function removes arguments	Leading underscore and trailing at-sign followed by the size of the arguments in bytes added to names; case not altered
Struct Member Byte Alignment (/Zp[1|2|4|8|16])

The /Zpn option controls how the members of a structure are packed into memory and specifies the same packing for all structures in a module. When you specify the /Zpn option, where n is 1, 2, 4, 8 or 16, each structure member after the first is stored on n-byte boundaries.

Struct Member Byte Alignment List Box

List Entry	Option	Comment
1 Byte	/Zp1	Pack structures on one-byte boundaries
2 Bytes	/Zp2	Pack structures on two-byte boundaries
4 Bytes	/Zp4	Pack structures on four-byte boundaries
8 Bytes	/Zp8	Pack structures on eight-byte boundaries
16 Bytes	/Zp16	Pack structures on sixteen-byte boundaries
  More information on structure packing and the pack pragma

You can find additional information about packing structures in Programming Techniques.


Compiler: Custom Options

Several miscellaneous options are controlled in this category. These include options for turning off Microsoft language extensions. You can also enable function-level linking, enable string pooling, and select the warning level with custom options.

Disable Microsoft Language Extensions (/Za, /Ze)

Visual C++ supports the ANSI C standard. In addition, it offers a number of features beyond those specified in the ANSI standard. These features are enabled by the /Ze option (the default) and disabled by the /Za option. For a complete list of these extensions, see Chapter 1, "Using the 32-Bit CL," in Build Tools

Enable Function-Level Linking (/Gy)

The /Gy option enables linking on a function-by-function basis by creating packaged functions. A packaged function is visible to the linker in the form of a COMDAT record.

You can exclude unreferenced packaged functions from the executable file by specifying the linkers /OPT:REF option.

  More information on OPT

You can place packaged functions in a specified order in the executable file by using passing the /ORDER option to the linker.

  More information on ORDER

Inline functions are always packaged if they are instantiated (e.g. if inlining is turned off or you take the function address). Also, C++ member functions defined within the class declaration are automatically packaged; other functions are not, and /Gy is required to compile them as packaged functions.

Eliminate Duplicate Strings (/Gf)

The /Gf option enables the compiler to place a single copy of identical strings into the executable file. Because identical strings are copied into a single memory location, programs compiled with the /Gf option can be smaller than those compiled without /Gf. This space optimization is sometimes called "string pooling." Use of /Gf ensures that string pooling occurs in most cases.

Warning Level (/W{0|1|2|3|4})

You can control the number of warning messages produced by the compiler by setting the warning level option and choosing a specific level from the list box. Warning level /W1 displays only severe warnings and is the default (no option mnemonic). /W2 displays intermediate warnings, such as the use of functions with no declared return type, failure to put return statements in functions that aren't void, and data conversions that would cause loss of data or precision. /W3 displays less severe warnings, such as warnings about function calls that precede their function prototypes. /W4 displays warnings such as non-ANSI features and extended keywords.

Note  The Warnings as Errors option (/WX) instructs the compiler to consider any warning message it produces as an error.

Warnings as Errors (/WX)

The /WX option instructs the compiler to consider any warning message it produces as an error. If there are any warning messages, an error message is emitted and compilation continues.

Suppress Display of Sign-On Banner (/nologo)

The /nologo option suppresses display of the sign-on banner when the compiler starts up.

Other Options

The Other Options text box lets you type any CL options independent of the dialog-box controls used by Visual Workbench to set them. This can be useful if you want to use a specific set of command-line options from some other makefile and you don't want to set these options from the dialog box categories.

You are responsible for the accuracy of any option you enter in this text box.

For brief descriptions of all CL options, click Compiler Options under Alphabetical Quick Reference on the Contents page. For a complete description of all CL options, see Chapter 1, "Using the 32-Bit CL," in Build Tools.


Compiler: Custom Options (C++)

Use this category to specify how to represent C++ pointers to class members.

C++ Pointer to Member Representation

Visual C++ supports pointers to members of any class. The number of bytes required to represent a pointer to a member of a class and the code required to interpret the representation varies considerably, depending upon whether the class is defined with no, single, multiple, or virtual inheritance (no inheritance being smallest and virtual inheritance largest).

If you always declare a pointer to a member of a class after defining the class, you can use the default option, which causes the compiler to generate an error when a pointer to a member of a class is declared before the class. This lets the compiler create the best-case representation, since it knows the inheritance model of the class before encountering a pointer to a class member.

If you need to declare a pointer to a member of a class prior to defining the class, you must select the general representation model (/vmg) and then specify the inheritance-model to be assumed for the pointer representation and the code required to interpret the representation.

You can also use the pointers_to_members pragma in your code to determine the pointer representation.

  More information on the pointers_to_members pragma

For additional information on the use of pragmas with pointers to members, see Chapter 7 in the C++ Language Reference.

Representation Method (/vmb, /vmg)

Use the Best-case always option (/vmb) if you always define a class before you declare a pointer to a member of the class.

When the compiler encounters the declaration of a pointer to a member of a class, it already has knowledge of the kind of inheritance used by the class. Thus, the compiler can use the smallest possible representation of a pointer and generate the smallest amount of code required to operate on the pointer for each kind of inheritance.

Use the General-purpose always option (/vmg) if you need to declare a pointer to a member of a class before defining the class. This need can arise if you define members in two different classes that reference each other. For such mutually referencing classes, one class must be referenced before it is defined. You must then select an inheritance model from the General-Purpose Representation list box.

Note  If you choose Best-case always, the General Purpose Representation options do not apply and are disabled. If you choose General-purpose always, the default general-purpose representation is Point to any class (/vmv).

General-Purpose Representation (/vmm, /vms, /vmv)

When the representation method is General-purpose always (/vmg), you must also specify an option to indicate the inheritance model of the not-yet-encountered class definition. This can be one of three options:  /vms (single inheritance), /vmm (multiple inheritance), or /vmv (virtual inheritance). Each of these options specifies the most general representation of a pointer to a member of a class [image] that is, it allows the pointer to point to members of classes with all inheritance models of its specified type or more restrictive types. Each makes a trade-off between flexibility and code size.

When you specify an inheritance model, that model is used for all pointers to member classes, regardless of their inheritance type or whether or not the pointer is declared before or after the class. Therefore, if you know that you always use single-inheritance classes, you can reduce code size by selecting that inheritance model; however, if you want to be safest (at the expense of the largest data representation) you can choose the virtual-inheritance model which allows pointers to all classes.

Disable Construction Displacements (/vd{0|1})

Visual C++ implements C++ construction displacement support. Construction displacements solve the problem created when a virtual function, declared in a virtual base and overridden in a derived class, is called from a constructor during construction of yet a further derived class. The problem is that the virtual function may be passed an incorrect this pointer. This is caused by discrepancies between the displacements to virtual bases of a class and the displacements to its derived classes. The solution provides a single construction displacement adjustment, called a vtordisp field, for each virtual base of a class.

By default, vtordisp fields are introduced whenever the code both defines user-defined constructors and destructors and also overrides virtual functions of virtual bases. The Disable Construction Displacement option (/vd0) lets you disable the construction displacements generation to help optimize program size. Select Disable Construction Displacement only if you are certain that all class constructors and destructors call virtual functions virtually.


Compiler: Debug Options

Use the Debug Options category to specify the type of debugging information to be included in the program.

None

Removes all debugging options from the command line. In this case, no debugging information is generated, and compilation is faster.

Partial (Line Numbers Only) (/Zd)

Produces an object file or executable file containing only global and external symbol and line-number information but not symbolic-debugging information. Use this option if you want to reduce the size of the executable or if you don't want to use the expression evaluator.

Full (C7 Compatible) (/Z7)

Produces an executable file containing line numbers and full symbolic-debugging information for use with the Visual Workbench debugger or with CodeView. This symbolic information is a map of your source code and includes such things as the names and types of variables and functions. The executable file also includes full symbol-table information and line numbers.

Note  This option has the same effect as /Zi in Microsoft C/C++ version 7.

Full (Using Program Database) (/Zi)

Produces a database with types information as well as an executable file containing line numbers and other symbolic-debugging information for use with the Visual Workbench debugger or with CodeView. This symbolic information is a map of your source code and includes such things as the names and types of variables and functions. The executable file also includes full symbol-table information and line numbers. The object files refer to the database file for debugging information. This makes object files smaller. The use of the database file also ensures that debugging information is up to date when using precompiled headers.

The database with types information is named project.PDB. If you compile a file without a project, Visual C++ creates a database named MSVC.PDB.


Compiler: Listing Files

Use the Listing Files category to generate output files for source browser files and code listing files.

For more information on these options, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

Source Browser Files

Source browser files (.SBR) contain symbolic information used by the Microsoft Browser Database Maintenance Utility (BSCMAKE) to produce a browser database file (.BSC) that is used by the Visual Workbench browser. You can cause the compiler to generate .SBR files with or without symbolic information on local variables. You can also turn off the packing of browser files.

Browser Information (/Fr)

Generate .SBR files without symbolic information about local variables.

Include Local Variables (/FR)

Generate .SBR files with complete symbolic information, including information about local variables.

Don't Pack Information (/Zn)

Don't pack information in the .SBR files. This also keeps unreferenced symbol definitions in the .SBR file. You can then run BSCMAKE with the /Iu option to build a .BSC file which includes the unreferenced symbol definitions.

Code Listing Files

Use the Assembly check boxes to generate files containing various combinations of source code, assembly code, and machine code.

Assembly (/FA)

Generate a file with an assembly language listing only. You must select this option to enable the following options for additional listing information.

Include Machine Code (/FAc)

Generate a combined assembly-code and machine-code listing.

Include Source Code (/FAs)

Generate a combined assembly-code and source-code listing.

Note  If you select both the Include Machine Code and the Include Source Code check boxes, /FAcs is included in the options string. In this case, the compiler generates a combined source-code, assembly-code and machine-code listing.


Compiler: Optimizations

The Optimizations category lets you determine how the compiler will tune the performance of your program. Four of the five options buttons (Default, Disable, Maximize Speed and Minimize Size) in the Category Settings section require no further optimization on your part. If you select the fifth option button, Customize, you can set specific customizations using the selections in the list box in the Category Settings.

Default

Select the Default option button to remove all optimization options from the command line. In this case, the compiler favors generation of faster, but possibly larger, machine code. If there is a choice between multiple possible code sequences for an expression, the code generator chooses the fastest sequence.

Disable (Debug) (/Od)

Select the Disable (Debug) option button to create an executable file that contains debug information. This sets the option /Od to disable optimization, which speeds compilation and also makes the program easier to debug by suppressing code reorganization. When you compile with the /Zi option (it is set by default in Debug build mode), you create the debug information used by both the Visual Workbench debugger and CodeView.

Maximize Speed (/O2)

Select the Maximize Speed option button to generate very fast code in the majority of cases. Its effect is the same as using the following options on the same command line:

/Og /Oi /Ot /Oy /Ob1 /Gs /Gf /Gy

These sets of options affect the overall program, in addition to individual code sequences affected by Favor fast code (/Ot) in the Custom Optimizations list.

Note  This option is set by default for release builds.

Minimize Size (/O1)

Select the Minimize Size option button to generate very small code in the majority of cases. Its effect is the same as using the following options on the same command line:

/Og /Os /Ob1 /Gs /Gf /Gy

These sets of options affect the overall program, in addition to individual code sequences affected by Favor small code (/Os) in the Custom Optimizations list.

Customize

Select the Customize option button to set Custom Optimization options. You can then select optimizations using the Custom Optimizations multiple-selection list box.

Custom Optimizations

The Custom Optimizations options are enabled when the Customize option button is selected.

For detailed information on each of these optimizations, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

You may choose from the following optimization options:

Assume no aliasing (/Oa)

Assume aliasing across function calls (/Ow)

Global optimization (/Og)

Generate intrinsic functions (/Oi)

Improve float consistency (/Op)

Favor small code (/Os)

Favor fast code (/Ot)

Control frame pointer omission (/Oy)

Full optimization (/Ox)

If you select Full optimization (the /Ox option), this is a shorthand way to combine optimizing options to produce very fast code in the majority of cases. Its effect is the same as using the following options on the same command line:

/Ob1 /Og /Oi /Ot /Oy /Gs

Inline Expansion of Functions (/Ob{0|1|2})

Inline expansion options control which functions become expanded. Expanding a function inline makes the program faster because it does not incur the overhead of calling the function.  When /Ob1 is used, the compiler only expands functions marked as inline or __inline, or C++ member functions defined within a class declaration. When /Ob2 is used, the compiler expands functions marked as inline or __inline, as well as any other function that the compiler chooses.

Inline Expansion of Functions List Box

List Entry	Option	Description
Disable	/Ob0	Disable inline expansion
Only __inline	/Ob1	Inline expansion is user-defined
Any suitable	/Ob2	Inline expansion at compiler discretion plus user-defined


Compiler: Precompiled Headers

You can greatly speed compile time by compiling any C or C++ files [image] including inline code [image] only once into a precompiled header file (.PCH) and thereafter using the precompiled header for each build. Although the Visual C++ compiler allows several ways to create and use precompiled header files, the Precompiled Headers category in the C/C++ Compiler Options dialog box presents a single, simplified approach to implementing this feature.

You can take two approaches to the use of precompiled header files:

Use automatic precompiled headers.

This is the easiest way to include precompiled headers.

The compiler creates a file named project.PCH if it doesn't exist, and compiles only header files into this precompiled header file. (If you have no project open, it creates a file named MSVC.PCH.) The inclusion of header files stops when the compiler encounters the first declaration, definition, hdrstop pragma, or #line directive in the source file being compiled with the option, or after the header file specified in the Precompile through Header text box.

  Consistency rules with automatic precompiled headers

  Debugging information with automatic precompiled headers

  More information on the hdrstop pragma

Select precompiled headers.

If your project includes source files with both C and C++ code, and you want to use separate precompiled headers for each language, you can select precompiled headers. You can choose distinct filenames for the precompiled header files for both C and C++ files, and include different code in each one. The compiler precompiles all code through the named file. This option allows you to precompile code as well as header files.

  Consistency rules with selected precompiled headers

Note  The compiler ignores hdrstop pragmas in files from projects where you have selected precompiled headers rather than used automatic precompiled headers.

If you are using only one language (that is, only C or only C++), you see one /Yu option followed by the header file name in the Options string. If you are using both languages and specifying precompiled headers, you see two /Yu options, one for each language. The Options string does not display the actual CL command line that is generated. In the actual makefile, a separate /Yu option and /Yc option are generated for each language, on a per-module basis, accompanied by the respective header and source filenames that you specify. The /Yc option does not appear in the Options string.

Automatic Use of Precompiled Headers (/YX)

Check this box to automatically compile and use a precompiled header file named project.PCH. If you choose this option, the C and C++ Files options are disabled.

If you have only one source file in your project, all preprocessor directives up to the first line of C or C++ code are automatically compiled into project.PCH. Any subsequent compilations then use project.PCH instead of the preprocessor directives, provided that they haven't changed in any way.

If you have more than one source file, you must take care to use automatic precompiled headers effectively. You can use automatic precompiled headers in three ways. In all three ways, preprocessor directives must be:

contiguous

in the same order (with the exception of groups of #define statements)

at the beginning of each source file

The three ways are:

Place identical preprocessor code in every file. The compiler creates project.PCH when it compiles the first file, and all subsequent files and all subsequent builds use it.

Place a subset of identical preprocessor directives at the beginning of every file. The compiler creates project.PCH containing all the identical code. During the first build, this method requires the compiler to build project.PCH every time it encounters different preprocessor directives after the subset of identical preprocessor directives. On all subsequent builds, the compiler uses project.PCH instead of the subset of precompiler directives.

Identify in advance the point at which the compiler should stop including preprocessor directives in project.PCH. You can either enter the name of the header file in the Precompile through Header text box, or you can include a hdrstop pragma in a common place in all your source files after the last header file to be included.

Precompile through Header

Use this text box to specify the name of the last header file in the list of header files that are included by every source file. These files are compiled into project.PCH.

C++ Files

Precompile through Header

Use this text box to specify the name of the last header file in the list of header files that are included by every source file. The precompiled header has this base file name with .PCH appended.

Precompile with Source

In the list box, highlight the source file name that includes the list of header files up to the header file specified.

C Files

Precompile through Header

Use this text box to specify the name of the last header file in the list of header files that are included by every source file. The precompiled header has this base file name with .PCH appended.

Precompile with Source

In the list box, highlight the source file name that includes the list of header files up to the header file specified.


Consistency Rules with Automatic Precompiled Headers

The compiler uses the following rules in determining whether rebuild project.PCH or not when it builds the project.

When compiling a project with automatic precompiled headers, the compiler compares the current compilation state with the precompiled header file project.PCH. If project.PCH does not meet the following rules for consistency, the compiler writes a new copy over the existing copy.

The current compiler options must match those specified when the precompiled header was last created.

The current working directory must match that specified when the precompiled header was last created.

The order and values of all #include and #pragma directives must match those specified when the precompiled header was last created. These, along with #define directives, are checked one by one as they appear during subsequent compilations that use the precompiled header. The values of #define directives must match. A group of #define directives in sequence need not occur in exactly the same order, however, since there are no semantic order dependencies for them. The #pragma directives, however, must be identical, except that multiple spaces outside of strings are treated as a single space to allow for different programming styles.

The value and order of include paths specified must match those specified when the precompiled header was last created.

The timestamps of all the header files (all files specified with the #include directives) used to build the precompiled header must match those that existed when the precompiled header was last created.


Consistency Rules with Selected Precompiled Headers

You should take care to specify a consistent environment [image] using consistent compiler options, pragmas, and so on [image] for the current compilation. The compiler uses the following rules in determining whether rebuild precompiled headers or not when it builds the project.

 The compiler compares the current compilation state with the precompiled header file that you have specified. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the .PCH file; rather, they simply warn you of possible conflicts. The compiler does not detect all inconsistencies, however, and the undetected inconsistencies may cause unexpected results.

The following compiler options may trigger an inconsistency warning:

Option	Name	Rule
/D	Define constant	Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if your files depend on the values of the changed constants.
/E or /EP	Send preprocessed output to standard output	Precompiled headers do not work with the /E or /EP option.
/Fr or /FR	Generate Source Browser information	For the /Fr and /FR options to be valid with the /Yu option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single .SBR file and is referenced by other files in the same manner as CodeView information. You cannot override the placement of Source Browser information.
/Zi	Generate CodeView information	If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that CodeView information. If /Zi is not in effect when the precompiled header is created, subsequent compilations that use the precompilation and the /Zi option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header are not available to CodeView.
If the specified include directories (set in the Project Options dialog box or with the /I option) have changed between the last creation of the .PCH file and the current compilation, the compiler uses the current settings regardless of the settings used when the .PCH file was last created.

After you have created and are using a precompiled header, the compiler ignores all preprocessor directives (including pragmas) that appear before the hdrstop pragma. The compilation specified by such preprocessor directives must be the same as the compilation used to create the precompiled header file.

Some pragma directives affect only code within the .PCH file; others affect code that subsequently uses the .PCH file.

The following pragma directives affect code only within the .PCH file:

comment
linesize
message
page
pagesize
skip
subtitle
title

The following pragma directives are retained as part of the precompiled header, but they affect the remainder of the code in a compilation that uses the precompiled header:

alloc_text
auto_inline
check_pointer
check_stack
code_seg
data_seg
function
inline_depth
inline_recursion
intrinsic
loop_opt
native_caller
optimize
pack
same_seg
warning

  More information on pragmas


Debugging Information with Automatic Precompiled Headers

The use of automatic precompiled headers (/YX) implies the use of the /Yd option to include debugging information. The action of the /YX option depends on the other choice of debugging options in the Debug Options category.

If you choose the Full (C7 Compatible) option (/Z7), then every object file created using the precompiled header gets its own copy of debug information from the precompiled header.

If you choose the Full (Using Program Database) option (/Zi), then the compiler behaves as if the /Yd option were not chosen. In this case, it puts debug information from the precompiled header in the first object file created from the .PCH file, and in the program database file. Subsequent object files contain cross-references to the debug information in the first object file.


Compiler: Preprocessor

The Preprocessor category lets you control elements used by the C/C++ preprocessor, such as symbols and macros and include paths. For a list of ANSI and Microsoft-specific predefined macros see the C Language Reference and the C++ Language Reference.

Symbols and Macros to Define (/D)

Use /D to define constants and macros for your source file. This has the same effect as using a #define preprocessor directive at the beginning of your source file. Any identifier or string that contains spaces must be surrounded by double quotation marks. You can assign a number or a string to the identifier using the equal sign (=) with no intervening spaces. If you omit the equal sign, the identifier is assumed to be defined (value of 1).

Type all of the constants and macros you want to define, separated by spaces or commas. You can specify a maximum of 30 identifiers following /D.

Note  All project types define _DEBUG by default for Debug build mode. This is used by the Microsoft Foundation Class libraries and may be disregarded or removed if your project does not use the class libraries. You can use the Individual Symbols to Undefine edit box to remove it.

Individual Symbols to Undefine (/U)

To turn off individual symbols that you have defined or that are predefined, type the names of each symbol, separated by spaces. A /U option is automatically inserted into the build options string for each symbol.

Undefine All Symbols (/u)

To turn off all predefined symbols, select the Undefine All Symbols check box.

  More information on predefined symbols

Include Path (/I)

You can add to the list of directories searched for include files by typing the path in the Include Path text box. To indicate more than one path to search, separate the paths by spaces. When an #include directive is encountered in a program (and a complete path is not provided), the compiler searches the current directory first, then the path or paths specified with the /I option, then the paths specified in the Directories dialog box, accessed from the Options menu.

Ignore Standard Places of Include Files (/X)

You can prevent the compiler from searching the standard places for include files by using the /X (for "exclude") option. This excludes the current directory and any directories listed in the Directories dialog box. You can access this dialog from the Options menu. You can use this option to exclude the files in the standard locations and then use the /I option to include files with the same name as those in the standard location.


Compiler: Preprocessor
Compiler: Runtime

The Runtime category lets you select either single-threaded or multi-threaded run-time routines, and to indicate that a multi-threaded module is a DLL.

For more information on these options, see Creating DLLs for Windows NT in Programming Techniques.

Single-threaded (LIBC.LIB) (/ML)

The /ML option causes the compiler to place the library name LIBC.LIB into the object file so that the linker will use LIBC.LIB to resolve external symbols. This is the compilers default action. LIBC.LIB does not provide multi-thread support.

Multi-threaded (LIBCMT.LIB) (/MT)

The /MT option causes the driver to define _MT so that multithread-specific versions of the run-time routines are selected from the standard header files. It also causes the compiler to place the library name LIBCMT.LIB into the object file so that the linker will use LIBCMT.LIB to resolve external symbols.

Multi-threaded using DLL (MSVCRT.LIB) (/MD)

The /MD option causes the driver to define _MT and _DLL so that both multithread- and DLL-specific versions of the run-time routines are selected from the standard header files. It also causes the compiler to place the library name MSVCRT.LIB into the object file.

Applications compiled with /MD are statically linked to MSVCRT.LIB. This library provides a layer of code that allows the linker to resolve external references. The actual working code is contained in MSVCRT10.DLL, which must be available at run time to applications linked with MSVCRT.LIB.


/c

Compile without linking

Category

  Custom Options: Other Options


/C

Preserve comments in preprocessed output

Category

  Custom Options: Other Options


/D
/Did[=|#[value]]

Define constants and macros. For more information, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

Category

  Preprocessor: Symbols and Macros to Define


/E

Emit #line directives in preprocessed output. /E suppresses compilation as well as production of the alternate output files that the /Fa, /Fc, /Fl, /Fm, or /Fs options generate.

Category

  Custom Options: Other Options


/EP

Remove #line directives from preprocessed output

Category

  Custom Options: Other Options


/F
/F number

Set stack size. number can be decimal, hexadecimal beginning with 0x or octal beginning with 0.

See Chapter 1, "Using the 32-Bit CL," in Build Tools for more information on stack size.

Category

  Custom Options: Other Options


/Fa
/Fa [file]

Rename assembly listing. You can use /Fa in conjunction with /FA to rename the output file.

Category

  Custom Options: Other Options


/FA[s][c]

Create a listing file with assembly-language, source and/or machine code. The default is an assembly-language code listing in a file with the source code base name and the default extension .ASM. If either c, for machine code, or s, for source code, is appended, the default extension is .COD.

Category

  Listing Files: Assembly


/Fd
/Fd file

Name the program database file with types information for debugging. Used in conjunction with the /Zi option.

Category

  Custom Options: Other Options


/Fe
/Fe [file]

Rename executable file. When specified together with /c, linking is suppressed and /Fe is ignored.

Category

  Custom Options: Other Options


/FI
/FIheaderfile

Preprocesses headerfile before any other files specified by #include directives in the source files. This option can appear multiple times, and the files are processed in the order the options occur. It is useful for porting source code.

Category

  Custom Options: Other Options


/Fm
/Fm [file]

Create linker map. When specified together with /c, linking is suppressed and /Fm is ignored.

Category

  Custom Options: Other Options


/Fo
/Fo [file]

Rename object file

Category

  Custom Options: Other Options


/Fp
/Fp file

Specify precompiled header filename. This option is for use in external makefiles only and cannot be set from within Visual Workbench.


/FR
/FR [file]

Create source browser information (.SBR file) that includes local variables

Category

  Listing Files: Include Local Variables


/Fr
/Fr [file]

Create source browser information (.SBR file) that does not include local variables

Category

  Listing Files: Browser Information


/G
/G{3|4|5}

Generate instructions for specified processor, where 3 specifies 80386, 4 specifies 80486, and 5 specifies Pentium. /G4 (generate 80486 instructions) is implied by default if no option of this type is set.

Category

  Code Generation: CPU


/Gd

Use the C/C++ calling convention. This option is on by default.

Category

  Code Generation: Calling Convention: C/C++


/Ge

Use stack-check calls for functions in all source files. You can disable stack-check calls explicitly with the /Gs option.

Category

  Custom Options: Other Options


/Ge

Use stack-check calls for functions in all source files. You can disable stack-check calls explicitly with the /Gs option.

Category

  Custom Options: Other Options


/Gf

Place a single copy of identical strings into the executable file

Category

  Custom Options: Eliminate Duplicate Strings


/Gh

Generate a call to a helper function named _ _penter as the first line of code in every method or function call. This call is a hook to a function _ _penter that you must write; the run-time libraries do not supply it. Your _ _penter function can do anything you choose, with one restriction: It must not modify the content of any register [image] it must push the content of all registers on entry and pop the unchanged content on exit. The compiler does not generate a call to _ _penter for methods or functions that it generates inline.

Category

  Custom Options: Other Options


/Gr

Use fastcall calling convention

Category

  Custom Options: Other Options


/Gs
/Gs[size]

Enable stack-check calls for functions that require more than size stack space for local variables. The stack-check calls are enabled in all source files.

If no explicit value is present for size, the default value is one page (4K for Intel x86 processors, /Gs4096). If size is present, it indicates the memory threshold at which stack check calls are generated. You can disable stack-check calls by setting size to a value larger than any function requires for local variables. Do not change the default setting of /Gs unless you know exactly why you need to change it.

You can enable stack-check calls for all functions with /Gs0 or with the /Ge option. /Gs4096 is the implied default option if neither it nor /Ge is set.

For more information, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

Category

  Custom Options: Other Options


/Gy

Generate packaged functions for linker

Category

  Custom Options: Enable Function-Level Linking


/Gz

Use the _ _stdcall calling convention for functions.

The /Gz option specifies that, for all prototyped C functions that do not take a variable number of arguments and are not marked as _ _cdecl or _ _fastcall, the called function's actual parameters are pushed onto the stack from left to right, and the calling function must pop these parameters from the stack.

The /Gz option has no effect on C++ methods and functions.

The /Gz option (and the _ _stdcall convention) do not translate the case of function names, and they use the following naming convention: an underscore ( _ ), followed by the function name, followed by an at-sign (@), followed by the size of the function's parameters in bytes.

Category

  Code Generation: Calling Convention


/H
/Hn

Set maximum external (public) name length to n characters

The compiler has no limit on length of external names, but other tools that operate on object files generated by the compiler [image] such as linkers [image] may have such limits.

Category

  Custom Options: Other Options


/HELP

Display Help for compiler options.

Category

  Custom Options: Other Options


/I
/Idirectory

Set additional include-file directories

Category

  Preprocessor: Include Path


/J

Change default character type to unsigned char

Category

  Custom Options: Other Options


/LD

Compile and link a program as a dynamic-link library (DLL). The /LD option does the following:

Causes the compiler to pass the -DLL option to the linker

Causes the linker to link the DLL startup code. You must have a function named DllMain in your source code.

Causes LIB to produce an import library, if an export file (.EXP) is not specified on the command line, to be linked to applications that call your DLL.

Interprets /Fe as naming a DLL rather than an executable file; the default program name becomes basename.DLL instead of basename.EXE.

Changes default run-time library support to /MT if you have not explicitly specified one of /MD, /ML, or /MT.

For important information on creating DLLs, see Creating DLLs for Windows NT in Programming Techniques.

Category

  Custom Options: Other Options


/link
/link [option1 [option2 ...]]

Pass the linker options and their arguments, if any, to LINK.

This option and its associated linker options must follow any source or object filenames, and any other CL options

Category

  Custom Options: Other Options


/MD

Link using MSVCRT.LIB.

This option defines _MT and _DLL, so that multithread- and DLL-specific versions of run-time functions are selected in the standard header files. It also places the library name MSVCRT.LIB in the object file for LINK to use to resolve external symbols. MSVCRT10.DLL must be available to the application at run-time.

Category

  Runtime: Multi-threaded (MSVCRT.LIB)


/ML

Link using LIBC.LIB.

This option places the library name LIBC.LIB in the object file for LINK to use to resolve external symbols. This is the compiler's default action.

Category

  Runtime: Single-threaded (LIBC.LIB)


/MT

Link using LIBCMT.LIB.

This option defines _MT, so that multithread-specific versions of run-time functions are selected in the standard header files. It also places the library name LIBCMT.LIB in the object file for LINK to use to resolve external symbols.

Category

  Runtime: Multi-threaded (LIBCMT.LIB)


/nologo

Suppress copyright message

Category

  Custom Options: Suppress Display of Sign-On Banner


/Oa

Assume no aliasing.

Category

  Optimizations: Custom Optimizations: Assume no aliasing


/Ob
/Ob{0|1|2}

Set inline expansion. /Ob0 means inline no functions; /Ob1 means inline only functions declared __inline; /Ob2 means inline any suitable functions, including functions marked __inline. The functions that the compiler actually puts inline depend also on the /OV setting.

Category

  Optimizations: Inline Expansion of Functions


/Od

Disable all optimization

Category

  Optimizations: Disable (Debug)


/Og

Perform global optimization.

The compiler performs the following set of optimizations:

Local and global common subexpression elimination

Automatic register allocation of variables and subexpressions

Loop optimizations

Common function-exit sequence

For more information on the /Og option, see Chapter 1, "Using 32-bit CL," in Build Tools.

Category

  Optimizations: Custom Optimizations: Global-level common subexpr. optimization


/Oi

Generate intrinsic functions.

This option replaces the following function calls with their inline forms:

_alloca	_lrotl	_rotr	labs	strcmp
_disable	_lrotr	_setjmp	memcmp	strcpy
_enable	_outp	_strset	memcpy	strlen
_inp	_outpw	abs	memset
_inpw	_rotl	fabs	strcat
For the following floating-point functions, with /Oi specified, the compiler uses versions that pass arguments directly to the floating-point coprocessor instead of pushing them onto the program stack:

acos	cos	fmod	pow	sqrt
asin	cosh	log	sin	tan
atan	exp	log10	sinh	tanh
atan2
Category

  Optimizations: Custom Optimizations: Generate intrinsic functions


/Op
/Op[-]

Improve consistency of floating-point tests for equality and inequality. This option disables optimizations that allow the compiler to store some intermediate results in coprocessor registers. These registers are typically larger than memory locations and thus change the degree of precision of floating-point calculations.

The /Za option (strict ANSI conformance) implies /Op. You can use /Op- to override the implied option in this case.

Category

  Optimizations: Custom Optimizations: Improve float consistency (/Op)

  Custom Options: Other Options (/Op-)


/Os

Favor generation of smaller, but possibly slower, machine code. If there is a choice between multiple possible code sequences for an expression, the code generator chooses the smallest sequence.

See Also

/O1

Category

  Optimizations: Custom Optimizations: Favor small code


/Ot
/O[t]

Favor generation of faster, but possibly larger, machine code. If there is a choice between multiple possible code sequences for an expression, the code generator chooses the fastest sequence. This is the default action

See Also

/O2

Category

  Optimizations: Custom Optimizations: Favor fast code


/Ow

Assume aliasing only across function calls.

Category

  Optimizations: Custom Optimizations: Assume aliasing across function calls


/Ox

Use maximum optimizations. /Ox is a shorthand way to specify all of the following command-line options:

/Ob1 /Og /Oi /Ot /Oy /Gs

See Also

/O1
/O2

Category

  Optimizations: Custom Optimizations: Full optimization


/Oy
/Oy[-]

Suppress the creation of frame pointers on the call stack. It speeds function calls, and it frees the EBP register to store frequently used variables and subexpressions.

Note Do not use this option if you use EBP-based addressing.

Category

  Optimizations: Custom Optimizations: Frame pointer omission


/O1

Generate a very small program. Its effect is the same as using the following options on the same command line:

/Og /Os /Ob1 /Gs /Gf /Gy

These sets of options affect the overall program, in addition to individual code sequences affected by /Os.

Category

  Optimizations: Minimize Size


/O2

Generate a very fast program. Its effect is the same as using the following options on the same command line:

/Og /Oi /Ot /Oy /Ob1 /Gs /Gf /Gy

These sets of options affect the overall program, in addition to individual code sequences affected by /Ot.

Category

  Optimizations: Maximize Speed


/P

Send preprocessed output to a file with the same base name as the source file, but with the .I extension. This option adds #line directives to the output.

Category

  Custom Options: Other Options


/Tc
/Tc file

Specify C source file

Category

  Custom Options: Other Options


/Tp
/Tp file

Specify C++ source file

Category

  Custom Options: Other Options


/u

Remove all predefined identifiers

For a list of predefined identifiers, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

Category

  Preprocessor: Undefine All Symbols


/U
/U id

Remove specified identifier

Category

  Preprocessor: Individual Symbols to Undefine


/V
/V string

Set version string. If string contains white-space characters in must be included in double quotation marks (" "). An escape character (\) must precede all embedded double quotation marks.

Category

  Custom Options: Other Options


/vd{0|1}

Suppress (/vd0) or enable (/vd1) hidden vtordisp constructor/destructor displacement members for C++ code that uses virtual base classes.

Category

  Custom Options (C++): Disable Construction Displacements


/vmb

Use best case for pointers to class members

Category

  Custom Options (C++): Representation Method


/vmg

Use full generality for pointers to class members

Category

  Custom Options (C++): Representation Method


/vmm

Declare multiple inheritance

Category

  Custom Options (C++): General-Purpose Representation


/vms

Declare single inheritance

Category

  Custom Options (C++): General-Purpose Representation


/vmv

Declare virtual inheritance

Category

  Custom Options (C++): General-Purpose Representation


/w

Turn off all warning messages. /w and /W0 are synonymous.

Category

  Custom Options: Other Options


/W
/W{0|1|2|3|4|X}

Set warning level. /WX reports all warnings as errors. /w and /W0 are synonymous: Both turn off all warning messages.

Category

  Custom Options: Warning Level

  Custom Options: Warnings as Errors


/X

Ignore standard include directory

Category

  Preprocessor: Ignore Standard Places of Include Files


/Yc
/Yc[file]

Create precompiled header.

In the Compiler Options dialog box, specifying a file in the Precompiled Header: Precompile through Header text box (for either C or C++ files) causes the compiler to place /Yu in the Build Options string. Visual Workbench then automatically inserts /Yc in the project makefile.

You can explicitly specify /Yc in external projects.


/Yd

Include debugging information for precompiled headers in all object files. Use this option witn /Z7 to include the expected debugging information in the object files. The /YX option implies /Yd.

Category

  Custom Options: Other Options


/Yu
/Yu[file]

Use precompiled header. If file is specified, it must be the file specified when /Yc was used to create the precompiled header.

Categories

  Precompiled Headers: C Files: Precompile through Header

  Precompiled Headers: C++ Files: Precompile through Header


/YX
/YX[file]

Use precompiled headers automatically. It precompiles header files only. It uses project.PCH, if that file exists, or creates project.PCH if it doesn't exist. If you specify a filename, it compiles header files up to that file. Otherwise, the inclusion of header files stops when the compiler encounters the first declaration, definition, hdrstop pragma, or #line directive in the source file being compiled with this option.

You can use /Fp in external makefiles to change the name for the precompiled header file.

Category

  Precompiled Headers: Automatic Use of Precompiled Headers


/Za

Compile for ANSI compatibility. This option disables Microsoft language extensions. When it is turned off, /Ze (the default) is automatically set.

Category

  Custom Options: Disable Microsoft Language Extensions (selected)


/Zd

Compile for debugging. Produces an object file or executable file containing line-number information but not symbolic-debugging information.

Category

  Debug Options: Partial (Line Numbers Only)


/Ze

Enable Microsoft language extensions. This option is on by default. When it is turned off, /Za is automatically set.

For a list of Microsoft extensions, see Chapter 1, "Using the 32-Bit CL," in Build Tools.

Category

  Custom Options: Disable Microsoft Language Extensions (cleared)


/Zg

Generate function prototypes

Category

  Custom Options: Other Options


/Zi

Compile for debugging. Produces a database with types information as well as an object file or executable file containing line-number information as well as full symbolic-debugging information. The database file is named project.PDB by default. You can use the /Fd option to name the database file.

Category

  Debug Options: Full (Using Program Database)


/Zl

Remove default-library name from object file

Category

  Custom Options: Other Options


/Zn

Turn off packing of browser files

Category

  Listing Files: Don't Pack Information


/Zp
/Zp[1|2|4|8|16]

Pack structure members on 1-, 2,- 4-, 8-, or 16-byte boundaries

Category

  Code Generation: Struct Member Byte Alignment


/Zs

Check syntax only

Category

  Custom Options: Other Options


/Z7

Compile for debugging. Produces an object file or executable file containing line-number information as well as full symbolic-debugging information.

If you are using precompiled headers, use /Yd or /YX to place debugging information for precompiled headers in object files.

Note  This is equivalent to /Zi in Microsoft C/C++ version 7.

Category

  Debug Options: Full (C7 Compatible)


Copyright Notice
Copyright Notice for Visual Workbench Help

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without express written permission of Microsoft Corporation.

© 1993 Microsoft Corporation. All rights reserved.

Microsoft is a registered trademark and Windows and Windows NT are trademarks of Microsoft Corporation.


Linker Options Dialog

Use the Linker Options dialog box to set linker options, either for builds with debugging information or for release builds. Select the category of options that you want set in the Categories list box. Then set the options in the Category group.

The Linker Options dialog box resolves conflicts among the option types automatically.

The options are set identically for all files in the project.

Note  Using the controls in the Linker Options dialog box to set the options string sent to the linker ensures that the options are known options and that they have the correct form. You can type any options in the text box under the Miscellaneous Options category, but the dialog box does not ensure that these options are valid or set properly.

Options

  Build Options

  Options String

  Category

  Category Settings

  Use Project Defaults

  Linker Options Categories

Tips

In the Linker Options dialog box, you set the values for linker options used to build either debug or release versions of projects, by selecting the Debug or Release option button and then choosing the appropriate linker options. In the Project dialog box under the Options menu, you specify whether to build a debug or a release version of a project by selecting either the Debug or Release option button.

Pressing F1 when the focus is in the Linker Options dialog box gives you information about the item which currently has the focus.

You can select an option in the Options String text box and then press F1 to get information about that option. Double-click an option to select it.


Build Options
The type of options displayed in the Options String and set in the Category Settings:

Debug Specific. Options to be used only when you want to include debugging information in your build.

Release Specific. Options to be used only when you want to build a release version.

Common to Both. Options that are used in conjunction with the Release or Debug options for your debug or release builds.


Options String
Internal representation of the string to be passed to the linker.


Category
List of categories of options to set for a given project type. Select a category to display the controls to set options in the Category Settings group.


Category Settings
Controls to set options in a given category.


Use Project Defaults
Resets all options to the default values for the project. These are the same options that are set when you create a new project of a given type.


Linker: Build Options

You use the Build Options buttons to set the values for linker options used to build either debug or release versions of projects. You select an option button and then select linker options to use with that type of build. For instance, if you select the Debug option button, the linker options that you subsequently select are used to build your project only when you select the Debug Build Mode in the Project Options dialog box. The Release button has a similar effect.

When you select the Common to Both option button, all the linker options that you subsequently select are used for both Debug builds and for Release builds, along with the respective sets of options chosen for those build modes.


Linker: Debug

The options in the Debug category of the Linker dialog box control mapping and debugging information.

Generate Mapfile Check Box

Produce a mapfile with the base name of the output file and the extension .MAP. Command-line equivalent: /MAP

Mapfile Name Text Box

Name the mapfile and override the default name. The Mapfile Name text box is unavailable if Generate Mapfile is not chosen. Command-line equivalent: /MAP:filename.

Generate Debugging Information Check Box

Put debugging information in the output file. Command-line equivalent: /DEBUG.

CodeView, COFF, and Both Buttons

Specify the format of debugging information. The CodeView Format choice creates Microsoft Symbolic Debugging Information for the Visual Workbench debugger and Microsoft CodeView. The COFF Format choice creates COFF debugging information for compatibility with NTSD (not provided with Visual C++) and other tools. Command-line equivalent: /DEBUGTYPE:CV, /DEBUGTYPE:COFF, or /DEBUGTYPE:BOTH.


Linker: Image Attributes

The options in the Image category of the Linker dialog box affect the executable image.

Stack Allocations Text Boxes

Set the stack size. The Reserve text box sets the total stack space in virtual memory. The Commit text box sets the amount of memory to allocate each time the stack grows. The Commit text box is unavailable if Reserve is not chosen. Command-line equivalent: /STACK:reserve,commit.

Base Address Text Box

Set the base address of the executable image. Command-line equivalent: /BASE:address.

Entry-Point Symbol Text Box

Set the starting address for the program. Command-line equivalent: /ENTRY:function.


Linker: Input

The options in the Input category of the Linker dialog box specify input to the linker.

Object/Library Modules Text Box

Specify additional libraries and object files. This text box sets command-line arguments rather than an option. Command-line equivalent: filename.

Ignore All Default Libraries Check Box

Remove all default libraries from the library search. Default libraries are specified in object files or with the /DEFAULTLIB option. Command-line equivalent: /NODEFAULTLIB.

Ignore Specific Libraries Text Box

Remove the specified default libraries from the library search. When Ignore All Default Libraries is chosen, this text box is not made unavailable but the option it generates has no effect. Command-line equivalent: /NODEFAULTLIB:library.

Include Symbols Text Box

Force a reference to a symbol, to cause the symbol's object to be linked. Command-line equivalent: /INCLUDE:symbol.

Name of .DEF File Text Box

Specify a module-definition file. Command-line equivalent: /DEF:filename.

MS-DOS Stub Filename Text Box

Add the specified MS-DOS program to the beginning of the output file. Command-line equivalent: /STUB:filename.


Linker: Miscellaneous

The options in the Miscellaneous category of the Linker dialog box pass additional options to the linker.

Version Information Text Boxes

Write a version number in the header of the output file. The Major and Minor text boxes set the major and minor parts of the number, respectively. The Minor text box is unavailable if Major is not chosen. Command-line equivalent: /VERSION:major.minor.

Verbose Check Box

Display additional information about the linking process. Command-line equivalent: /VERBOSE.

Suppress Display of Sign-On Banner Text Box

Prevent display of the linker copyright message. Command-line equivalent: /NOLOGO.

Other Options Text Box

Add the specified options to the LINK command line. If an option is represented by a choice in the Linker Options dialog box, Visual Workbench sets the corresponding choice and removes the option from Other Options. For details about the use of each LINK option, see Linker Option Alphabetical Reference.


Linker: Output

The options in the Output category of the Linker dialog box control how the output file is created.

Force File Output Check Box

Create an output file even if a symbol is undefined. Command-line equivalent: /FORCE.

Name of Output File Text Box

Name the executable or DLL file and override the default name. Command-line equivalent: /OUT:filename.


The /ALIGN Option
/ALIGN

Sets the section alignment within the address space of the image.

Syntax

/ALIGN:number

Category

Miscellaneous: Other Options

This option specifies the alignment of each section within the linear address space of the image file. The number argument is in bytes and must be a multiple of 512. The default is 4K. The linker generates a warning if the alignment might produce an invalid image.


The /BASE Option
/BASE

Specifies the default base address for the executable file or DLL.

Syntax

/BASE:{address|@filename,key}

Category

Image Attributes: Base Address

This option sets a base address for the image, overriding the default location for an executable file (at 0x10000) or a DLL (at 0x400000). The operating system will first attempt to load the image at the specified base address. If sufficient space is not available there, the system will relocate the image. To prevent relocation, use the /FIXED option.

The address argument specifies the preferred base address. LINK rounds the specified number up to the nearest multiple of 64K.

Another way to specify the base address is by using a filename, preceded by an at sign (@), and a key into the file. The filename is a text file that contains the locations and sizes of all DLLs that your program will use. LINK looks for filename in either the specified path or, if no path is specified, in directories specified in the LIB environment variable. Each line in filename represents one DLL and has the following syntax:

key address size ;comment

The key is a string of alphanumeric characters and is not case sensitive. It is usually the name of a DLL but it need not be. The key is followed by a base address in C-notation hexadecimal or decimal and a maximum size. All three arguments are separated by spaces or tabs. LINK issues a warning if the specified size is less than the virtual address space required by the image. A comment is specified by a semicolon (;) and can be on the same or a separate line. LINK ignores all text from the semicolon to the end of the line. An example of part of such a file is as follows:

main   0x00010000    0x08000000    ; for PROJECT.EXE

one    0x28000000    0x00100000    ; for DLLONE.DLL

two    0x28100000    0x00300000    ; for DLLTWO.DLL

If the file is called DLLS.TXT, the following example command applies this information:

link dlltwo.obj /dll /base:dlls.txt,two

You can reduce paging and improve performance of your program by assigning base addresses so that DLLs do not overlap in the address space.

An alternate way to set the base address is with the BASE argument in a NAME or LIBRARY statement. The /BASE and /DLL options together are equivalent to the LIBRARY statement.


The /COMMENT Option
/COMMENT

Inserts a string into the executable file or DLL.

Syntax

/COMMENT:["]comment["]

Category

Miscellaneous: Other Options

This option inserts a comment string into the header of an image file, after the array of section headers. The type of operating system determines whether the string is loaded into memory. This comment string, unlike the comment specified with the DESCRIPTION statement in a .DEF file, is not inserted into the data section. Comments are useful for embedding copyright and version information.

To specify a comment that contains spaces or tabs, enclose it in double quotation marks ("). LINK removes the quotation marks before inserting the string. If more than one /COMMENT option is specified, LINK concatenates the strings and places a null byte at the end of each string.


The /DEBUG Option
/DEBUG

Puts debugging information into the image file.

Syntax

/DEBUG

Category

Debug: Debugging Information

This option adds debugging information to the main output file. Debugging information must exist in the object files; use the /Zi, /Zd, or /Z7 option when compiling with CL. If an object was compiled with /Zi, or if a library contains an object that was compiled with /Zi, debugging information is stored in a program database (PDB). The object contains the name and location of the PDB. LINK looks for the PDB in the following locations in this order:

1.	The absolute path written in the object

2.	The directory that LINK is running from

3.	Any directories specified in the LINK environment variable

LINK does not look in the directory that contains the object file or library that uses the PDB. You cannot specify a PDB's filename or location on the LINK command line.

When /DEBUG is used, LINK calls the CVPACK tool after linking the program. CVPACK.EXE must be in the same directory as LINK.EXE or in a directory specified in the PATH environment variable.

The /DEBUG option changes the default for the /OPT option from REF to NOREF.


The /DEBUGTYPE Option
/DEBUGTYPE

Specifies the format for debugging information.

Syntax

/DEBUGTYPE:{CV|COFF|BOTH}

Category

Debug: Debugging Information Type

This option determines the type of debugging information to be included in the image file. Specify one of the following keywords:

Keyword	Format of debugging information
CV	Microsoft Symbolic Debugging Information, used by CodeView, Visual Workbench, and some other debuggers
COFF	Common Object File Format, used by other COFF debuggers
BOTH	Both CV and COFF formats
If no option is specified, the default is CV. If more than one option is specified, both formats are put into the image file. LINK ignores /DEBUGTYPE if /DEBUG is not specified.


The /DEF Option
/DEF

Specifies a .DEF file.

Syntax

/DEF:filename

Category

Input: Name of .DEF File

This option passes a module-definition (.DEF) file to the linker. Only one .DEF file can be specified to LINK.


The /DEFAULTLIB Option
/DEFAULTLIB

Adds a default library name to the library search.

Syntax

/DEFAULTLIB:library[,library...]

Category

Miscellaneous: Other Options

This option adds a library to the list of libraries that LINK searches when resolving references. The library is searched after libraries specified on the command line and before default libraries named in object files.

If the /NODEFAULTLIB option is specified, either with no filename or with the same filename as given with /DEFAULTLIB, the /DEFAULTLIB option is ignored.


The /DLL Option
/DLL

Creates a dynamic-link library.

Syntax

/DLL

Category

This option is set when you choose Dynamic Link Library (DLL) in the Project Type drop-down list box in the Project Options dialog box. Do not specify this option in Other Options in the Miscellaneous category.

This option builds a DLL as the main output file. A DLL usually contains exports that can be used by another program. There are three methods for specifying exports, listed in recommended order of use:

•	The __declspec(dllexport) keyword in the source code

•	An /EXPORT specification in a LINK command

•	An EXPORTS statement in a .DEF file

A program can use more than one method.

An alternate way to build a DLL is with the LIBRARY module-definition statement. The /BASE and /DLL options together are equivalent to the LIBRARY statement.


The /ENTRY Option
/ENTRY

Specifies the starting address of an image.

Syntax

/ENTRY:function

Category

Image Attributes: Entry-Point Symbol

This option sets the starting address for an executable file or DLL. Specify a function that is defined with the __stdcall calling convention. The function parameters and return value must be defined as documented in the Win32 API for WinMain (for an .EXE) or DllEntryPoint (for a DLL). It is recommended that you let LINK set the entry point so that the C run-time library is initialized correctly and C++ constructors for static objects are executed.

By default, the starting address is a function name from the C run-time library. LINK selects it according to the attributes of the image, as follows:

Function name	Default for
_mainCRTStartup	Application using /SUBSYSTEM:CONSOLE; calls main
_WinMainCRTStartup	Application using /SUBSYSTEM:WINDOWS; calls WinMain (which must be defined with __stdcall)
__DllMainCRTStartup	DLL; calls DllMain (which must be defined with __stdcall) if it exists
If /DLL or /SUBSYSTEM is not specified, LINK selects a subsystem and entry point depending on whether main or WinMain is defined.

The functions main, WinMain, and DllMain are the three forms of the user-defined entry point.


The /EXPORT Option
/EXPORT

Specifies a definition to be exported.

Syntax

/EXPORT:entryname[=internalname][,@ordinal[,NONAME]][,DATA]

Category

Miscellaneous: Other Options

This option lets you export a function from your program to allow other programs to call the function. You can also export data. Exports are usually defined in a DLL.

The entryname is the name of the function or data item as it is to be used by the calling program. You can optionally specify the internalname as the function known in the defining program; by default, internalname is the same as entryname. The ordinal specifies an index into the exports table in the range 1 − 65565; if you do not specify ordinal, LINK assigns one. The NONAME keyword exports the function only as an ordinal, without an entryname.

The DATA keyword specifies that the exported item is a data item. The data item in the client program must be declared using extern __declspec(dllimport). The CONSTANT keyword is supported for compatibility but is not recommended.

There are three methods for exporting a definition, listed in recommended order of use:

•	The __declspec(dllexport) keyword in the source code

•	An /EXPORT specification in a LINK command

•	An EXPORTS statement in a .DEF file

All three methods can be used in the same program. When LINK builds a program that contains exports, it also creates an import library, unless an .EXP file is used in the build.

LINK uses decorated forms of identifiers. CL decorates an identifier when it creates the object file. If entryname or internalname is specified to the linker in its undecorated form as it appears in the source code, LINK attempts to match the name. If it cannot find a unique match, LINK issues an error. Use the DUMPBIN tool to get the decorated form of an identifier when you need to specify it to the linker.


The /FIXED Option
/FIXED

Suppresses relocation of the image in memory.

Syntax

/FIXED

Category

Miscellaneous: Other Options

This option tells the operating system to load the image file only at its preferred base address. If the preferred base address is unavailable, the operating system will not load the file. For more information on base addresses, see the description of the /BASE option.

When /FIXED is specified, LINK does not generate a relocation section in the image file. At run time, if the operating system is unable to load the image at that address, it issues an error and does not load the program.

Some Win32 operating systems, especially those that coexist with MS-DOS, frequently must relocate an image.


The /FORCE Option
/FORCE

Creates an image file despite unresolved externals.

Syntax

/FORCE

Category

Output: Force File Output

This option tells LINK to create a valid image file even if a symbol is referenced but not defined. LINK issues a warning for each undefined symbol. By default, LINK does not generate an image file when an unresolved external is found.

A file created with /FORCE may not run as expected if there are undefined symbols.


The /IMPLIB Option
/IMPLIB

Names the import library.

Syntax

/IMPLIB:filename

Category

Miscellaneous: Other Options

This option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension .LIB. A program contains exports if one or more of the following are specified:

•	The __declspec(dllexport) keyword in the source code

•	An /EXPORT specification in a LINK command

•	An EXPORTS statement in a .DEF file

LINK ignores /IMPLIB when an import library is not being created. If no exports are specified, LINK does not create an import library. If an export (.EXP) file is used in the build, LINK assumes an import library already exists and it does not create one.


The /INCLUDE Option
/INCLUDE

Forces a reference to a symbol, causing the defining object to be linked into the image.

Syntax

/INCLUDE:symbol

Category

Input: Include Symbols

This option tells LINK to add the specified symbol to the symbol table. LINK then resolves symbol by adding the object that contains the symbol definition to the image file. This is useful for including a library object that otherwise would not have been linked to the program.

An /INCLUDE:symbol specification overrides the removal of that symbol by /OPT:REF.


The /MAP Option
/MAP

Creates a mapfile that describes the image.

Syntax

/MAP[:filename]

Category

Debug: Generate Mapfile
Debug: Mapfile Name

This option tells LINK to generate a mapfile, which is a text file that contains information about the image file. The mapfile can be read by tools such as MAPSYM (not provided in this product).

When /MAP is specified, LINK names the mapfile with the base name of the image file and the extension .MAP. To override the default name, specify a colon (:) followed by filename.

A mapfile contains the following information:

•	The module name, which is the base name of the file

•	The timestamp from the image file header (not from the file system)

•	A list of groups in the image, with each group's start address (as section:offset), length, group name, and class

•	A list of public symbols, with each address (as section:offset), symbol name, flat address, and object file where the symbol is defined

•	The entry point (as section:offset)

•	A list of fixups


The /NODEFAULTLIB Option
/NODEFAULTLIB

Removes one or more libraries from the library search list.

Syntax

/NODEFAULTLIB[:library[,library...]]

Category

Input: Ignore All Default Libraries
Input: Ignore Specific Libraries

This option tells LINK to remove some or all default libraries from the list of libraries it searches when resolving externals. LINK resolves references to external definitions by searching first in libraries specified on the command line, then in default libraries specified with the /DEFAULTLIB option, then in default libraries named in object files.

To suppress the search in all default libraries, specify /NODEFAULTLIB with no arguments. To suppress the search in a specific library, specify a colon (:) and the library name. You can specify multiple libraries by typing a comma (,) between the library names.

If the /NODEFAULTLIB option is specified with no filename or with the same library as given with the /DEFAULTLIB option, LINK does not search the library specified with /DEFAULTLIB.


The /NOLOGO Option
/NOLOGO

Suppresses display of the LINK copyright message and version number.

Syntax

/NOLOGO

Category

Miscellaneous: Suppress Display of Sign-On Banner

This option tells LINK not to display the copyright message and version number that it sends to standard output. This option also prevents echoing of command files.


The /OPT Option
/OPT

Provides control over LINK optimizations.

Syntax

/OPT:{REF|NOREF}

Category

Miscellaneous: Other Options

This option controls the kind of optimizations that LINK performs during a build. Optimizations generally decrease the image size and increase the program speed, at a cost of increased link time.

By default, LINK removes unreferenced packaged functions (COMDATs). An object contains packaged functions if it has been compiled with the /Gy option. This optimization is called transitive COMDAT elimination. To override this default and keep unused packaged functions in the program, specify /OPT:NOREF. You can use the /INCLUDE option to override the removal of a specific symbol.

If the /DEBUG option is specified, the default for /OPT changes from REF to NOREF and all functions are preserved in the image. To override this default and optimize a debugging build, specify /OPT:REF.


The /ORDER Option
/ORDER

Sets an order in which specified functions are to be linked.

Syntax

/ORDER:@filename

Category

Miscellaneous: Other Options

This option lets you perform optimization by telling LINK to place certain packaged functions into the image in a predetermined order. LINK places the functions in the specified order within each section in the image.

Specify the order in filename, which is a text file that lists the packaged functions in the order you want to link them. Each line in filename contains the name of one packaged function. An object contains packaged functions if it has been compiled with the /Gy option. Function names are case sensitive. A comment is specified by a semicolon (;) and can be on the same or a separate line. LINK ignores all text from the semicolon to the end of the line.

LINK uses decorated forms of identifiers. CL decorates an identifier when it creates the object file. If the name of the packaged function is specified to the linker in its undecorated form as it appears in the source code, LINK attempts to match the name. If it cannot find a unique match, LINK issues an error. Use the DUMPBIN tool to get the decorated form of an identifier when you need to specify it to the linker.

If more than one /ORDER specification is used, the last one specified takes effect.

Ordering allows you to optimize your program's paging behavior through swap tuning. Group a function with the functions it calls. You can also group frequently called functions together. These techniques increase the probability that a called function is in memory when it is needed and will not have to be paged from disk.


The /OUT Option
/OUT

Names the executable file or DLL.

Syntax

/OUT:filename

Category

Output: Name of Output File

This option overrides the default name and location of the image file that LINK creates. By default, LINK forms the filename using the base name of the first file specified and the appropriate extension (.EXE or .DLL).

The /OUT option controls the default base name for a mapfile or import library. For details, see the descriptions of /MAP and /IMPLIB.


The /SECTION Option
/SECTION

Sets attributes for a section in the image file.

Syntax

/SECTION:name,attributes

Category

Miscellaneous: Other Options

This option changes the attributes of a section, overriding the attributes set when the object file for the section was compiled.

Specify a colon (:) and a section name. The name is case sensitive.

Specify one or more attributes for the section. The attribute characters are E, R, W, and S and are not case sensitive. You must specify all attributes that you want the section to have; an omitted attribute character causes that attribute bit to be turned off. Attribute characters have the following meanings:

Character	Attribute	Meaning
E	execute	Allows code to be executed
R	read	Allows read operations on data
W	write	Allows write operations on data
S	shared	Shares the section among all processes that load the image
Note that Win32s operating systems load all DLL data sections as "shared" even if that attribute is not set.

A section that does not have E, R, or W set is probably invalid.


The /STACK Option
/STACK

Sets the stack size.

Syntax

/STACK:reserve[,commit]

Category

Image Attributes: Stack Allocations

This option sets the size of the stack in bytes and takes arguments in decimal or C-language notation.

The reserve specifies the total stack allocation in virtual memory. The default stack size is 1MB. LINK rounds up the specified value to the nearest 4 bytes.

The optional commit argument is subject to interpretation by the operating system. In Windows NT, commit specifies the amount of physical memory to allocate at a time. Committed virtual memory causes space to be reserved in the paging file. A higher commit value saves time when the application needs more stack space but increases the memory requirements and possibly startup time.

An alternate way to set the stack is with the STACKSIZE statement in a .DEF file. STACKSIZE overrides /STACK if both are specified. You can change the stack after the executable file is built by using the EDITBIN tool.


The /STUB Option
/STUB

Inserts an MS-DOS application at the start of the image.

Syntax

/STUB:filename

Category

Output: MS-DOS Stub Filename

This option attaches an MS-DOS stub program to a Win32 image file. A stub program is invoked if the file is executed in MS-DOS. Usually, it displays an appropriate message; however, any valid MS-DOS application can be a stub program.

Specify a colon (:) and the filename for the stub program. LINK checks filename to be sure that it is a valid MS-DOS executable file and issues an error if the file is not valid.

If /STUB is not used, LINK attaches a default stub program that generates the following message:

This program cannot be run in MS-DOS mode.


The /SUBSYSTEM Option
/SUBSYSTEM

Specifies the subsystem required to run the program.

Syntax

/SUBSYSTEM:{CONSOLE|WINDOWS}[,major[.minor]]

Category

Miscellaneous: Other Options (not recommended)

This option tells the operating system how to run the executable file. The subsystem is set as follows:

•	The CONSOLE subsystem is for a character-mode application that runs with Windows NT. Console applications are given a console by the operating system. If main is defined, CONSOLE is the default.

•	The WINDOWS subsystem applies to an application that does not require a console, probably because it creates its own windows for interaction with the user. Win32s operating systems can run only WINDOWS applications. If WinMain is defined, WINDOWS is the default.

The optional major and minor version numbers specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 − 65535. The default is version 3.10.

The choice of subsystem affects the default starting address for the program. For more information, see the description of the /ENTRY option.


The /VERBOSE Option
/VERBOSE

Displays information on the link session.

Syntax

/VERBOSE

Category

Miscellaneous: Verbose

This option tells LINK to display details about the build process to standard output. The output can be redirected to a file.

The displayed information includes the library search process and lists each library and object name (with full path), the symbol being resolved from the library, and the list of objects that reference the symbol.


The /VERSION Option
/VERSION

Writes a user-specified version number in the image header.

Syntax

/VERSION:major[.minor]

Category

Miscellaneous: Version Information

This option tells LINK to put a version number in the header of the executable file or DLL. The major and minor arguments are decimal numbers in the range 0 − 65535. The default is version 0.0.

An alternate way to insert a version number is with the VERSION module-definition statement.


The /WARN Option
/WARN

Controls the display of warnings by the linker.

Syntax

/WARN[:level]

Category

Miscellaneous: Other Options

This option lets you determine the output of LINK warnings. Specify the level as one of the following:

level	Meaning
0	Suppress all warnings.
1	Default if /WARN:level is not used; displays most warnings. Overrides a /WARN:level specified earlier on the LINK command line or in the LINK environnment variable
2	Default if /WARN is specified without level; displays additional warnings.


The NAME Statement
NAME

Specifies the filename for an executable file.

Syntax

NAME [application][BASE=address]

This statement specifies a name for the main output file. An equivalent way to specify an output filename is with the /OUT option, and an equivalent way to set the base address is with the /BASE option. If both are specified, /OUT overrides NAME. See the descriptions of /OUT and /BASE for details about output filenames and base addresses.


The LIBRARY Statement
LIBRARY

Builds a DLL and sets the base address

Syntax

LIBRARY [library][BASE=address]

This statement tells LINK to create a DLL. At the same time LINK also creates an import library, unless an .EXP file is used in the build.

The library argument specifies the DLL filename. If both the /OUT option and the LIBRARY statement are specified, /OUT overrides LIBRARY.

An equivalent way to specify a DLL build is with the /DLL option, and an equivalent way to set the base address is with the /BASE option. See the descriptions of /DLL, /BASE, and /OUT for details about filenames, DLLs, import libraries, .EXP files, and base addresses.


The DESCRIPTION Statement
DESCRIPTION

Inserts user-specified text in the image.

Syntax

DESCRIPTION "text"

This statement writes a string into the data section with a "read" attribute. Enclose the specified text in single or double quotation marks (' or "). To use a literal quotation mark (either single or double) in the string, enclose the string with the other type of mark.

This feature differs from the comment specified with the /COMMENT option.


The STACKSIZE Statement
STACKSIZE

Sets the stack size.

Syntax

STACKSIZE reserve[,commit]

This statement sets the size of the stack in bytes. An equivalent way to set the stack is with the /STACK option. See the /STACK description for details about the reserve and commit arguments.


The CODE Statement
CODE

Defines attributes for code sections.

Syntax

CODE attributes

This statement sets the default attributes for all code sections in the image file. You can override the defaults for specific sections by using individual /SECTION specifications or SECTIONS statements.

The attributes are one or more of the following: EXECUTE, READ, SHARED, and WRITE. The default attributes for code sections are EXECUTE and READ.


The DATA Statement
DATA

Defines attributes for data sections.

Syntax

DATA attributes

This statement sets the default attributes for all data sections in the image file. You can override the defaults for specific sections by using individual /SECTION specifications or SECTIONS statements.

The attributes are one or more of the following: EXECUTE, READ, SHARED, and WRITE. The default attributes for data sections are READ and WRITE. Data sections in DLLs for Win32s and Windows NT must be SHARED.


The SECTIONS Statement
SECTIONS

Defines attributes for specific sections.

Syntax

SECTIONS definitions

This statement sets attributes for one or more sections in the image file. It can be used to override the default attributes for each type of section.

SECTIONS marks the beginning of a list of section definitions. Each definition must be on a separate line. The SECTIONS keyword can be on the same line as the first definition or on a preceding line. The .DEF file can contain one or more SECTIONS statements. The SEGMENTS keyword is supported as a synonym for SECTIONS.

The syntax for a section definition is:

section [CLASS 'classname'] attributes

The section name is case sensitive. The CLASS keyword is supported for compatibility but is ignored. The attributes are one or more of the following: EXECUTE, READ, SHARED, and WRITE.

An equivalent way to specify section attributes is with the /SECTION option.


The EXPORTS Statement
EXPORTS

Specifies definitions to be exported.

Syntax

EXPORTS definitions

This statement makes one or more definitions available as exports to other programs.

EXPORTS marks the beginning of a list of export definitions. Each definition must be on a separate line. The EXPORTS keyword can be on the same line as the first definition or on a preceding line. The .DEF file can contain one or more EXPORTS statements.

The syntax for an export definition is:

entryname[=internalname] [@ordinal[ NONAME]] [DATA]

The entryname, internalname, ordinal, NONAME, and DATA arguments are discussed in the description of the /EXPORT option. The CONSTANT keyword is supported for compatibility but is not recommended.

There are three methods for exporting a definition, listed in recommended order of use:

•	The __declspec(dllexport) keyword in the source code

•	An /EXPORT specification in a LINK command

•	An EXPORTS statement in a .DEF file

All three methods can be used in the same program. When LINK builds a program that contains exports, it also creates an import library, unless an .EXP file is used in the build.


The VERSION Statement
VERSION

Writes a user-specified version number in the image header.

Syntax

VERSION major[.minor]

This statement tells LINK to put a number in the header of the executable file or DLL. The major and minor arguments are decimal numbers in the range 0 − 65535. The default is version 0.0.

An equivalent way to specify a version number is with the /VERSION option.


ACCELERATORS Resource

acctablename ACCELERATORS
[[optional-statements]]
BEGIN
    event, idvalue, [[type]] [[options]]
    . . .
END

The ACCELERATORS statement defines one or more accelerators for an application. An accelerator is a keystroke defined by the application to give the user a quick way to perform a task. The TranslateAccelerator function is used to translate accelerator messages from the application queue into WM_COMMAND or WM_SYSCOMMAND messages.

Parameters

acctablename

Specifies either a unique name or a 16-bit unsigned integer value that identifies the resource.

optional-statements

Zero or more of the following statements:

Statement	Decription
CHARACTERISTICS dword	User-defined information about a resource that can be used by tools that read and write resource files.
LANGUAGE language, sublanguage	Specifies the language for the resource. The parameters are constants from WINNLS.H.
VERSION dword	User-defined version number for the resource that can be used by tools that read and write resource files.
event

Specifies the keystroke to be used as an accelerator. It can be any one of the following character types:

char

A single character enclosed in double quotation marks. The character can be preceded by a caret (^), meaning that the character is a control character.

Character

An integer value representing a character. The type parameter must be ASCII.

Virtual-key character

An integer value representing a virtual key. The virtual key for alphanumeric keys can be specified by placing the uppercase letter or number in double quotation marks (for example, 9 or C). The type parameter must be VIRTKEY.

idvalue

Specifies a 16-bit unsigned integer value that identifies the accelerator.

type

Required only when the event parameter is a character or a virtual-key character. The type parameter specifies either ASCII or VIRTKEY; the integer value of event is interpreted accordingly. When VIRTKEY is specified and event contains a string, event must be uppercase.

options

Specifies the options that define the accelerator. This parameter can be one or more of the following values:

NOINVERT

Specifies that no top-level menu item is highlighted when the accelerator is used. This is useful when defining accelerators for actions such as scrolling that do not correspond to a menu item. If NOINVERT is omitted, a top-level menu item will be highlighted (if possible) when the accelerator is used.

ALT

Causes the accelerator to be activated only if the ALT key is down.

SHIFT

Causes the accelerator to be activated only if the SHIFT key is down.

CONTROL

Defines the character as a control character (the accelerator is only activated if the CONTROL key is down). This has the same effect as using a caret (^) before the accelerator character in the event parameter.

The ALT, SHIFT, and CONTROL options apply only to virtual keys.

Example

The following example demonstrates the use of accelerator keys:

1 ACCELERATORS
BEGIN
  "^C",  IDDCLEAR         ; control C
  "K",   IDDCLEAR         ; shift K
  "k",   IDDELLIPSE, ALT  ; alt k
  98,    IDDRECT, ASCII   ; b
  66,    IDDSTAR, ASCII   ; B (shift b)
  "g",   IDDRECT          ; g
  "G",   IDDSTAR          ; G (shift G)
  VK_F1, IDDCLEAR, VIRTKEY                ; F1
  VK_F1, IDDSTAR, CONTROL, VIRTKEY        ; control F1
  VK_F1, IDDELLIPSE, SHIFT, VIRTKEY       ; shift F1
  VK_F1, IDDRECT, ALT, VIRTKEY            ; alt F1
  VK_F2, IDDCLEAR, ALT, SHIFT, VIRTKEY    ; alt shift F2
  VK_F2, IDDSTAR, CONTROL, SHIFT, VIRTKEY ; ctrl shift F2
  VK_F2, IDDRECT, ALT, CONTROL, VIRTKEY   ; alt control F2
END

See Also

TranslateAccelerator
Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


AUTO3STATE Control

AUTO3STATE text, id, x, y, width, height [[, style [[, extended-style]]]]

The AUTO3STATE statement creates an automatic 3-state check box. The control is an open box with the given text positioned to the right of the box. When chosen, the box automatically advances between three states: checked, unchecked, and disabled (grayed). The control sends a message to its parent whenever the user chooses the control.

Parameters

style

Specifies styles for the control, which can be a combination of the BS_AUTO3STATE style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

The default style for this control is BS_AUTO3STATE and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

See Also

AUTOCHECKBOX, CHECKBOX, CONTROL, STATE3


AUTOCHECKBOX Control

AUTOCHECKBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The AUTOCHECKBOX statement creates an automatic check box control. The control is a small rectangle (check box) that has the specified text displayed next to it (typically, to the right). When the user chooses the control, the control highlights the rectangle and sends a message to its parent window. The AUTOCHECKBOX statement, which can only be used in the body of a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Parameters

style

Specifies the styles of the control. This value can be a combination of the button class style BS_AUTOCHECKBOX and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_AUTOCHECKBOX and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

See Also

AUTO3STATE, CHECKBOX, CONTROL, STATE3


AUTORADIOBUTTON Control

AUTORADIOBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

The AUTORADIOBUTTON control statement specifies an automatic radio button control. This control automatically performs mutual exclusion with the other AUTORADIOBUTTON controls in the same group. When the button is chosen, the application is notified with BN_CLICKED

Parameters

text

The specified text appears next to the radio button.

style

Specifies styles for the automatic radio button, which can be a combination of BUTTON-class styles and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

The default style for AUTORADIOBUTTON is BS_AUTORADIOBUTTON and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

See Also

CONTROL, RADIOBUTTON


BITMAP Resource

nameID BITMAP [[load-mem]] filename

The BITMAP resource-definition statement specifies a bitmap that an application uses in its screen display or as an item in a menu or control.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

filename

Specifies the name of the file that contains the resource. The name must be a valid filename; it must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

Example

The following example specifies two bitmap resources:

disk1   BITMAP disk.bmp
12      BITMAP PRELOAD diskette.bmp

See Also

LoadBitmap


CAPTION Statement

CAPTION captiontext

The CAPTION statement defines the title for a dialog box. The title appears in the box's caption bar (if it has one).

The default caption is empty.

Parameter

captiontext

Specifies a character string enclosed in double quotation marks.

Example

The following example demonstrates the use of the CAPTION statement:

CAPTION "Error!"


CHARACTERISTICS Statement

CHARACTERISTICS dword

The CHARACTERISTICS statement allows the developer to specify information about a resource that can be used by tools that read and write resource-definition files. The specified dword value appears with the resource in the compiled .RES file. However, the value is not stored in the executable file and has no significance to Windows.

The CHARACTERISTICS statement appears before the BEGIN in an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition. The specified value applies only to that resource.

Parameter

dword

A user-defined doubleword value.

See Also

Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


CHECKBOX Control

CHECKBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The CHECKBOX statement creates a check box control. The control is a small rectangle (check box) that has the specified text displayed next to it (typically, to the right). When the user selects the control, the control highlights the rectangle and sends a message to its parent window. The CHECKBOX statement, which can only be used in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Parameters

text

Specifies text that is displayed to the right of the control.

style

Specifies the control styles. This value can be a combination of the button class style BS_CHECKBOX and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_CHECKBOX and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a check-box control that is labeled Italic:

CHECKBOX "Italic", 3, 10, 10, 40, 10

See Also

AUTOCHECKBOX, AUTO3STATE, STATE3, GetDialogBaseUnits


CLASS Statement

CLASS class

The CLASS statement defines the class of the dialog box. The CLASS statement appears in the optional section before a DIALOG statements BEGIN keyword. If no class is given, the Windows standard dialog class is used.

Parameters

class

Specifies a 16-bit unsigned integer or a string, enclosed in double quotation marks, that identifies the class of the dialog box. If the window procedure for the class does not process a message sent to it, it must call the DefDlgProc function to ensure that all messages are handled properly for the dialog box. A private class can use DefDlgProc as the default window procedure. The class must be registered with the cbWndExtra member of the WNDCLASS structure set to DLGWINDOWEXTRA.

Comments

The CLASS statement should only be used with special cases, since it overrides the normal processing of a dialog box. The CLASS statement converts a dialog box to a window of the specified class; depending on the class, this could give undesirable results. Do not use the redefined control-class names with this statement.

Example

The following example demonstrates the use of the CLASS statement:

CLASS "myclass"

See Also

DIALOG, DefDlgProc


COMBOBOX Control

COMBOBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The COMBOBOX statement creates a combination box control (a combo box). A combo box consists of either a static text box or an edit box combined with a list box. The list box can be displayed at all times or pulled down by the user. If the combo box contains a static text box, the text box always displays the selection (if any) in the list box portion of the combo box. If it uses an edit box, the user can type in the desired selection; the list box highlights the first item (if any) that matches what the user has entered in the edit box. The user can then select the item highlighted in the list box to complete the choice. In addition, the combo box can be owner-drawn and of fixed or variable height.

Parameters

style

Specifies the control styles. This value can be a combination of the COMBOBOX class styles and any of the following styles: WS_TABSTOP, WS_GROUP, WS_VSCROLL, and WS_DISABLED.

If you do not specify a style, the default style is CBS_SIMPLE and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a combo-box control with a vertical scroll bar:

COMBOBOX 777, 10, 10, 50, 54, CBS_SIMPLE | WS_VSCROLL | WS_TABSTOP


CONTROL: General Control

CONTROL text, id, class, style, x, y, width, height [[, extended-style]]

This statement defines a user-defined control window.

Parameters

class

Specifies a redefined name, character string, a 16-bit unsigned integer value that defines the class. This can be any one of the control classes; for a list of the control classes, see the first list following this description. If the value is a redefined name supplied by the application, it must be a string enclosed in double quotation marks.

style

Specifies a redefined name or integer value that specifies the style of the given control. The exact meaning of style depends on the class value. the sections following this description show the control classes and corresponding styles.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

The six possible control classes are described in the following sections.

The Button Control Class

A button control is a small rectangular child window that represents a button that the user can turn on or off by clicking it with the mouse. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.

A button can have only one of the following styles, with the exception of BS_LEFTTEXTBS, which can be combined with check boxes and radio buttons.

BS_3STATE

Creates a button that is the same as a check box, except that the box can be grayed (dimmed) as well as checked. The grayed state is used to show that the state of the check box is not determined.

BS_AUTO3STATE

Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and normal.

BS_AUTOCHECKBOX

Creates a button that is the same as a check box, except that an X appears in the check box when the user selects the box; the X disappears (is cleared) the next time the user selects the box.

BS_AUTORADIOBUTTON

Creates a button that is the same as a radio button, except that when the user selects it, the button automatically highlights itself and clears (removes the selection from) any other buttons in the same group.

BS_CHECKBOX

Creates a small square that has text displayed to its right (unless this style is combined with the BS_LEFTTEXT style).

BS_DEFPUSHBUTTON

Creates a button that has a heavy black border. The user can select this button by pressing the ENTER key. This style is useful for enabling the user to quickly select the most likely option (the default option).

BS_GROUPBOX

Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle's upper-left corner.

BS_LEFTTEXT

Places text on the left side of the radio button or check box when combined with a radio button or check box style.

BS_OWNERDRAW

Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created, and it receives a WM_DRAWITEM message when a visual aspect of the button has changed. The BS_OWNERDRAW style cannot be combined with any other button styles.

BS_PUSHBUTTON

Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.

BS_RADIOBUTTON

Creates a small circle that has text displayed to its right (unless this style is combined with the BS_LEFTTEXT style). Radio buttons are usually used in groups of related but mutually exclusive choices.

The Combobox Control Class

Combo-box controls consist of a selection field similar to an edit control plus a list box. The list box may be displayed at all times or may be dropped down when the user selects a pop box next to the selection field.

Depending on the style of the combo box, the user can or cannot edit the contents of the selection field. If the list box is visible, typing characters into the selection box will cause the first list-box entry that matches the characters typed to be highlighted. Conversely, selecting an item in the list box displays the selected text in the selection field. Combo-box control styles are described below.

CBS_SIMPLE

Displays the list box at all times. The current selection in the list box is displayed in the edit control.

CBS_DROPDOWN

Similar to CBS_SIMPLE except that the list box is not displayed unless the user selects an icon next to the selection field.

CBS_DROPDOWNLIST

Similar to CBS_DROPDOWN except that the edit control is replaced by a static text item which displays the current selection in the list box.

CBS_OWNERDRAWFIXED

Specifies a fixed-height owner-draw combo box. The owner of the list box is responsible for drawing its contents; the items in the list box are all the same height.

CBS_OWNERDRAWVARIABLE

Specifies a variable-height owner-draw combo box. The owner of the list box is responsible for drawing its contents; the items in the list box can have different heights.

CBS_AUTOHSCROLL

Scrolls the text in the edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed.

CBS_SORT

Sorts strings entered into the list box.

CBS_HASSTRINGS

Specifies an owner-draw combo box that contains items consisting of strings. The combo box maintains the memory and pointers for the strings so that the application can use the LB_GETTEXT message to retrieve the text for a particular item.

CBS_OEMCONVERT

Converts text entered in the combo box edit control from the ANSI character set to the OEM character set and then back to ANSI. This ensures proper character conversion when the application calls the CharToOem function to convert an ANSI string in the combo box to OEM characters. This style is most useful for combo boxes that contain filenames and applies only to combo boxes created with the CBS_SIMPLE or CBS_DROPDOWN styles.

The Edit Control Class

An edit control is a rectangular child window in which the user can enter text from the keyboard. The user selects the control, and gives it the input focus, by clicking the mouse inside it or pressing the TAB key. The user can enter text when the control displays a flashing insertion point. The mouse can be used to move the cursor and select characters to be replaced, or to position the cursor for inserting characters. The BACKSPACE key can be used to delete characters.

Edit controls use the fixed-pitch font and display Unicode characters. They expand tab characters into as many space characters as are required to move the cursor to the next tab stop. Tab stops are assumed to be at every eighth character position. Edit control styles are described below.

ES_LEFT

Justifies the text to the left.

ES_CENTER

Centers the text. This style is valid in multiline edit controls only.

ES_RIGHT

Justifies the text to the right. This style is valid in multiline edit controls only.

ES_LOWERCASE

Converts all characters to lowercase as they are typed into the edit control.

ES_UPPERCASE

Converts all characters to uppercase as they are typed into the edit control.

ES_PASSWORD

Displays all characters as an asterisk (*) as they are typed into the edit control. An application can use the EM_SETPASSWORDCHAR message to change the character that is displayed.

ES_MULTILINE

Multiple-line edit control. (The default is single-line.) Shows as many lines of text as possible. The following four styles specify options for horizontal and vertical scrolling.

ES_AUTOVSCROLL specified

Shows as many lines as possible and scrolls vertically when the user presses the ENTER key. (This is actually the carriage-return character, which the edit control expands to a carriage-return/line-feed combination.)

ES_AUTOVSCROLL not specified

Shows as many lines as possible and beeps if the user presses ENTER when no more lines can be displayed.

ES_AUTOHSCROLL specified

Scrolls horizontally when the insertion point goes past the right edge of the control. To start a new line, press the ENTER key.

ES_AUTOHSCROLL not specified

Wraps words to the beginning of the next line when necessary. A new line is also started if the user presses ENTER. If the window size changes, the word wrap position changes, and the text is redisplayed.

Multiple-line edit controls can have scroll bars. An edit control with scroll bars processes its own scroll-bar messages. Edit controls without scroll bars scroll as described above, and process any scroll messages sent by the parent window.

ES_AUTOVSCROLL

Scrolls text automatically up one page when the user presses the ENTER key on the last line.

ES_AUTOHSCROLL

Scrolls text automatically to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position 0.

ES_NOHIDESEL

Overrides the default action, in which an edit control hides the selection when the control loses the input focus. Inverts the selection instead.

ES_OEMCONVERT

Converts text entered in the edit control from the ANSI character set to the OEM character set and then back to ANSI. This ensures proper character conversion when the application calls the CharToOem function to convert an ANSI string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.

The Listbox Control Class

Listbox controls consist of a list of character strings. The control is used whenever an application needs to present a list of names, such as filenames, that the user can view and select. The user can select a string by pointing to the string with the mouse and clicking a mouse button. When a string is selected, it is highlighted and a notification message is passed to the parent window. A scroll bar can be used with a listbox control to scroll lists that are too long or too wide for the control window. Listbox control styles are described below.

LBS_STANDARD

Strings in the list box are sorted alphabetically and the parent window receives an input message whenever the user clicks or double-clicks a string. The list box contains borders on all sides.

LBS_DISABLENOSCROLL

Shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If this style is not specified, the scroll bar is hidden when the list box does not contain enough items.

LBS_EXTENDEDSEL

The user can select multiple items using the mouse with the SHIFT and/or the CONTROL key or special key combinations.

LBS_HASSTRINGS

An owner-draw list box contains items consisting of strings. The list box maintains the memory and pointers for the strings so the application can use the LB_GETTEXT message to retrieve the text for a particular item.

LBS_NOTIFY

The parent receives an input message whenever the user clicks or double-clicks a string.

LBS_MULTIPLESEL

The string selection is toggled each time the user clicks or double-clicks the string. Any number of strings can be selected.

LBS_MULTICOLUMN

The list box contains multiple columns. The list box can be scrolled horizontally. The LB_SETCOLUMNWIDTH message sets the width of the columns.

LBS_NOINTEGRALHEIGHT

The size of the list box is exactly the size specified by the application when it created the list box. Normally, Windows sizes a list box so that the list box does not display partial items.

LBS_SORT

The strings in the list box are sorted alphabetically.

LBS_NOREDRAW

The list-box display is not updated when changes are made. This style can be changed at any time by sending a WM_SETREDRAW message.

LBS_OWNERDRAWFIXED

The owner of the list box is responsible for drawing its contents; the items in the list box are all the same height.

LBS_OWNERDRAWVARIABLE

The owner of the list box is responsible for drawing its contents; the items in the list box are variable in height.

LBS_USETABSTOPS

The list box is able to recognize and expand tab characters when drawing its strings. The default tab positions are set at every 32 dialog units. (A dialog unit is a horizontal or vertical distance. One horizontal dialog unit is equal to 1/4 of the current dialog base width unit. The dialog base units are computed from the height and width of the current system font. The GetDialogBaseUnits function returns the size of the dialog base units in pixels.)

LBS_WANTKEYBOARDINPUT

The owner of the list box receives WM_VKEYTOITEM or WM_CHARTOITEM  messages whenever the user presses a key when the list box has input focus. This allows an application to perform  special processing on the keyboard input.

The Scrollbar Control Class

A scroll-bar control is a rectangle that contains a scroll  thumb and has direction arrows at both ends. The scroll bar sends  a notification message to its parent whenever the user clicks the  mouse in the control. The parent is responsible for updating the thumb  position, if necessary. Scroll-bar controls have the same appearance  and function as the scroll bars used in ordinary windows. But unlike  scroll bars, scroll-bar controls can be positioned anywhere within  a window and used whenever needed to provide scrolling input for a  window. Scroll bar control styles are described below.

SBS_VERT

Vertical scroll bar. If neither SBS_RIGHTALIGN nor SBS_LEFTALIGN  is specified, the scroll bar has the height, width, and position given  in the CreateWindow function.

SBS_RIGHTALIGN

Used with SBS_VERT. The right edge of the scroll bar is aligned  with the right edge of the rectangle specified by the x, y,  width, and height values given in the CreateWindow function. The scroll bar has the default width for system scroll bars.

SBS_LEFTALIGN

Used with SBS_VERT. The left edge of the scroll bar is aligned  with the left edge of the rectangle specified by the x, y,  width, and height values given in the CreateWindow function. The scroll bar has the default width for system scroll bars.

SBS_HORZ

Horizontal scroll bar. If neither SBS_BOTTOMALIGN nor SBS_TOPALIGN  is specified, the scroll bar has the height, width, and position given  in the CreateWindow function.

SBS_TOPALIGN

Used with SBS_HORZ. The top edge of the scroll bar is aligned  with the top edge of the rectangle specified by the x, y,  width, and height values given in the CreateWindow  function. The scroll bar has the default height for system scroll  bars.

SBS_BOTTOMALIGN

Used with SBS_HORZ. The bottom edge of the scroll bar is aligned  with the bottom edge of the rectangle specified by the x, y,  width, and height values given in the CreateWindow function. The scroll bar has the default height for system scroll  bars.

SBS_SIZEBOX

Size box. If neither SBS_SIZEBOXBOTTOMRIGHTALIGN nor SBS_SIZEBOXTOPLEFTALIGN  is specified, the size box has the height, width, and position given  in the CreateWindow function.

SBS_SIZEBOXTOPLEFTALIGN

Used with SBS_SIZEBOX. The top-left corner of the size box  is aligned with the top-left corner of the rectangle specified by  the x, y,  width, and height values given  in the CreateWindow function. The size box has the default size  for system size boxes.

SBS_SIZEBOXBOTTOMRIGHTALIGN

Used with SBS_SIZEBOX. The bottom-right corner of the size  box is aligned with the bottom-right corner of the rectangle specified  by the x, y, width, and height values  given in the CreateWindow function. The size box has the default  size for system size boxes.

The Static Control Class

Static controls are simple text fields, boxes, and rectangles  that can be used to label, box, or separate other controls. Static  controls take no input and provide no output. Static control styles  are described below.

SS_LEFT

A simple rectangle displaying the given text flush left. The  text is formatted before it is displayed. Words that would extend  past the end of a line are automatically wrapped to the beginning  of the next line.

SS_CENTER

A simple rectangle displaying the given text centered. The  text is formatted before it is displayed. Words that would extend  past the end of a line are automatically wrapped to the beginning  of the next line.

SS_RIGHT

A simple rectangle displaying the given text flush right.  The text is formatted before it is displayed. Words that would extend  past the end of a line are automatically wrapped to the beginning  of the next line.

SS_LEFTNOWORDWRAP

A simple rectangle displaying the given text flush left. Tabs  are expanded, but words are not wrapped. Text that extends past the  end of a line is clipped.

SS_SIMPLE

A simple rectangle with a single line of text flush left.  The line of text cannot be shortened or altered in any way. (The control's  parent window or dialog box must not process the WM_CTLCOLOR message.)

SS_NOPREFIX

Removes any (&) characters and underlines the next character  in the string. Unless this style is specified, Windows will interpret  any (&) characters in the control's text to be accelerator prefix  characters. If a static control is to contain text where this feature  is not wanted, SS_NOPREFIX may be added. This STATIC-control style  may be included with any of the defined STATIC controls.

You can combine SS_NOPREFIX with other styles by using the  bitwise OR operator. This is most often used when filenames  or other strings that may contain an (&) need to be displayed in a  static control in a dialog box.

SS_ICON

An icon displayed in the dialog box. The given text is the  name of an icon (not a filename) defined elsewhere in the resource  file. For the ICON statement, the width and height  parameters in the CreateWindow function are ignored; the  icon automatically sizes itself.

SS_BLACKRECT

A rectangle filled with the color used to draw window frames.  This color is black in the default Windows color scheme.

SS_GRAYRECT

A rectangle filled with the color used to fill the screen  background. This color is gray in the default Windows color scheme.

SS_WHITERECT

A rectangle filled with the color used to fill window backgrounds.  This color is white in the default Windows color scheme.

SS_BLACKFRAME

Box with a frame drawn with the same color as window frames.  This color is black in the default Windows color scheme.

SS_GRAYFRAME

Box with a frame drawn with the same color as the screen background  (desktop). This color is gray in the default Windows color scheme.

SS_WHITEFRAME

Box with a frame drawn with the same color as window backgrounds.  This color is white in the default Windows color scheme.

SS_USERITEM

User-defined item.


CTEXT Control

CTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

The CTEXT statement creates a centered-text control. The control is a simple rectangle displaying the given text centered in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The CTEXT statement, which you can use only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Parameters

text

Specifies text that is centered in the rectangular area of the control.

style

Specifies the control styles. This value can be any combination of the following styles: SS_CENTER, WS_TABSTOP, and WS_GROUP.

If you do not specify a style, the default style is SS_CENTER and WS_GROUP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a centered-text control that is labeled filename:

CTEXT "filename", 101, 10, 10, 100, 100

See Also

CONTROL, DIALOG, LTEXT, RTEXT


CURSOR Resource

nameID CURSOR [[load-mem]] filename

The CURSOR statement specifies a bitmap that defines the shape of the cursor on the display screen.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer identifying the resource.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

filename

Specifies the name of the file that contains the resource. The name must be a valid filename; it must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

Comments

Icon and cursor resources can contain more than one image. If the resource is marked with the PRELOAD option, Windows loads all images in the resource when the application executes.

Example

The following example specifies two cursor resources; one by name (cursor1) and the other by number (2):

cursor1 CURSOR bullseye.cur
2       CURSOR "d:\\cursor\\arrow.cur"


DEFPUSHBUTTON Control

DEFPUSHBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

The DEFPUSHBUTTON statement creates a default push-button control. The control is a small rectangle with a bold outline that represents the default response for the user. The given text is displayed inside the button. The control highlights the button in the usual way when the user clicks the mouse in it and sends a message to its parent window.

Parameters

text

Specifies text that is centered in the rectangular area of the control.

style

Specifies the control styles. This value can be a combination of the following styles: BS_DEFPUSHBUTTON, WS_TABSTOP, WS_GROUP, and WS_DISABLED.

If you do not specify a style, the default style is BS_DEFPUSHBUTTON and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a default push-button control that is labeled Cancel:

DEFPUSHBUTTON "Cancel", 101, 10, 10, 24, 50

See Also

PUSHBUTTON, RADIOBUTTON


DIALOG Resource

nameID DIALOG [[load-mem]] x, y, width, height
[[optional-statements]]
BEGIN
    control-statement
    . . .
END

The DIALOG statement defines a window that an application can use to create dialog boxes. The statement defines the position and dimensions of the dialog box on the screen as well as the dialog box style.

nameID

Identifies the dialog box. This is either a unique name or a unique 16-bit unsigned integer value in the range 1 to 65,535.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

option-statements

Specifies options for the dialog box. This can be zero or more of the following statements:

CAPTION "text"

Specifies the caption of the dialog box if it has a title bar. See CAPTION for more information.

CHARACTERISTICS dword

Specifies a user-defined double-word value for use by resource tools. This value is not used by Windows. For more information, see CHARACTERISTICS.

CLASS class

Specifies a 16-bit unsigned integer or a string, enclosed in double quotation marks, that identifies the class of the dialog box. See CLASS for more information.

LANGUAGE language,sublanguage

Specifies the language of the dialog box. See LANGUAGE for more information.

STYLE styles

Specifies the styles of the dialog box. See STYLE for more information.

EXSTYLE=extended-styles

Specifies the extended styles of the dialog box. See EXSTYLE for more information.

VERSION dword

Specifies a user-defined doubleword value. This statement is intended for use by additional resource tools and is not used by Windows. For more information, see VERSION.

For more information on the x, y, width, and height parameters, see Common Statement Parameters.

Comments

The GetDialogBaseUnits function returns the dialog base units in pixels. The exact meaning of the coordinates depends on the style defined by the STYLE option statement. For child-style dialog boxes, the coordinates are relative to the origin of the parent window, unless the dialog box has the style DS_ABSALIGN; in that case, the coordinates are relative to the origin of the display screen.

Do not use the WS_CHILD style with a modal dialog box. The DialogBox function always disables the parent/owner of the newly created dialog box. When a parent window is disabled, its child windows are implicitly disabled. Since the parent window of the child-style dialog box is disabled, the child-style dialog box is too.

If a dialog box has the DS_ABSALIGN style, the dialog coordinates for its upper-left corner are relative to the screen origin instead of to the upper-left corner of the parent window. You would typically use this style when you wanted the dialog box to start in a specific part of the display no matter where the parent window may be on the screen.

The name DIALOG can also be used as the class-name parameter to the CreateWindow function to create a window with dialog box attributes.

Example

The following demonstrates the usage of the DIALOG statement:

#include <windows.h>

ErrorDialog DIALOG  10, 10, 300, 110
STYLE WS_POPUP|WS_BORDER
CAPTION "Error!"
BEGIN
    CTEXT "Select One:", 1, 10, 10, 280, 12
    PUSHBUTTON "&Retry", 2, 75, 30, 60, 12
    PUSHBUTTON "&Abort", 3, 75, 50, 60, 12
    PUSHBUTTON "&Ignore", 4, 75, 80, 60, 12
END

See Also

CONTROL, CreateDialog, CreateWindow, DialogBox, GetDialogBaseUnits
Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


EDITTEXT Control

EDITTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

The EDITTEXT statement defines an EDIT control belonging to the EDIT class. It creates a rectangular region in which the user can type and edit text. The control displays a cursor when the user clicks the mouse in it. The user can then use the keyboard to enter text or edit the existing text. Editing keys include the BACKSPACE and DELETE keys. The user can also use the mouse to select characters to be deleted or to select the place to insert new characters.

Parameters

style

Specifies the control styles. This value can be a combination of the edit class styles and the following styles: WS_TABSTOP, WS_GROUP, WS_VSCROLL, WS_HSCROLL, and WS_DISABLED.

If you do not specify a style, the default style is ES_LEFT, WS_BORDER, and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

The following example demonstrates the use of the EDITTEXT statement:

EDITTEXT  3, 10, 10, 100, 10


EXSTYLE Statement

EXSTYLE extended-style

The EXSTYLE command allows you to designate a dialog box with the WS_EX_style styles. In a resource definition, the EXSTYLE statement is placed with the optional statements before the BEGIN keyword. It can also be placed with the load-mem parameters in a DIALOG statement as follows:

name DIALOG  [[load-mem]] EXSTYLE=extended-style  x, y, ...

For controls, extended styles are specified after the style option in any control definition, as follows:

control text, id, x, y, width, height, [[style[[, extended-style]]]]

Parameters

extended-style

The WS_EX_style style for the dialog box or control.

See also

ACCELERATORS, CONTROL, DIALOG, MENU, POPUP, RCDATA, STRINGTABLE, User-Defined Resouce


Font Resource

nameID FONT [[load-mem]] filename

The FONT resource-definition statement specifies a file that contains a font.

For a font resource, nameID must be a number; it cannot be a name.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

filename

Specifies the name of the file that contains the resource. The name must be a valid filename; it must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

Example

The following example specifies a single font resource:

5 FONT  CMROMAN.FNT

See also

FONT Statement


FONT Statement

FONT pointsize, typeface

The FONT statement defines the font with which Windows will draw text in the dialog box. The font must have been previously loaded, either from the WIN.INI file or by calling the LoadResource function.

Parameters

pointsize

Specifies the size, in points, of the font.

typeface

Specifies the name of the typeface. This name must be identical to the name defined in the [fonts] section of WIN.INI. This parameter must be enclosed in double quotes.

Example

The following example demonstrates the use of the FONT statement:

FONT 12, "MS Sans Serif"

See Also

DIALOG, FONT Resource, LoadResource


GROUPBOX Control

GROUPBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The GROUPBOX statement creates a group box control. The control is a rectangle that groups other controls together. The controls are grouped by drawing a border around them and displaying the given text in the upper-left corner. The GROUPBOX statement, which you can use only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of a control window.

When the style contains WS_TABSTOP or the text specifies an accelerator, tabbing or pressing the accelerator key moves the focus to the first control within the group.

Parameters

style

Specifies the control styles. This value can be a combination of the button class style BS_GROUPBOX and the WS_TABSTOP and WS_DISABLED styles.

If you do not specify a style, the default style is BS_GROUPBOX.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a group-box control that is labeled Options:

GROUPBOX "Options", 101, 10, 10, 100, 100

See Also

DIALOG


ICON Resource

nameID ICON [[load-mem]] filename

The ICON resource-definition statement specifies a bitmap that defines the shape of the icon to be used for a given application.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

filename

Specifies the name of the file that contains the resource. The name must be a valid filename; it must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

Comments

Icon and cursor resources can contain more than one image. If the resource is marked as PRELOAD, Windows loads all images in the resource when the application executes.

Example

The following example specifies two icon resources:

desk1   ICON desk.ico
11      ICON DISCARDABLE custom.ico


ICON Control

ICON text, id, x, y, [[width, height, style [[, extended-style]]]]

The ICON statement creates an icon control. This control is an icon displayed in a dialog box. The ICON control statement, which you can use only in a DIALOG statement, defines the icon-resource identifier, icon-control identifier, position, and attributes of a control.

Parameters

text

Specifies the name of an icon (not a filename) defined elsewhere in the resource file.

width

This value is ignored and should be set to zero.

height

This value is ignored and should be set to zero.

style

Specifies the control style. This parameter is optional. The only value that can be specified is the SS_ICON style. This is the default style whether this parameter is specified or not.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates an icon control whose icon identifier is 901 and whose name is myicon:

ICON "myicon" 901, 30, 30

See Also

DIALOG, ICON Resource


LANGUAGE Statement

LANGUAGE language, sublanguage

The LANGUAGE statement sets the language for all resources up to the next LANGUAGE statement or to the end of the file. When the LANGUAGE statement appears before the BEGIN in an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition, the specified language applies only to that resource.

Parameters

language

Language identifier. Must be one of the constants from WINNLS.H

sublanguage

Sublanguage identifier. Must be one of the constants from WINNLS.H

See Also

Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


LISTBOX Control

LISTBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The LISTBOX statement creates commonly used controls for a dialog box or window. The control is a rectangle containing a list of strings (such as filenames) from which the user can select. The LISTBOX statement, which can only be used in a DIALOG or WINDOW statement, defines the identifier, dimensions, and attributes of a control window.

Parameters

style

Specifies the control styles. This value can be a combination of the list-box class styles and any of the following styles: WS_BORDER and WS_VSCROLL.

If you do not specify a style, the default style is LBS_NOTIFY and WS_BORDER.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a list-box control whose identifier is 101:

LISTBOX 101, 10, 10, 100, 100

See Also

COMBOBOX, DIALOG


LTEXT Control

LTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

The LTEXT statement creates a left-aligned text control. The control is a simple rectangle displaying the given text left-aligned in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The LTEXT statement, which can be used only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Parameters

style

Specifies the control styles. This value can be any combination of the BS_RADIOBUTTON style and the following styles: SS_LEFT, WS_TABSTOP, and WS_GROUP.

If you do not specify a style, the default style is SS_LEFT and WS_GROUP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

This example creates a left-aligned text control that is labeled Filename:

LTEXT "Filename", 101, 10, 10, 100, 100

See Also

CONTROL, DIALOG, CTEXT, RTEXT


MENU Resource

menuID MENU [[load-mem]]
[[optional-statements]]
BEGIN
    item-definitions
    . . .
END

The MENU statement defines the contents of a menu resource. A menu resource is a collection of information that defines the appearance and function of an application menu. A menu is a special input tool that lets a user select commands from a list of command names.

Parameters

menuID

Identifies the menu. This value is either a unique string or a unique 16-bit unsigned integer value in the range of 1 to 65,535.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

optional-statements

Zero or more of the following statements:

Statement	Decription
CHARACTERISTICS dword	User-defined information about a resource that can be used by tools that read and write resource files.
LANGUAGE language, sublanguage	Specifies the language for the resource. The parameters are constants from WINNLS.H.
VERSION dword	User-defined version number for the resource that can be used by tools that read and write resource files.
Example

Following is an example of a complete MENU statement:

sample MENU
BEGIN
     MENUITEM "&Soup", 100
     MENUITEM "S&alad", 101
     POPUP "&Entree"
     BEGIN
          MENUITEM "&Fish", 200
          MENUITEM "&Chicken", 201, CHECKED
          POPUP "&Beef"
          BEGIN
               MENUITEM "&Steak", 301
               MENUITEM "&Prime Rib", 302
          END
     END
     MENUITEM "&Dessert", 103
END

See Also

MENUITEM, POPUP
Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


MENU Statement

MENU menuname

The MENU statement defines the dialog box's menu. If no statement is given, the dialog box has no menu.

Parameter

menuname

Specifies the menu to use. This value is either the name of the menu or the integer identifier of the menu.

Example

The following example demonstrates the use of the MENU dialog statement:

MENU errmenu


MENUITEM Statement

MENUITEM text, result, [[optionlist]]
MENUITEM SEPARATOR

The MENUITEM statement defines a menu item.

Parameters

text

Specifies the name of the menu item.

The string can contain the escape characters \t and \a. The \t character inserts a tab in the string and is used to align text in columns. Tab characters should be used only in pop-up menus, not in menu bars. (For information on pop-up menus, see the POPUP statement.) The \a character aligns all text that follows it flush right to the menu bar or pop-up menu.

result

Specifies the result generated when the user selects the menu item. This parameter takes an integer value. Menu-item results are always integers; when the user clicks the menu-item name, the result is sent to the window that owns the menu.

optionlist

Specifies the appearance of the menu item. This optional parameter takes one or more redefined menu options, separated by commas or spaces. The menu options are as follows:

CHECKED

Item has a check mark next to it.

GRAYED

Item name is initially inactive and appears on the menu in gray or a lightened shade of the menu-text color.

HELP

Identifies a help item.

INACTIVE

Item name is displayed but it cannot be selected.

MENUBARBREAK

Same as MF_MENUBREAK except that for pop-up menus, it separates the new column from the old column with a vertical line.

MENUBREAK

Places the menu item on a new line for static menu-bar items. For pop-up menus, it places the menu item in a new column with no dividing line between the columns.

The INACTIVE and GRAYED options cannot be used together.

SEPARATOR

The MENUITEM SEPARATOR form of the MENUITEM statement creates an inactive menu item that serves as a dividing bar between two active menu items in a pop-up menu.

Example

The following example demonstrates the use of the MENUITEM and MENUITEM SEPARATOR statements:

MENUITEM "&Roman", 206, CHECKED, GRAYED
MENUITEM SEPARATOR
MENUITEM "&Blackletter", 301

See Also

MENU, POPUP


MESSAGETABLE Resource

nameID MESSAGETABLE filename

The MESSAGETABLE resource-deinition statement defines the ID and file of an applications message table resource. Message tables are special string resources used in event logging and with the FormatMessage API. The file contains a binary message table generated by the Message Compiler. The Message Compiler also generates a resource script file that contains the MESSAGETABLE statements you need to include the message table resources in the compiled resource file. Use the #include directive to include this resource script into your main resource script.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.

filename

Specifies the name of the file that contains the resource. The name must be a valid filename; it must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

See Also

STRINGTABLE Resource


POPUP Resource

POPUP text, [[optionlist]]

BEGIN
    item-definitions
    .
    .
    .
END

The POPUP statement marks the beginning of the definition of a pop-up menu. A pop-up menu (which is also known as a drop-down menu) is a special menu item that displays a sublist of menu items when it is selected.

Parameters

text

Specifies the name of the pop-up menu. This string must be enclosed in double quotation marks.

optionlist

Specifies one or more redefined menu options that specify the appearance of the menu item. The menu options follow:

CHECKED

Item has a check mark next to it. This option is not valid for a top-level pop-up menu.

GRAYED

Item name is initially inactive and appears on the menu in gray or a lightened shade of the menu-text color.

INACTIVE

Item name is displayed but it cannot be selected.

MENUBARBREAK

Same as MF_MENUBREAK except that for pop-up menus, it separates the new column from the old column with a vertical line.

MENUBREAK

Places the menu item on a new line for static menu-bar items. For pop-up menus, it places the menu item in a new column with no dividing line between the columns.

The INACTIVE and GRAYED options cannot be used together.

Example

The following example demonstrates the use of the POPUP statement:

chem MENU
BEGIN
    POPUP "&Elements"
    BEGIN
         MENUITEM "&Oxygen", 200
         MENUITEM "&Carbon", 201, CHECKED
         MENUITEM "&Hydrogen", 202
         MENUITEM SEPARATOR
         MENUITEM "&Sulfur", 203
         MENUITEM "Ch&lorine", 204
    END
    POPUP "&Compounds"
    BEGIN
         POPUP "&Sugars"
         BEGIN
            MENUITEM "&Glucose", 301
            MENUITEM "&Sucrose", 302, CHECKED
            MENUITEM "&Lactose", 303, MENUBREAK
            MENUITEM "&Fructose", 304
         END
         POPUP "&Acids"
         BEGIN
              "&Hydrochloric", 401
              "&Sulfuric", 402
         END
    END
END

See Also

MENU, MENUITEM


PUSHBOX Control

PUSHBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

The PUSHBOX statement creates a push-box control. Identical to a PUSHBUTTON, except that it does not display a button face or frame; only the text appears.

Parameters

style

Specifies styles for the pushbox, which can be a combination of the BS_PUSHBOX style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

The default style is BS_PUSHBOX and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

See Also

PUSHBUTTON


PUSHBUTTON Control

PUSHBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

The PUSHBUTTON statement creates a push-button control. The control is a round-cornered rectangle containing the given text. The text is centered in the control. The control sends a message to its parent whenever the user chooses the control.

Parameters

style

Specifies styles for the pushbutton, which can be a combination of the BS_PUSHBUTTON style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

The default style is BS_PUSHBUTTON and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

The following example demonstrates the use of the PUSHBUTTON statement:

PUSHBUTTON "ON", 7, 10, 10, 20, 10

See Also

GetDialogBaseUnits


RADIOBUTTON Control

RADIOBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

The RADIOBUTTON statement creates a radio-button control. The control is a small circle that has the given text displayed next to it, typically to its right. The control highlights the circle and sends a message to its parent window when the user selects the button. The control removes the highlight and sends a message when the button is next selected.

Parameters

style

Specifies styles for the radio button, which can be a combination of BUTTON-class styles and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

The default style for RADIOBUTTON is BS_RADIOBUTTON and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

The following example demonstrates the use of the RADIOBUTTON statement:

RADIOBUTTON "Italic", 100, 10, 10, 40, 10

See Also

GetDialogBaseUnits


RCDATA
RCDATA Resource

nameID RCDATA [[load-mem]]
[[optional-statements]]
BEGIN
    raw-data
    . . .
END

The RCDATA statement defines a raw data resource for an application. Raw data resources permit the inclusion of binary data directly in the executable file.

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer value that identifies the resource.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

optional-statements

Zero or more of the following statements:

Statement	Decription
CHARACTERISTICS dword	User-defined information about a resource that can be used by tools that read and write resource files.
LANGUAGE language, sublanguage	Specifies the language for the resource. The parameters are constants from WINNLS.H.
VERSION dword	User-defined version number for the resource that can be used by tools that read and write resource files.
raw-data

Specifies raw data consisting of one or more integers or strings of characters. Integers can be specified in decimal, octal, or hexadecimal format. RC does not automatically append a terminating null character to a string. The string is a sequence of the specified ANSI (byte) characters unless explicitly qualified as a wide-character string with the L prefix. Strings in all resources other than RCDATA and user-defined resources are Unicode strings.

The block of data begins on a DWORD boundary and RC performs no padding or alignment of data within the raw-data block. It is the programmers responsibility to ensure the proper alignment of data within the block.

Example

The following example demonstrates the use of the RCDATA statement:

resname RCDATA
BEGIN
   L"Here is a Unicode string\0", /* A Unicode string. Note: explicitly
                                 null-terminated */
   1024,                  /* int        */
   0x029a,                /* hex int    */
   0o733,                 /* octal int  */
   "\07"                  /* octal byte */
END

See Also

Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


RTEXT Control

RTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

The RTEXT statement creates a right-aligned text control. The control is a simple rectangle displaying the given text right-aligned in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line.

Parameters

style

Specifies styles for the text control, which can be any combination of the following: WS_TABSTOP and WS_GROUP.

The default style for RTEXT is SS_RIGHT and WS_GROUP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

The following example demonstrates the use of the RTEXT statement:

RTEXT "Number of Messages", 4, 30, 50, 100, 10

See Also

CONTROL, CTEXT, DIALOG, LTEXT


SCROLLBAR Control

SCROLLBAR text, id, x, y, width, height [[, style [[, extended-style]]]]

The SCROLLBAR statement creates a scroll-bar control. The control is a rectangle that contains a scroll box and has direction arrows at both ends. The scroll-bar control sends a notification message to its parent whenever the user clicks the mouse in the control. The parent is responsible for updating the scroll-box position. Scroll-bar controls can be positioned anywhere in a window and used whenever needed to provide scrolling input.

Parameters

style

Specifies a combination (or none) of the following styles: WS_TABSTOP, WS_GROUP, and WS_DISABLED.

In addition to these styles, the style parameter may contain a combination (or none) of the SCROLLBAR-class styles. The default style for SCROLLBAR is SBS_HORZ.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

Example

The following example demonstrates the use of the SCROLLBAR statement:

SCROLLBAR 999, 25, 30, 10, 100


STATE3 Control

STATE3  text, id, x, y, width, height [[, style [[, extended-style]]]]

The STATE3 statement defines a 3-state check box control. The control is identical to a CHECKBOX, except that it has three states: checked, unchecked, and disabled (grayed).

Parameters

text

Specifies text that is displayed to the right of the control.

style

Specifies the control styles. This value can be a combination of the button class style BS_3STATE and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_3STATE and WS_TABSTOP.

For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Statement Parameters.

See Also

AUTOCHECKBOX, CHECKBOX, CONTROL


STRINGTABLE Resource

STRINGTABLE [[load-mem]]
[[optional-statements]]
BEGIN
    stringID string
    . . .
END

The STRINGTABLE statement defines one or more string resources for an application. String resources are simply null-terminated Unicode strings that can be loaded when needed from the executable file, using the LoadString function.

Parameter

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

optional-statements

Zero or more of the following statements:

Statement	Decription
CHARACTERISTICS dword	User-defined information about a resource that can be used by tools that read and write resource files.
LANGUAGE language, sublanguage	Specifies the language for the resource. The parameters are constants from WINNLS.H.
VERSION dword	User-defined version number for the resource that can be used by tools that read and write resource files.
stringID

Specifies an unsigned 16-bit integer that identifies the resource.

string

Specifies one or more strings, enclosed in double quotation marks. The string must be no longer than 255 characters and must occupy a single line in the source file. To add a carriage return to the string, use this character sequence: \012. For example, Line one\012Line two would define a string that would be displayed as follows:

Line one
Line two

Comments

Grouping strings in separate sections allows all related strings to be read in at one time and discarded together. When possible, an application should make the table movable and discardable. RC allocates 16 strings per section and uses the identifier value to determine which section is to contain the string. Strings with the same upper-12 bits in their identifiers are placed in the same section.

Example

The following example demonstrates the use of the STRINGTABLE statement:

#define IDS_HELLO    1
#define IDS_GOODBYE  2

STRINGTABLE
BEGIN
    IDS_HELLO,   "Hello"
    IDS_GOODBYE, "Goodbye"
END

See Also

Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


STYLE Statement

STYLE style

The STYLE statement defines the window style of the dialog box. The window style specifies whether the box is a pop-up or a child window. The default style has the following attributes: WS_POPUP, WS_BORDER, and WS_SYSMENU.

Parameter

style

Specifies the window style. This parameter takes an integer value or redefined name. The following lists the redefined styles:

DS_LOCALEDIT

Specifies that edit controls in the dialog box will use memory in the application's data section. By default, all edit controls in dialog boxes use memory outside the application's data section. This feature can be suppressed by adding the DS_LOCALEDIT flag to the STYLE command for the dialog box. If this flag is not used, EM_GETHANDLE and EM_SETHANDLE messages must not be used since the storage for the control is not in the application's data section. This feature does not affect edit controls created outside of dialog boxes.

DS_MODALFRAME

Creates a dialog box with a modal dialog box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles.

DS_NOIDLEMSG

Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.

DS_SYSMODAL

Creates a system-modal dialog box.

WS_BORDER

Creates a window that has a border.

WS_CAPTION

Creates a window that has a title bar (implies the WS_BORDER style).

WS_CHILD

Creates a child window. It cannot be used with the WS_POPUP style.

WS_CHILDWINDOW

Creates a child window that has the WS_CHILD style.

WS_CLIPCHILDREN

Excludes the area occupied by child windows when drawing within the parent window. Used when creating the parent window.

WS_CLIPSIBLINGS

Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, this style clips all other top-level child windows out of the region of the child window to be updated. (If the WS_CLIPSIBLINGS style is not given and child windows overlap, it is possible, when drawing in the client area of a child window, to draw in the client area of a neighboring child window.) For use with the WS_CHILD style only.

WS_DISABLED

Creates a window that is initially disabled.

WS_DLGFRAME

Creates a window with a modal dialog box frame but no title.

WS_GROUP

Specifies the first control of a group of controls in which the user can move from one control to the next by using the arrow keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the style group and starts the next group (that is, one group ends where the next begins). This style is valid only for controls.

WS_HSCROLL

Creates a window that has a horizontal scroll bar.

WS_ICONIC

Creates a window that is initially iconic. For use with the WS_OVERLAPPED style only.

WS_MAXIMIZE

Creates a window of maximum size.

WS_MAXIMIZEBOX

Creates a window that has a Maximize box.

WS_MINIMIZE

Creates a window of minimum size.

WS_MINIMIZEBOX

Creates a window that has a Minimize box.

WS_OVERLAPPED

Creates an overlapped window. An overlapped window has a caption and a border.

WS_OVERLAPPEDWINDOW

Creates an overlapped window having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles.

WS_POPUP

Creates a pop-up window. It cannot be used with the WS_CHILD style.

WS_POPUPWINDOW

Creates a pop-up window that has the WS_POPUP, WS_BORDER, and WS_SYSMENU styles. The WS_CAPTION style must be combined with the WS_POPUPWINDOW style to make the System menu visible.

WS_SIZEBOX

Creates a window that has a size box. Used only for windows with a title bar or with vertical and horizontal scroll bars.

WS_SYSMENU

Creates a window that has a System-menu box in its title bar. Used only for windows with title bars. If used with a child window, this style creates a Close box instead of a System-menu box.

WS_TABSTOP

Specifies one of any number of controls through which the user can move by using the TAB key. The TAB key moves the user to the next control specified by the WS_TABSTOP style. This style is valid only for controls.

WS_THICKFRAME

Creates a window with a thick frame that can be used to size the window.

WS_VISIBLE

Creates a window that is initially visible. This applies to overlapping and pop-up windows. For overlapping windows, the y parameter is used as a parameter for the ShowWindow function.

WS_VSCROLL

Creates a window that has a vertical scroll bar.

Comments

If the redefined names are used, you must include WINDOWS.H.


User-Defined Resource

nameID typeID [[load-mem]] filename

The filename specifies the name of a file containing the binary data of the resource. The contents of the file are included as the resource. RC does not interpret the binary data in any way. It is the programmers responsibility to ensure that the data is properly aligned for the target machine architecture.

A user-defined resource can also be defined completely in the resource script using the syntax:

nameID typeID [[load-mem]]
BEGIN
    raw-data
END

A user-defined resource statement specifies a resource that contains application-specific data. The data can have any format and can be defined either as the content of a given file (if the filename parameter is given) or as a series of numbers and strings (if the raw-data block is given).

Parameters

nameID

Specifies either a unique name or a 16-bit unsigned integer that identifies the resource.

typeID

Specifies either a unique name or a 16-bit unsigned integer that identifies the resource type. If a number is given, it must be greater than 255. The numbers 1 through 255 are reserved for existing and future redefined resource types.

load-mem

Specifies loading and memory attributes for the resource. For more information, see Common Resource Attributes.

filename

Specifies the name of the file that contains the resource data. The parameter must be a valid filename; it must be a full path if the file is not in the current working directory.

raw-data

Specifies raw data consisting of one or more integers or strings of characters. Integers can be specified in decimal, octal, or hexadecimal format. RC does not automatically append a terminating null character to a string. The string is a sequence of the specified ANSI (byte) characters unless explicitly qualified as a wide-character string with the L prefix. Strings in all resources other than RCDATA and user-defined resources are Unicode strings.

The block of data begins on a DWORD boundary and RC performs no padding or alignment of data within the raw-data block. It is the programmers responsibility to ensure the proper alignment of data within the block.

Example

The following example shows several user-defined statements:

array   MYRES   data.res
14      300     custom.res
18 MYRES2
BEGIN
  "Here is a data string\0", /* A string. Note: explicitly
                                null-terminated */
   1024,                     /* int        */
   0x029a,                   /* hex int    */
   0o733,                    /* octal int  */
   "\07"                     /* octal byte */
END


VERSION Statement

VERSION dword

The VERSION statement allows the developer to specify version information about a resource that can be used by tools that read and write resource files. The specified dword value appears with the resource in the compiled .RES file. However, the value is not stored in the executable file and has no significance to Windows.

The VERSION statement appears before the BEGIN in an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition. The specified value applies only to that resource.

Parameter

dword

A user-defined doubleword value.

See Also

Multiline Statements
CHARACTERISTICS, LANGUAGE, VERSION
ACCELERATORS, DIALOG, MENU, RCDATA, STRINGTABLE


VERSIONINFO Resource

versionID VERSIONINFO fixed-info
BEGIN
    block-statement
    . . .
END

The VERSIONINFO statement creates a version-information resource. The resource contains such information about the file as its version number, its intended operating system, and its original filename. The resource is intended to be used with the File Installation library functions.

Parameters

versionID

Specifies the version-information resource identifier. This value must be 1.

fixed-info

Specifies the version information, such as the file version and the intended operating system. This parameter consists of the following statements:

FILEVERSION version

Specifies the binary version number for the file. The version consists of two 32-bit integers, defined by four 16-bit integers. For example, FILEVERSION 3,10,0,61 is translated into two doublewords: 0x0003000a and 0x0000003d, in that order. Therefore, if version is defined by the doublewords dw1 and dw2, they need to appear in the FILEVERSION statement as follows: HIWORD(dw1), LOWORD(dw1), HIWORD(dw2), LOWORD(dw2).

PRODUCTVERSION version

Specifies the binary version number for the product with which the file is distributed. The version parameter is two 32-bit integers, defined by four 16-bit integers. For more information about version, see the FILEVERSION description.

FILEFLAGSMASK fileflagsmask

Specifies which bits in the FILEFLAGS statement are valid. If a bit is set, the corresponding bit in FILEFLAGS is valid.

FILEFLAGS fileflags

Specifies the Boolean attributes of the file. The fileflags parameter must be the combination of all the file flags that are valid at compile time. For Windows 3.1, this value is 0x3f.

FILEOS fileos

Specifies the operating system for which this file was designed. The fileos parameter can be one of the operating system values given in the Comments section.

FILETYPE filetype

Specifies the general type of file. The filetype parameter can be one of the file type values listed in the Comments section.

FILESUBTYPE subtype

Specifies the function of the file. The subtype parameter is zero unless the type parameter in the FILETYPE statement is VFT_DRV, VFT_FONT, or VFT_VXD. For a list of file subtype values, see the Comments section.

block-statement

Specifies one or more version-information blocks. A block can contain string information or variable information.

Comments

To use the constants specified with the VERSIONINFO statement, the WINVER.H file (included in WINDOWS.H) must be included in the resource-definition file.

The following list describes the parameters used in the VERSIONINFO statement:

Parameter

fileflags

Specifies a combination of the following values:

VS_FF_DEBUG

File contains debugging information or is compiled with debugging features enabled.

VS_FF_INFOINFERRED

File contains a dynamically created version-information resource. Some of the blocks for the resource may be empty or incorrect. This value is not intended to be used in version-information resources created by using the VERSIONINFO statement.

VS_FF_PATCHED

File has been modified and is not identical to the original shipping file of the same version number.

VS_FF_PRERELEASE

File is a development version, not a commercially released product.

VS_FF_PRIVATEBUILD

File was not built using standard release procedures. If this value is given, the StringFileInfo block must contain a PrivateBuild string.

VS_FF_SPECIALBUILD

File was built by the original company using standard release procedures but is a variation of the standard file of the same version number. If this value is given, the StringFileInfo block must contain a SpecialBuild string.

fileos

Specifies one of the following values:

Value	Description
VOS_UNKNOWN	Operating system for which the file was designed is unknown to Windows.
VOS_DOS	File was designed for MS-DOS.
VOS_NT	File was designed for Windows NT.
VOS_WINDOWS16	File was designed for Windows version 3.0 or later.
VOS_WINDOWS32	File was designed for 32-bit Windows.
VOS_DOS_WINDOWS16	File was designed for Windows version 3.0 or later running with MS-DOS.
VOS_DOS_WINDOWS32	File was designed for 32-bit Windows running with MS-DOS.
VOS_NT_WINDOWS32	File was designed for 32-bit Windows running with Windows NT.
The values 0x00002L, 0x00003L, 0x20000L and 0x30000L are reserved.

filetype

Specifies one of the following values:

Value	Description
VFT_UNKNOWN	File type is unknown to Windows.
VFT_APP	File contains an application.
VFT_DLL	File contains a dynamic-link library (DLL).
VFT_DRV	File contains a device driver. If the dwFileType member is VFT_DRV, the dwFileSubtype member contains a more specific description of the driver.
VFT_FONT	File contains a font. If the dwFileType member is VFT_FONT, the dwFileSubtype member contains a more specific description of the font.
VFT_VXD	File contains a virtual device.
VFT_STATIC_LIB	File contains a static-link library.
All other values are reserved for use by Microsoft.

subtype

Specifies additional information about the file type.

If the FILETYPE statement specifies VFT_DRV, this parameter can be one of the following values:

Value	Description
VFT2_UNKNOWN	Driver type is unknown to Windows.
VFT2_DRV_COMM	File contains a communications driver.
VFT2_DRV_PRINTER	File contains a printer driver.
VFT2_DRV_KEYBOARD	File contains a keyboard driver.
VFT2_DRV_LANGUAGE	File contains a language driver.
VFT2_DRV_DISPLAY	File contains a display driver.
VFT2_DRV_MOUSE	File contains a mouse driver.
VFT2_DRV_NETWORK	File contains a network driver.
VFT2_DRV_SYSTEM	File contains a system driver.
VFT2_DRV_INSTALLABLE	File contains an installable driver.
VFT2_DRV_SOUND	File contains a sound driver.
If the FILETYPE statement specifies VFT_FONT, this parameter can be one of the following values:

Value	Description
VFT2_UNKNOWN	Font type is unknown to Windows.
VFT2_FONT_RASTER	File contains a raster font.
VFT2_FONT_VECTOR	File contains a vector font.
VFT2_FONT_TRUETYPE	File contains a TrueType font.
If the FILETYPE statement specifies VFT_VXD, this parameter must be the virtual-device identifier included in the virtual-device control block.

All subtype values not listed here are reserved for use by Microsoft.

langID

Specifies one of the following language codes:

Code	Language	Code	Language
0x0401	Arabic	0x0417	Rhaeto-Romanic
0x0402	Bulgarian	0x0418	Romanian
0x0403	Catalan	0x0419	Russian
0x0404	Traditional Chinese	0x041A	Croato-Serbian (Latin)
0x0405	Czech	0x041B	Slovak
0x0406	Danish	0x041C	Albanian
0x0407	German	0x041D	Swedish
0x0408	Greek	0x041E	Thai
0x0409	U.S. English	0x041F	Turkish
0x040A	Castilian Spanish	0x0420	Urdu
0x040B	Finnish	0x0421	Bahasa
0x040C	French	0x0804	Simplified Chinese
0x040D	Hebrew	0x0807	Swiss German
0x040E	Hungarian	0x0809	U.K. English
0x040F	Icelandic	0x080A	Mexican Spanish
0x0410	Italian	0x080C	Belgian French
0x0411	Japanese	0x0810	Swiss Italian
0x0412	Korean	0x0813	Belgian Dutch
0x0413	Dutch	0x0814	Norwegian − Nynorsk
0x0414	Norwegian − Bokml	0x0816	Portuguese
0x0415	Polish	0x081A	Serbo-Croatian (Cyrillic)
0x0416	Brazilian Portuguese	0x0C0C	Canadian French
0x0417	Rhaeto-Romanic	0x100C	Swiss French
charsetID

Specifies one of the following character-set identifiers:

Identifier	Character Set
0	7-bit ASCII
932	Windows, Japan (Shift − JIS X-0208)
949	Windows, Korea (Shift − KSC 5601)
950	Windows, Taiwan (GB5)
1200	Unicode
1250	Windows, Latin-2 (Eastern European)
1251	Windows, Cyrillic
1252	Windows, Multilingual
1253	Windows, Greek
1254	Windows, Turkish
1255	Windows, Hebrew
1256	Windows, Arabic
string-name

Specifies one of the following redefined names:

Comments

Specifies additional information that should be displayed for diagnostic purposes.

CompanyName

Specifies the company that produced the file—for example, "Microsoft Corporation" or "Standard Microsystems Corporation, Inc.". This string is required.

FileDescription

Specifies a file description to be presented to users. This string may be displayed in a list box when the user is choosing files to install—for example, "Keyboard Driver for AT-Style Keyboards" or "Microsoft Word for Windows". This string is required.

FileVersion

Specifies the version number of the file—for example, "3.10" or "5.00.RC2". This string is required.

InternalName

Specifies the internal name of the file, if one exists—for example, a module name if the file is a dynamic-link library. If the file has no internal name, this string should be the original filename, without extension. This string is required.

LegalCopyright

Specifies all copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on—for example, "Copyright© Microsoft Corporation 1990−1992". This string is optional.

LegalTrademarks

Specifies all trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on—for example, "Windows™ is a trademark of Microsoft® Corporation". This string is optional.

OriginalFilename

Specifies the original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.

PrivateBuild

Specifies information about a private version of the file—for example, "Built by TESTER1 on \TESTBED". This string should be present only if the VS_FF_PRIVATEBUILD flag is set in the dwFileFlags member of the VS_FIXEDFILEINFO structure of the root block.

ProductName

Specifies the name of the product with which the file is distributed—for example, Microsoft Windows. This string is required.

ProductVersion

Specifies the version of the product with which the file is distributed—for example, "3.10" or "5.00.RC2". This string is required.

SpecialBuild

Specifies how this version of the file differs from the standard version—for example, "Private build for TESTER1 solving mouse problems on M250 and M250E computers". This string should be present only if the VS_FF_SPECIALBUILD flag is set in the dwFileFlags member of the VS_FIXEDFILEINFO structure in the root block.

A string information block has the following form:

BLOCK "StringFileInfo"
BEGIN
    BLOCK "lang-charset"
    BEGIN
        VALUE "string-name", "value"
            . . .
    END
END

Following are the parameters in the StringFileInfo block:

lang-charset

Specifies a language and character-set identifier pair. It is a hexadecimal string consisting of the concatenation of the language and character-set identifiers listed earlier in this section.

string-name

Specifies the name of a value in the block and can be one of the redefined names listed earlier in this section.

value

Specifies, as a character string, the value of the corresponding string name. More than one VALUE statement can be given.

A variable information block has the following form:

BLOCK "VarFileInfo"
BEGIN
    VALUE "Translation",
        langID, charsetID
            . . .
END

Following are the parameters in the variable information block:

langID

Specifies one of the language identifiers listed earlier in this section.

charsetID

Specifies one of the character-set identifiers listed earlier in this section. More than one identifier pair can be given, but each pair must be separated from the preceding pair with a comma.


Resource Compiler Contents
 Resource Compiler for Windows NT

Microsoft Windows Resource Compiler (RC) is a tool for the Microsoft Windows NT operating system. This document describes how to create a resource-definition (script) file, and how to compile your application's resources and add them to the application's executable file.


 Including Resources in an Application

To include resources in your 32-bit Windows application, do the following:

1.	Create individual resource files for cursors, icons, bitmaps, dialog boxes, and fonts. To do this, you can use AppStudio.

2.	Create a resource-definition file (script) that describes all the resources used by the application.

3.	Compile the script into a resource (.RES) file with RC.

4.	Link the compiled resource files into the application's executable file.

Unlike for the 16-bit versions of the Windows development system, you do not use RC to include compiled resources into the executable file or to mark the file as a Windows application. The linker recognizes the compiled resource files and links them to the executable file.


Creating a Resource-Definition File

After creating individual resource files for your application's icon, cursor, font, bitmap, and dialog-box resources, you create a resource-definition file, or script. A script file is a text file with the extension .RC.

The script lists every resource in your application and describes some types of resources in great detail. For a resource that exists in a separate file, such as an icon or cursor, the script names the resource and the file that contains it. For some resources, such as a menu, the entire definition of the resource exists within the script .

A script file can contain the following types of information:

Preprocessing directives, which instruct RC to perform actions on the script before compiling it. Directives can also assign values to names.

Statements, which name and describe resources.


Common Statement Parameters

This section lists parameters in common among the resource or control statements. Occasionally, a certain statement will use a parameter differently, or may ignore a parameter. The statement-specific variation is described with the statement in the alphabetical reference.

Common Control Parameters

The general syntax for a control definition, and the meaning of each parameter is as follows:

control [[text,]] id, x, y, width, height [[, style [[, extended-style]]]]

Horizontal dialog units are 1/4 of the dialog base width unit. Vertical units are 1/8 of the dialog base height unit. The current dialog base units are computed from the height and width of the current system font. The GetDialogBaseUnits function returns the dialog base units in pixels. The coordinates are relative to the origin of the dialog box.

Parameters

control

Keyword that indicates the type of control being defined, such as PUSHBUTTON or CHECKBOX.

text

Specifies text that is displayed with the control. The text is positioned within the controls specified dimensions, or adjacent to the control.

This parameter must contain zero or more characters enclosed in double quotation marks.  Strings are automatically null-terminated and converted to Unicode in the resulting resource file, except for strings specified in raw-data statements. (raw-data can be specified in RCDATA and user-defined resources.) To specify a Unicode string in raw-data, explicitly qualify the string as a wide-character string by using the L prefix.

By default, the characters listed between the double quotation marks are ANSI characters and escape sequences are interpreted as byte escape sequences. If the string is preceded by the L prefix, the string is a wide-character string and escape sequences are interpreted as two-byte escape sequences that specify Unicode characters. If a double quotation mark is required in the text, you must include the double quotation mark twice or use the \" escape sequence.

An ampersand (&) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the ampersand is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. To use the ampersand as a character in a string, insert two ampersands (&&).

id

Specifies the control identifier. This value must be a 16-bit unsigned integer in the range 0 through 65,535 or a simple arithmetic expression that evaluates to a value in that range.

x

Specifies the x-coordinate of the left side of the control relative to the left side of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control.

y

Specifies the y-coordinate of the top side of the control relative to the top of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units relative to the origin of the dialog box, window, or control containing the specified control.

width

Specifies the width of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The width is in 1/4-character units.

height

Specifies the height of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The height is in 1/8-character units.

style

Specifies the control styles. Use the bitwise OR (|) operator to combine styles.

extended-style

Specifies extended (WS_EX_xxx) styles. You must specify a style to specify an extended-style. See also EXSTYLE.


text

Specifies text that is displayed with the control. The text is positioned within the controls specified dimensions, or adjacent to the control.

This parameter must contain zero or more characters enclosed in double quotation marks.  Strings are automatically null-terminated and converted to Unicode in the resulting resource file, except for strings specified in raw-data statements. (raw-data can be specified in RCDATA and user-defined resources.) To specify a Unicode string in raw-data, explicitly qualify the string as a wide-character string by using the L prefix.

By default, the characters listed between the double quotation marks are ANSI characters and escape sequences are interpreted as byte escape sequences. If the string is preceded by the L prefix, the string is a wide-character string and escape sequences are interpreted as two-byte escape sequences that specify Unicode characters. If a double quotation mark is required in the text, you must include the double quotation mark twice or use the \ escape sequence.

An ampersand (&) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the ampersand is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. To use the ampersand as a character in a string, insert two ampersands (&&).


id

Specifies the control identifier. This value must be a 16-bit unsigned integer in the range 0 through 65,535 or a simple arithmetic expression that evaluates to a value in that range.


x

Specifies the x-coordinate of the left side of the control relative to the left side of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control.


y

Specifies the y-coordinate of the top side of the control relative to the top of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units relative to the origin of the dialog box, window, or control containing the specified control.


width

Specifies the width of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The width is in 1/4-character units.


height

Specifies the height of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The height is in 1/8-character units.


style

Specifies the control styles. Use the bitwise OR (|) operator to combine styles.


extended-style

Specifies extended (WS_EX_xxx) styles. You must specify a style to specify an extended-style. See also EXSTYLE.


Common Resource Attributes

All resource-definition statements include a load-mem option that specifies the loading and memory characteristics of the resource. These attributes are divided into two groups: load attributes and memory attributes. The only attribute that is used by Win32 is the DISCARDABLE attribute. The remaining attribute specifiers are allowed in the script for compatibility with existing scripts, but are ignored.

Load Attributes

The load attributes specify when the resource is to be loaded. The load parameter must be one of the following:

PRELOAD

Ignored. In 16-bit Windows, the resource is loaded with the executable file.

LOADONCALL

Ignored. In 16-bit Windows, the resource is loaded when called.

Memory Attributes

The memory attributes specify whether the resource is fixed or movable, whether it is discardable, and whether it is pure. The memory parameter can be one or more of the following:

FIXED

Ignored. In 16-bit Windows, the resource remains at a fixed memory location.

MOVEABLE

Ignored. In 16-bit Windows, the resource can be moved if necessary in order to compact memory.

DISCARDABLE

Resource can be discarded if no longer needed.

PURE

Ignored. Accepted for compatibility with existing resource scripts.

IMPURE

Ignored. Accepted for compatibility with existing resource scripts.

The default is DISCARDABLE for cursor, icon, and font resources.


Preprocessing Directives

The following directives can be used as needed in the script to instruct RC to perform actions or to assign values to names:

Directive	Description
#define	Defines a specified name by assigning it a given value.
#elif	Marks an optional clause of a conditional-compilation block.
#else	Marks the last optional clause of a conditional-compilation block.
#endif	Marks the end of a conditional-compilation block.
#if	Conditionally compiles the script if a specified expression is true.
#ifdef	Conditionally compiles the script if a specified name is defined.
#ifndef	Conditionally compiles the script if a specified name is not defined.
#include	Copies the contents of a file into the resource-definition file.
#undef	Removes the definition of the specified name.
The syntax and semantics for the RC preprocessor is the same as for a C compiler. For more information on preprocessing in RC, see Preprocessing Reference.


Single-Line Statements

A single-line statement can begin with any of the following keywords:

Keyword	Description
BITMAP	Defines a bitmap by naming it and specifying the name of the file that contains it. (To use a particular bitmap, the application requests it by name.)
CURSOR	Defines a cursor by naming it and specifying the name of the file that contains it. (To use a particular cursor, the application requests it by name.)
FONT	Specifies the name of a file that contains a font.
ICON	Defines an icon by naming it and specifying the name of the file that contains it. (To use a particular icon, the application requests it by name.)
LANGUAGE	Sets the language for all resources up to the next LANGUAGE statement or to the end of the file. When the LANGUAGE statement appears before the BEGIN in an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition, the specified language applies only to that resource.
MESSAGETABLE	Defines a message table by naming it and specifying the name of the file that contains it. The file is a binary resource file generated by the Message Compiler.


Multiline Statements

A multiline statement can begin with any of the following keywords:

Keyword	Description
ACCELERATORS	Defines menu accelerator keys.
DIALOG	Defines a template that an application can use to create dialog boxes.
MENU	Defines the appearance and function of a menu.
RCDATA	Defines data resources. Data resources let you include binary data in the executable file.
STRINGTABLE		Defines string resources. String resources are Unicode strings that can be loaded from the executable file.
Each of these multiline statements allows optional statements before the BEGIN ... END block that defines the resource. You can specify zero or more of the following statements:

Statement	Decription
CHARACTERISTICS dword	User-defined information about the resource that can be used by tools that read and write resource files. The value appears in the compiled resource file. However, it is not stored in the executable file and is not used by Windows.
LANGUAGE language, sublanguage	Specifies the language for the resource. The parameters are constants from WINNLS.H.
VERSION dword	User-defined version number for the resource that can be used by tools that read and write resource files. The value appears in the compiled resource file. However, it is not stored in the executable file and is not used by Windows.


Sample Resource-Definition File

The following example shows a script file that defines the resources for an application named Shapes:

#include "SHAPES.H"

ShapesCursor  CURSOR  SHAPES.CUR
ShapesIcon    ICON    SHAPES.ICO

ShapesMenu    MENU
    BEGIN
        POPUP "&Shape"
            BEGIN
                MENUITEM "&Clear", ID_CLEAR
                MENUITEM "&Rectangle", ID_RECT
                MENUITEM "&Triangle", ID_TRIANGLE
                MENUITEM "&Star", ID_STAR
                MENUITEM "&Ellipse", ID_ELLIPSE
            END
    END

The CURSOR statement names the application's cursor resource ShapesCursor and specifies the cursor file SHAPES.CUR, which contains the image for that cursor.

The ICON statement names the application's icon resource ShapesIcon and specifies the icon file SHAPES.ICO, which contains the image for that icon.

The MENU statement defines an application menu named ShapesMenu, a pop-up menu with five menu items.

The menu definition, enclosed by the BEGIN and END keywords, specifies each menu item and the menu identifier that is returned when the user selects that item. For example, the first item on the menu, Clear, returns the menu identifier ID_CLEAR when the user selects it. The menu identifiers are defined in the application header file, SHAPES.H.


Using RC
Using RC (The RC Command Line)

To start RC, use the RC command. The following line shows RC command-line syntax:

RC [[options]] script-file

The RC command's options parameter can include one or more of the following options:

/?

Displays a list of RC command-line options.

/d

Defines a symbol for the preprocessor that you can test with the #ifdef directive.

/foresname

Uses resname for the name of the .RES file.

/h

Displays a list of RC command-line options.

/i

Searches the specified directory before searching the directories specified by the INCLUDE environment variable.

/r

Ignored. Provided for compatibility with existing makefiles.

/v

Displays messages that report on the progress of the compiler.

/x

Prevents RC from checking the INCLUDE environment variable when searching for header files or resource files.

Options are not case-sensitive, and a hyphen (-) can be used in place of a slash mark (/). You can combine single-letter options if they do not require any additional parameters. For example, the following two commands are equivalent:

RC /V /X SAMPLE.RC

rc -vz sample.rc

The script-file parameter specifies the name of the resource-definition file that contains the names, types, filenames, and descriptions of the resources to be compiled.


Defining Names for the Preprocessor

You can specify conditional compilation in a script, based on whether a name is defined on the RC command line with the /d option, or in the file or an include file with the #define directive.

For example, suppose your application has a pop-up menu, the Debug menu, that should appear only with debugging versions of the application. When you compile the application for normal use, the Debug menu is not included. The following example shows the statements that can be added to the resource-definition file to define the Debug menu:

MainMenu MENU
BEGIN
  . . .
#ifdef DEBUG
        POPUP "&Debug"
        BEGIN
                MENUITEM "&Memory usage", ID_MEMORY
                MENUITEM "&Walk data heap", ID_WALK_HEAP
        END
#endif
END

When compiling resources for a debugging version of the application, you could include the Debug menu by using the following RC command:

rc -d DEBUG myapp.rc

To compile resources for a normal version of the application—one that does not include the Debug menu—you could use the following RC command:

rc myapp.rc


Renaming the Compiled Resource File

By default, when compiling resources, RC names the compiled resource (.RES) file with the base name of the .RC file and places it in the same directory as the .RC file. The following example compiles MYAPP.RC and creates a compiled resource file named MYAPP.RES in the same directory as MYAPP.RC:

rc myapp.rc

The /fo option lets you give the resulting .RES file a name that differs from the name of the corresponding .RC file. For example, to name the resulting .RES file NEWFILE.RES, you would use the following command:

rc -fo newfile.res myapp.rc

The /fo option can also place the .RES file in a different directory. For example, the following command places the compiled resource file MYAPP.RES in the directory C:\SOURCE\RESOURCE:

rc -fo c:\source\resource\myapp.res myapp.rc


Searching for Files

By default, RC searches for header files and resource files (such as icon and cursor files) first in the current directory and then in the directories specified by the INCLUDE environment variable. (The PATH environment variable has no effect on which directories RC searches.)

Adding a Directory to Search

You can use the /i option to add a directory to the list of directories RC searches. The compiler then searches the directories in the following order:

1.	The current directory

2.	The directory or directories you specify by using the /i option, in the order in which they appear on the RC command line

3.	The list of directories specified by the INCLUDE environment variable, in the order in which the variable lists them, unless you specify the /x option

The following example compiles the resource-definition file MYAPP.RC:

rc /i c:\source\stuff /i d:\resources myapp.rc

When compiling the script MYAPP.RC, RC searches for header files and resource files first in the current directory, then in C:\SOURCE\STUFF and D:\RESOURCES, and then in the directories specified by the INCLUDE environment variable.

Suppressing the INCLUDE Environment Variable

You can prevent RC from using the INCLUDE environment variable when determining the directories to search. To do so, use the /x option. The compiler then searches for files only in the current directory and in any directories you specify by using the /i option.

The following example compiles the script file MYAPP.RC:

rc /x /i c:\source\stuff myapp.rc

When compiling the script MYAPP.RC, RC searches for header files and resource files first in the current directory and then in C:\SOURCE\STUFF. It does not search the directories specified by the INCLUDE environment variable.


Displaying Progress Messages

By default, RC compiles quietly. It does not display messages that report on its progress. You can, however, specify that RC is to display these messages. To do so, use the /v option.

The following example causes RC to report on its progress as it compiles the resource-definition file SAMPLE.RC and creates the compiled resource file SAMPLE.RES:

rc /v sample.rc


Preprocessing Reference

The syntax and semantics for the RC preprocessor is the same as for the preprocessor in a C compiler. Single-line comments begin with two forward slashes (//) and run to the end of the line. Block comments begin with an opening delimiter (/*) and run to a closing delimiter (*/). Comments do not nest.

You use the #define directive to define symbols for your resource identifiers in a header file. You include this header both in the resource script and your application source code. Similarly, the values for attributes and styles are defined by including the C header files for Windows.

You can also define macros. The standard C preprocessing operators (#, ##) can be used in a macro definition. For detailed information on preprocessing and defining macros, see your C compiler documentation.

Directive	Description
#define	Defines a specified name by assigning it a given value.
#elif	Marks an optional clause of a conditional-compilation block.
#else	Marks the last optional clause of a conditional-compilation block.
#endif	Marks the end of a conditional-compilation block.
#if	Conditionally compiles the script if a specified expression is true.
#ifdef	Conditionally compiles the script if a specified name is defined.
#ifndef	Conditionally compiles the script if a specified name is not defined.
#include	Copies the contents of a file into the resource-definition file.
#undef	Removes the definition of the specified name.


#define

#define name value

The #define directive assigns the given value to the specified name. All subsequent occurrences of the name are replaced by the value.

Parameters

name

Specifies the name to be defined. This value is any combination of letters, digits, and punctuation.

value

Specifies any integer, character string, or line of text.

Example

This example assigns values to the names NONZERO and USERCLASS:

#define     NONZERO     1
#define     USERCLASS   "MyControlClass"

See Also

#ifdef, #ifndef, #undef


#elif

#elif constant-expression

The #elif directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #elif directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after #endif. If the constant expression is zero, #elif directs the compiler to skip to the next #endif, #else, or #elif directive. You can use any number of #elif directives in a conditional block.

Parameter

constant-expression

Specifies the expression to be checked. This value is a defined name, an integer constant, or an expression consisting of names, integers, and arithmetic and relational operators.

Example

In this example, #elif directs the compiler to process the second BITMAP statement only if the value assigned to the name Version is less than 7. The #elif directive itself is processed only if Version is greater than or equal to 3.

#if Version < 3
BITMAP 1 errbox.bmp
#elif Version < 7
BITMAP 1 userbox.bmp
#endif

See Also

#else, #endif, #if, #ifdef, #ifndef


#else

#else

The #else directive marks an optional clause of a conditional-compilation block defined by a #ifdef, #ifndef, or #if directive. The #else directive must be the last directive before the #endif directive.

This directive has no arguments.

Example

This example compiles the second BITMAP statement only if the name DEBUG is not defined:

#ifdef DEBUG
    BITMAP 1 errbox.bmp
#else
    BITMAP 1 userbox.bmp
#endif

See Also

#elif, #endif, #if, #ifdef, #ifndef


#endif

#endif

The #endif directive marks the end of a conditional-compilation block defined by a #ifdef directive. One #endif is required for each #if, #ifdef, or #ifndef directive.

This directive has no arguments.

See Also

#elif, #else, #if, #ifdef, #ifndef


#if

#if constant-expression

The #if directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, #if directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the constant expression is zero, #if directs the compiler to skip to the next #endif, #else, or #elif directive.

Parameter

constant-expression

Specifies the expression to be checked. This value is a defined name, an integer constant, or an expression consisting of names, integers, and arithmetic and relational operators.

Example

This example compiles the BITMAP statement only if the value assigned to the name Version is less than 3:

#if Version < 3
BITMAP 1 errbox.bmp
#endif

See Also

#elif, #else, #endif, #ifdef, #ifndef


#ifdef

#ifdef name

The #ifdef directive controls conditional compilation of the resource file by checking the specified name. If the name has been defined by using a #define directive or by using the -d command-line option with the Resource Compiler, #ifdef directs the compiler to continue with the statement immediately after the #ifdef directive. If the name has not been defined, #ifdef directs the compiler to skip all statements up to the next #endif directive.

Parameter

name

Specifies the name to be checked by the directive.

Example

This example compiles the BITMAP statement only if the name Debug is defined:

#ifdef Debug
BITMAP 1 errbox.bmp
#endif

See Also

#define, #endif, #if, #ifndef, #undef


#ifndef

#ifndef name

The #ifndef directive controls conditional compilation of the resource file by checking the specified name. If the name has not been defined or if its definition has been removed by using the #undef directive, #ifndef directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the name is defined, #ifndef directs the compiler to skip to the next #endif, #else, or #elif directive.

Parameter

name

Specifies the name to be checked by the directive.

Example

This example compiles the BITMAP statement only if the name Optimize is not defined:

#ifndef Optimize
BITMAP 1 errbox.bmp
#endif

See Also

#elif, #else, #endif, #if, #ifdef, #undef


#include

#include (filename)

The #include directive causes Resource Compiler to process the file specified in the filename parameter. This file should be a header file that defines the constants used in the resource-definition file.

Parameter

filename

Specifies the name of the file to be included. If the file is in the current directory, the string must be enclosed in double quotation marks; if the file is in the directory specified by the INCLUDE environment variable, the string must be enclosed in less-than and greater-than characters (<>). You must give a full path enclosed in double quotation marks if the file is not in the current directory or in the directory specified by the INCLUDE environment variable.

Example

This example processes the header files WINDOWS.H and HEADERS\MYDEFS.H while compiling the resource-definition file:

#include <windows.h>
#include "headers\mydefs.h"

See Also

#define


#undef

#undef name

The #undef directive removes the current definition of the specified name. All subsequent occurrences of the name are processed without replacement.

Parameter

name

Specifies the name to be removed. This value is any combination of letters, digits, and punctuation.

Example

This example removes the definitions for the names nonzero and USERCLASS:

#undef     nonzero
#undef     USERCLASS

See Also

#define


Using Search Plus

Search Plus provides a way to search the full text of help files. You can search for a single word, a combination of words in a topic, one word near another word, an exact phrase, and so on.

  To search for a word or phrase:

1.	If the help file is not already open, open it using WINHLP32.

2.	Click Search Plus on the button bar.

3.	Enter the word or words that you want to find in the Search dialog box.

If you want to enter groups of words, or exclude words, and so on, click the Hints button. This displays the Search Hints dialog box. It describes the use of keywords to combine words, the use of quoting and grouping operators, and the use of a wildcard for expanding a root word.

You can also set the range used for the keyword NEAR. It determines how many other words can separate two words for which you are searching.

4.	In the Look At group box, select either the Topic Titles Only or the All Text option button.

5.	In the Look In group box, select the help files in which you want to search for the desired topic.

6.	Click the Search button.

The titles of topics found are displayed in the Topics Found list.

7.	Double-click the desired topic in the Topics Found list. Each entry in the topic displayed is highlighted.

Topics in the current help file have no label before the topic title. Topics in other help files in the group are preceded by a label. These labels change as you switch from one help file to another.

You can also use the Go To, Next and Previous buttons to display topics.

Tips and Troubleshooting

Using Search Keywords

The keywords AND, OR, and NOT operate only on a topic level. The following Search For string finds any topic that contains both words:

menu AND command

The order of words in the Search For string does not matter. The following Search For strings produce identical results:

menu AND command

and

command AND menu

The search mechanism ignores letter case. The same results appear if you search for cobject or COBJECT.

You cannot search for the Search keywords, such as NOT, for instance.

Exclusion from Searches

You can search for alphanumeric characters only. Characters such as ~ [tilde], # [number sign], \ [backslash] and ( [left parenthesis] are excluded from the search.

Some words are excluded from the full-text search capability in order to build a smaller search index file. The excluded words are not usually helpful for finding information in this kind of material, such as "because," for instance.

This exclusion has a side-effect with the NEAR keyword, because excluded words are essentially invisible to the search mechanism, even though they are visible to you on the topic page. For instance, if you set NEAR to 1 and search for:

menus NEAR commands

the search would find "commands because the menus" in the sentence "It may not display all the listed commands because the menus are dynamic," since both "because" and "the" are excluded from the search index.

Narrowing Your Search

If you find a very large number of topics with your search, you can narrow your search in four ways:

Exclude help files in the Look In group from the search list by clearing the check box for the help file.

Use the keywords (AND, OR and NOT) and the grouping operators listed in the Search Hints dialog box to create likely combinations of words.

Use the "" quoting operators to search for an exact phrase.

Use the NEAR keyword with combinations of words to find only those that are close together in a topic.

Recovering from Errors

If you get an error message that refers to an old or missing index file, one of two things may have happened:

The .IND index file may have accidentally been deleted or moved to a directory other than that containing the help files. In this case, reinstall the help files using Setup.

The VIEWER.INI file may have been deleted or corrupted. In this case, simply close the help file, open it again and try again.

If you get an error message that refers to a title setup problem, when you click the OK button, the Help file will close. In this case, open the help file again and continue.