────────────────────────────────────────────────────────────────────────────
Microsoft (R) C - REFERENCE
VERSION 6.0
────────────────────────────────────────────────────────────────────────────
MICROSOFT CORPORATION
Information in this document is subject to change without notice and does
not represent a commitment on the part of Microsoft Corporation. The
software described in this document is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to copy
the software on any medium except as specifically allowed in the license or
nondisclosure agreement. No part of this manual may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including
photocopying and recording, for any purpose without the express written
permission of Microsoft.
(C) Copyright Microsoft Corporation, 1989. All rights reserved.
Simultaneously published in the U.S. and Canada.
Printed and bound in the United States of America.
Microsoft, MS, MS-DOS, XENIX, CodeView, and QuickC are
registered trademarks of Microsoft Corporation.
IBM is a registered trademark of International Business
Machines Corporation.
Intel is a registered trademark of Intel Corporation.
Lotus is a registered trademark of Lotus Development
Corporation.
Tandy is a registered trademark of Tandy Corporation.
Document No. LN0802a-600-R00-0989
Part No. 06515
10
9
8
7
6
5
4
3
2
1
Table of Contents
────────────────────────────────────────────────────────────────────────────
Introduction
About This Book
Document Conventions
PART I Utilities
────────────────────────────────────────────────────────────────────────────
The Microsoft(R) C Reference contains essential information about the
language, run-time library, and utility programs that comprise version 6.0
of the Microsoft C Professional Development System. This book is aimed at
the experienced programmer who needs a particular fact─the meaning of an
option, the syntax of a pragma, the arguments to a library function. Much of
the information is in lists and tables, organized to help you find it at a
glance.
The C Reference is designed to complement the other Microsoft C
documentation, including Installing and Using the Professional Development
System, Advanced Programming Techniques, and the Advisor (on-line help).
For example, while Installing and Using introduces you to Microsoft C and
teaches you how to use the Programmer's WorkBench (PWB), the C Reference
assumes that you are already familiar with using PWB. Thus, it lists all the
functions and keystrokes, both alphabetically and by use, as well as return
values and editor switches─but it does not teach you how to use them. You'll
find a discussion about how to optimize C programs to best advantage in
Advanced Programming Techniques. In this C Reference you'll find a complete
list of all the compiler options, including those for optimization, and a
short description of what each one does─but not which is best in a
particular situation.
About This Book
The parts of this book and what they contain are discussed below.
Utilities
Part 1 of the Microsoft C Reference summarizes the utility programs included
with the Microsoft C Professional Development System. The utilities are
listed alphabetically. A brief description and the syntax appear at the
beginning of each utility's description, followed by command-line options.
The description may also include other useful information. For example, the
coverage of LINK lists module-definition file statements used in Windows(tm)
and OS/2 applications; the pages on the CodeView(R) debugger list dialog
commands as well as size and format specifiers.
Language Reference
Part 2 includes the basic elements of the C language: it lists keywords and
escape sequences, and gives the syntax and a short explanation of
statements, preprocessor directives, and pragmas. It also provides tables of
information on operators and data type sizes.
Run-Time Library Functions
The Microsoft C libraries contain over 500 functions. Part 3 of this book
first lists the functions by category. It then provides an alphabetical
overview of each function, listing the function prototype, the include file,
the parameter list, a brief description, and compatibility.
Appendixes
The appendixes contain various useful tables, such as one on printf and
scanf formatting codes. They also list compiler limits and program limits at
run time, the data ranges defined in LIMITS.H, and the numerical values
defined in FLOAT.H. Finally, there are numeric and ASCII conversion tables.
The pages that follow use the term "OS/2" to refer to the OS/2
systems─Microsoft Operating System/2 (MS(R) OS/2) and IBM(R) OS/2.
Similarly, the term "DOS" refers to both the MS-DOS(R) and IBM Personal
Computer DOS operating systems. The name of a specific operating system is
used when it is necessary to note features that are unique to the system.
────────────────────────────────────────────────────────────────────────────
Document Conventions
This book uses the following document conventions :
Example Description
────────────────────────────────────────────────────────────────────────────
STDIO.H Uppercase letters indicate file names,
segment names, registers, and terms used
at the
operating-system command level.
_far Boldface letters indicate C keywords,
operators,
language-specific characters, and
library routines. Within discussions of
syntax, bold type indicates that the
text must be entered exactly as shown.
expression Words in italics indicate placeholders
for information you must supply, such as
a file name. Italics are also
occasionally used for emphasis in the
text.
«option» Items inside double square brackets are
optional.
#pragma pack {1|2} Braces and a vertical bar indicate a
choice among two or more items. You must
choose one of these items unless double
square brackets surround the braces.
#include <io.h> This font is used for examples, user
input, program output, and error
messages in text.
CL options «files...» Three dots following an item indicate
that more items having the same form may
appear.
while() A column of three dots tells you that
{ part of the program has been
. intentionally omitted.
.
.
}
CTRL+ENTER Small capital letters are used for the
names of keys on the keyboard. When you
see a plus sign (+) between two key
names, you should hold down the first
key while pressing the second.
The carriage-return key, sometimes
marked as a bent arrow on the keyboard,
is called ENTER.
The cursor-movement keys are called the
arrow keys. Individual keys are referred
to by their direction (LEFT, UP) or by
the name on the key (PGUP).
"argument" Quotation marks enclose a new term the
first time it is defined in text.
"C string" Some C constructs, such as strings,
require quotation marks. Quotation marks
required by the language have the form "
" and ' ' rather than " " and ' '.
Color Graphics The first time an acronym is used, it is
Adapter (CGA) often
spelled out.
PART I Utilities
────────────────────────────────────────────────────────────────────────────
The BIND utility converts protected-mode programs that use Family API
functions to access system services, allowing them to run in both real mode
and protected mode.
In the syntax above, infile contains the name of the OS/2 application,
implibs contains the name of one or more import libraries, and linklibs
contains the name of one or more standard libraries and object files.
Options
/HELP Provides on-line help for BIND. First
BIND attempts to execute the QuickHelp
program, QH.EXE. If QuickHelp or its
database is unavailable, the /HELP
option lists BIND syntax and options to
the standard output.
/M«AP» mapfile Causes a link map to be generated to
mapfile for the real mode environment of
the executable file.
/N«AMES» functions Allows the listing of functions
supported in protected mode only. Use
with a list of functions or a file
specification preceded by @.
/NOLOGO Suppresses display of the sign-on banner.
/O«UTFILE» outfile Specifies the name for the bound
application, outfile.
/A {T|S|M|C|L|H} Selects one of these standard memory
models:
Option Comments
────────────────────────────────────────────────────────────────────────────
/AT Tiny memory model. Code and
data are limited to 64K
total. Must link with
CRTCOM.LIB. Creates a .COM
file for real mode. (Same as
/Asnd.)
/AS Small memory model. Code and
data are limited to 64K each.
(Same as /Asnd.)
/AM Medium memory model. Data is
limited to 64K. (Same as
/Alnd.)
/AC Compact memory model. Code
is limited to 64K. (Same as
/Asfd.)
/AL Large memory model. No
limits on code or data.
(Same as /Alfd.)
/AH Huge memory model. Same as
large model, but individual
arrays can exceed 64K. (Same
as /Alhd.)
/Astring Sets up a customized memory model. The
string consists of three characters in
any order, indicating code and data
pointer size and segment setup.
╓┌───────────────┌───────────┌───────────────────────────────────────────────╖
Group Code Description
────────────────────────────────────────────────────────────────────────────
Code pointers s Small (Near)
l Large (Far)
Group Code Description
────────────────────────────────────────────────────────────────────────────
l Large (Far)
Data pointers n Near
f Far
h Huge
Segment setup d SS == DS
u SS != DS; DS loaded for each function entry
w SS != DS; DS not loaded at function entry
/B1 «path» Invokes an alternative preprocessor
called C1L.EXE. Use this option to
compile programs that generate the
message
the compiler is out of near heap. The
drive and path where C1L.EXE resides are
optionally specified in path.
/B2 «path» Invokes an alternative compiler pass two
called C2L.EXE.
/B3 «path» Invokes an alternative compiler pass
three called C3L.EXE.
/C Preserves comments when preprocessing a
file; use only with /E, /P, or /EP.
/c Compiles without linking. Creates an
object file but not an executable file.
/D id « = «value» » Defines the symbolic constant id to the
preprocessor. If value is defined, the
value of id is value. If the equal sign
is given without value, the value of id
is empty. If id is given without the
equal sign, the value of id is 1.
/E Preprocesses the source file, copying
the result to the standard output and
inserting #line directives.
/EP Preprocesses the source file, copying
the result to the standard output
without #line directives.
/F hexnum Sets stack size to hexnum bytes (this is
the same as
/link /STACK:number). The value must be
expressed in
hexadecimal notation.
/Fa «listfile» Produces an assembly listing. If
listfile is unspecified, /Fa
defaults to sourcefilename.ASM. Not
available with the /qc
option.
/Fbbound-exe Creates a bound executable file. Use
only with /Lp.
/Fc «listfile» Produces a combined source-assembly code
listing. If listfile is unspecified, /Fc
defaults to sourcefilename.COD. Not
available with the /qc option.
/Fe exefile Names the executable file.
/Fl «listfile» Generates an object-code listing. If
listfile is not given, /Fl
defaults to sourcefilename.COD. Not
available with the /qc
option.
/Fm «mapfile» Creates a linker map file. If mapfile is
not given, /Fm defaults to
first-sourcefilename.MAP.
/Fo objfile Names the object file.
/FPa Generates floating-point calls and
selects the alternate math library. Not
available with the /qc option.
/FPc Generates floating-point calls and
selects the emulator library (which uses
an 80x87 coprocessor if one is present).
Not available with the /qc option.
/FPc87 Generates floating-point calls and
selects an 80x87 library (which requires
an 80x87 coprocessor at run time). Not
available with the /qc option.
/FPi Generates in-line 80x87 instructions and
selects an emulator library (uses an 80x
87 coprocessor if one is present). This
is the default /FP option.
/FPi87 Generates in-line 80x87 instructions and
selects an 80x87 library (which requires
an 80x87 coprocessor at run time).
/Fr «browsefile» Generates a standard PWB Source Browser
database. If
browsefile is unspecified, /Fr defaults
to basename.SBR.
/FR «browsefile» Generates an extended Source Browser
database. If browsefile is unspecified,
/FR defaults to basename.SBR.
/Fs «listfile» Produces a source listing. If listfile
is unspecified, /Fs defaults to
sourcefilename.LST. Not available with
the /qc option.
/Fx«xreffile» Specifies a name for the Microsoft Macro
Assembler (MASM) cross-reference file.
If xreffile is unspecified, /Fx
defaults to sourcefilename.CRF.
/G0 Generates 8086/8088 instructions. This
is the default /G
option.
/G1 Generates 80186/80188 instructions.
/G2 Generates 80286 instructions.
/Gc Specifies use of FORTRAN- or
Pascal-style function calling and naming
conventions.
/Gd Specifies standard (default) C calling
conventions.
/Ge Enables calls to the stack-checking
routine (default).
/Gi Compiles incrementally (when used in
conjunction with the /qc option); only
functions that have changed are
recompiled. Without /qc, /Gi
incrementally links by padding object
files. Implies /Li.
/Gm Stores strings in the constant (CONST)
segment. Not available with the /qc
option.
/Gr Enables the new _fastcall function to
call conventions for eligible functions.
When possible, values are passed in
registers instead of on the stack.
/Gs Suppresses generation of calls to the
stack-checking routine.
/Gt«number» Places data items greater than or equal
to number bytes in a new segment.
Default is 256 if no number is specified.
/Gw Generates entry/exit code sequences
suitable for use in
Microsoft Windows(tm) applications.
/GW Same as /Gw, but generates more
efficient entry sequences. Used for code
other than user callback functions.
/H number Restricts external names to number
significant characters. The default is
31 characters. Not available with the
/qc option.
/HELP Calls the QuickHelp utility. If the
QuickHelp program is not available, CL
displays the most commonly used options
to the standard output. This option is
not case sensitive.
/I directory Adds directory to the beginning of the
list of directories to be searched for
include files.
/J Changes the default for char type from
signed to unsigned.
/Lc Causes the linker to create a
compatibility mode executable file. Same
as /Lr.
/Li«number» Invokes the incremental linker ILINK
instead of the standard linker LINK.
ILINK runs faster than LINK while
creating larger executable files. The
optional number specifies the byte
boundary to which the linker pads all
near functions.
/Lp Causes the linker to create a
protected-mode executable file.
/Lr Causes the linker to create a real-mode
executable file.
/link link-libinfo Passes linker options or library names
in link-libinfo to LINK.
/MAMASM_option Passes the specified option to the
Microsoft Macro Assembler (MASM). MASM
is automatically invoked for files
listed on the command line with the
extension .ASM.
/MD Creates a dynamically linked C run-time
library (OS/2 only). Equivalent to /ALw
/FPi /G2 /DDLL /DMT. No library search
record.
/ML Statically links the C run-time library
as part of a dynamic-link library (OS/2
only). Equivalent to /ALw /FPa /G2 /DMT.
Library search record is changed to
LLIBCDLL.LIB.
/MT Enables support for multithread programs
(OS/2 only). Equivalent to /ALw /FPi /G2
/DMT. Library search record is changed
to LLIBCMT.LIB.
/NDdataseg Sets the data segment name.
/NMmodule Sets the module name.
/nologo Suppresses display of the sign-on banner.
/NTtextseg Sets the code segment name.
/O«opt_codes» Controls optimization. When no codes are
included, default optimization is
enabled. The optional opt_codes argument
may contain one or more of the following
characters:
Code Description
────────────────────────────────────────────────────────────────────────────
a Assumes no aliasing
c Enables default (block-level)
local common expressions
d Disables all optimizations
e Enables global register
allocation
g Enables global optimizations
and global common
expressions
i Enables generation of
intrinsic routines
l Enables loop optimizations
n Disables unsafe loop
optimizations (default)
p Improves consistency in
floating-point
calculations
r Disables in-line returns
from functions
s Favors smaller code size
t Favors faster execution
speed (default)
w Assumes no aliases except
across function calls (not
available with the /qc
option)
x Maximizes optimizations
(equivalent to /Oecilgt/Gs)
z Enables maximum loop and
global-register-allocation
optimization
/P Preprocesses the source file and sends
output to a file
having the base name of the source file
and the extension .I
(basename.I).
/qc Invokes the quick compile option. The
following options produce an error
during a quick compile: /Fa, /Fc, /Fl,
/FPa, /FPc, /FPc87, /Fs, /Gm, /H, /Ow,
/Zc.
/Sl linewidth Sets the line width of source listing in
characters per line. Range is 79-132.
Default is 79.
/Sp pagelength Sets the page length of source listing
in lines per page. Range is 15-255.
Default is 63.
/Ss subtitle Specifies subtitle for source listing.
/St title Specifies title for source listing.
/Ta asm_srcfile Specifies that asm_srcfile is to be
treated as an assembler source file,
whether or not it has an .ASM extension.
/Tc c-srcfile Indicates that c-srcfile is a C source
file, whether or not it has a .C
extension.
/u Removes (undefines) definitions of all
predefined identifiers.
/U identifier Removes the definition of the given
predefined identifier.
/V string Copies the version string to the object
file.
/w Suppresses compiler warning messages;
same as /W0.
/W{0 | 1 | 2 | 3 | 4} Sets the output level for compiler
warning messages. The default is 1.
/WX Makes all warnings fatal; no object file
is generated when a warning occurs.
/X Ignores the list of "standard places" in
the search for include files.
/Za Enforces American National Standards
Institute (ANSI)
language compatibility, disabling
extensions specific to
Microsoft C.
/Zc Causes functions declared as _pascal to
be treated without regard to case. Not
available with the /qc option.
/Zd Generates line-number information
required for the SYMDEB debugger.
/Ze Enables extensions specific to Microsoft
C. This is the default /Z option.
/Zg Generates function prototypes from
function definitions and writes
declarations to standard output, without
compiling the program.
/Zi Generates symbolic information required
by the Microsoft CodeView(R)
window-oriented debugger.
/Zl Suppresses emission of library search
records in the object file.
/Zp«{1 | 2 | 4}» Packs structure members on the specified
byte boundary.
/Zr Generates code that checks for null
pointers and out-of-range far pointers
(in the CL command, use only with /qc).
The Microsoft CodeView window-oriented debugger runs the compiled program
while simultaneously displaying the program source code, program variables,
memory locations, processor registers, and other pertinent information.
Syntax
CV «options» executablefile «arguments»
To debug protected-mode programs, set IOPL = YES in your CONFIG.SYS file and
use the following syntax:
CVP «options» executablefile «arguments»
Options
/2 Permits the use of two monitors
/25 Starts in 25-line mode
/43 Starts in EGA 43-line mode
/50 Starts in VGA 50-line mode
/B Starts in black-and-white mode with CGA
or EGA
/Ccommands Executes commands on start up
/D«buffersize» Enables disk overlays (DOS only)
/E Enables Expanded Memory Support (EMS)
(DOS only)
/F Does not swap video pages between
CodeView and the program you are
debugging; exchanges debug and output
screens by flipping between video pages
(faster than /S)
/Inumber Turns nonmaskable interrupts and
8259-interrupt trapping on (/I1) or off
(/I0)
/K Disables installation of keyboard
monitors for the program being debugged
/L dynlib Enables CodeView to search OS/2
dynamic-link libraries for symbolic
information
/M Disables CodeView support of the mouse
(use this option when debugging an
application that supports the mouse)
/Nnumber /N0 tells CodeView to trap; /N1 tells it
not to
/O Enables debugging of multiple processes
under OS/2 protected mode
/R Enables 80386 debug registers (not
available under OS/2)
/S Starts with screen swapping (exchanges
screens by changing buffers, primarily
for use with graphics programs)
/X Uses extended memory to increase
debugging capacity (DOS only)
CodeView Commands
╓┌────────────────────────┌───────────────────────┌──────────────────────────╖
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
Display help about the F1 Click Help menu
selected topic
Display contents of SHIFT+F1 Click Help menu Contents
help command
Go to next help screen CTRL+F1 ─
Go to previous help SHIFT+CTRL+F1 ─
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
Go to previous help SHIFT+CTRL+F1 ─
topic
Go to previously viewed ALT+F1 Click Back button on help
help screen screen
Toggle register window F2 Click View menu
Registers command
Toggle F3 Click Options menu Source
source/assembly/mixed Window command
modes
Change flag in register Any printing character Double-click Left button
window on flag
Delete character at DEL ─
cursor
Toggle insert and INS ─
overstrike modes
Copy text into delete CTRL+INS Click Edit menu Copy
buffer command
Paste text from delete SHIFT+INS Click Edit menu Paste
buffer command
Move to next command TAB Click Left button at
(Command location
window only)
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
window only)
Move to previous SHIFT+TAB Click Left button at
command (Command location
window only)
Find selected text CTRL+\ Click Search menu
Selected Text command
Repeat last find ALT+/ Click Search menu Repeat
Find command
Add Watch expression CTRL+W Click Watch menu Add
Watch command
Delete Watch expression CTRL+U Click Watch menu Delete
Watch command
Open QuickWatch window SHIFT + F9 Click Watch window
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
Open QuickWatch window SHIFT + F9 Click Watch window
for a variable QuickWatch command
Scroll up one line in CTRL+UP Click Left button on up
window arrow on scroll bar
Scroll down one line in CTRL+DOWN Click Left button on down
window arrow on scroll bar
Scroll up one page in PGUP Click Left button above
window vertical elevator
Scroll down one page in PGDN Click Left button below
window vertical elevator
Scroll window to the CTRL+PGUP Click Left button on left
left
arrow or to left of
horizontal
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
horizontal
elevator
Scroll window to the CTRL+PGDN Click Left button on
right right arrow or to right
of horizontal elevator
Move cursor to HOME Click Left button at
beginning of line location
Move cursor to end of END Drag elevator to bottom
line
Scroll to top of file CTRL+HOME Drag vertical elevator to
top
Scroll to end of file CTRL+END Drag elevator to bottom
Move cursor one word CTRL+LEFT/ Click Left button at
Action Keyboard Mouse
────────────────────────────────────────────────────────────────────────────
Move cursor one word CTRL+LEFT/ Click Left button at
CTRL+RIGHT location
Move cursor one line UP/DOWN Click Left button at
location
╓┌────────────────────┌──────────────────────────────────────────┌───────────►
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
address « «segment | register»: »offset Identifies th
(type *) constant of an express
various comma
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
various comma
Breakpoint Clear BC {list | * } Clears breakp
list or in al
breakpoints (
Breakpoint BD {list | * } Turns off bre
Disable in list or in
breakpoints (
Breakpoint Enable BE {list | * } Enables break
list or in al
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
list or in al
breakpoints (
Breakpoint List BL Lists breakpo
the status of
Breakpoint Set BP «address» «=symbol«range» » | «? Breaks execut
expression» «, passcount» address is re
«,"commands"» Breaks execut
the value of
changes; if a
listed, the e
is evaluated
that address
Breaks execut
expression is
address is li
expression is
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
expression is
only at that
Comment *comment Displays expl
text
Compare Memory C range address Compares byte
with bytes be
address; disp
mismatched pa
Current . Displays the
Location location
Delay : Delays execut
redirected co
(may be repea
longer delays
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
Delete Watch Y {number | *} Deletes (yank
statements
Display ? expression«, format» Displays expr
Expression format
Dump D«type» «address | range» Dumps memory
range in type
Enter E«type» address «list» Enters memory
type format
Fill Memory F range list Fills address
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
Fill Memory F range list Fills address
range with va
list
Go G «breakaddress» Executes to
breakaddress
List Watch W Lists current
statements
Move Memory M range address Copies values
memory block
Options O«option«+ | -» » Views or sets
options, incl
bytes coded (
flip/swap (F)
sensitivity (
symbol addres
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
symbol addres
symbols (S),
386 (3)
Pause " Interrupts ex
redirected co
waits for key
Port Input I port Reads and dis
from port
Port Output O port byte Sends byte to
Program Step P «count» Executes sour
or instructio
stepping over
procedure, an
interrupt cal
repeats count
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
repeats count
Quick Watch ?? symbol Displays loca
variables and
data structur
dialog box
Quit Q Exits and ret
DOS
Radix N «radixnumber» Sets input ra
Redirection « « «T»>«>» » | < | =»devicename Redirects inp
output to or
devicename
Redraw @ Redraws the screen
Register R «registername « «=»expression» » Displays regi
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
Register R «registername « «=»expression» » Displays regi
flags, or set
registers and
Restart L «arguments» Restarts prog
Screen \ «time» Exchanges the
Exchange and output sc
Search / «regularexpression» Searches for
expression
Search Memory S range list Searches rang
values in lis
Shell Escape !«command» Escapes to a
OS/2 shell an
command
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
Source Display Mode S « + | - | & » Sets display
source,
assembly, or
Stack Trace K Displays acti
routines on t
Tab Set #number Sets number s
each tab char
Trace T «count» Executes sour
or instructio
tracing into
pro-
cedure, or in
calls; repeat
times
Name Syntax Description
─────────────────────────────────────────────────────────────────────────────
Unassemble U «viewaddress» Displays
assembly-lang
instructions
The prefix h can be used with the integer-type specifiers (d, o, u, x, and
X) to specify a short int. The prefix l can be used with the same types to
specify a long int.
────────────────────────────────────────────────────────────────────────────
Command-Window Commands (Protected Mode)
Syntax Description
────────────────────────────────────────────────────────────────────────────
None Default type
| Displays process ID number (PID) and
session (screen group) ID number
| processID Enables direct debugging of the child
process identified
Thread Commands
Syntax
~«specifier«command» »
In the syntax above, the specifier specifies the thread or threads, and
command determines debugging activity.
The legal values for specifier and their effects are listed below.
Specifier Function
────────────────────────────────────────────────────────────────────────────
Blank Displays the status of all threads. If
you omit the specifier field you cannot
enter a command. Instead, you enter the
tilde (~) by itself.
# Specifies the last thread that was
executed, which is not necessarily the
current thread.
* Specifies all threads.
number Specifies the indicated thread, where
number must be a number corresponding to
an existing thread. You can determine
corresponding numbers for all threads by
entering the command ~*, which gives the
status of all threads.
Specifies the current thread.
The legal values for command and their effects are listed below.
Command Function
────────────────────────────────────────────────────────────────────────────
Blank Displays the status of the selected
thread (or threads).
BP Sets the breakpoint for the specified
thread or threads.
E Executes the specified thread in slow
motion. The command ~*E is legal only in
source mode, where it executes the
current thread in slow motion but lets
all other unfrozen threads run.
F Freezes the specified thread (or
threads). A frozen thread will not run
in the background or in response to the
debugger Go command. However, if you use
the E, G, P, or T variation of the
Thread command, the specified thread is
temporarily unfrozen while the debugger
executes the command.
G Passes control to the specified thread
until it terminates or until a
breakpoint is reached. If you give the
command ~*G, all threads execute
concurrently (except for those that are
frozen). If you specify a particular
thread, the debugger temporarily freezes
all other threads and executes the
specified thread.
P Executes a program step for the
specified thread. The command ~*P is
legal only in source mode and causes the
debugger to step to the next source line
while letting all other threads run
(except for those that are frozen). You
see only the current thread execute in
the debugger display.
S Selects the specified thread as the
current thread. Can apply to only one
thread at a time. Thus, the command ~*S
results in an error message.
T Traces the specified thread. Identical
to P, except that T traces through
function calls and interrupts, whereas P
does not.
U Unfreezes the specified thread or
threads. Reverses the effect of a freeze.
Effect of Threads on CodeView Commands
Whether or not you use the Thread Command, the existence of threads affects
your CodeView debugging session at all times. Particular debugger commands
are strongly affected. Each of these commands is discussed below.
Command Behavior in Multiple-Thread Programs
────────────────────────────────────────────────────────────────────────────
The Current Location command always uses
the current value of CS:IP to determine
what the current instruction is. Thus,
the Current Location command applies to
the current thread.
E When the debugger is in source mode, the
Execute command is equivalent to the ~*E
command. The current thread is executed
in slow motion while all other threads
are also running. When the debugger is
in mixed or assembly mode, the
Execute command is equivalent to the
command ~.P, which does not let other
threads run concurrently.
BP The Breakpoint Set command is equivalent
to the ~*BP command; the breakpoint
applies to all threads.
G The Go command is equivalent to the ~*G
command; control is passed to the
operating system, which executes all
threads in the program except for those
that are frozen.
P When the debugger is in source mode, the
Program Step command is equivalent to
the command ~*P, which lets other
threads run concurrently. When the
debugger is in mixed or assembly mode,
the Program Step command is equivalent
to the command ~.P, which lets no other
threads run.
K The Stack Trace command displays the
stack of the current thread.
T When the debugger is in source mode, the
Trace command is equivalent to the
command ~*T, which lets other threads
run concurrently. When the debugger is
in mixed or assembly mode, the Trace
command is equivalent to the command ~.T,
which lets no other threads run.
The CVPACK utility reads through an .EXE file and combines multiple-module
debugging information into one table at the end of the file. CodeView can
then load the file more quickly.
Syntax
CVPACK «options» filename
Options
/HELP Causes CVPACK to attempt to call the
QuickHelp program
The EXEHDR utility displays and modifies the contents of an executable-file
header.
Syntax
EXEHDR «options» filename
Options
/HEAP:nnnn Sets the heap allocation field to nnnn
for segmented executable files.
/HELP Calls the QuickHelp utility. If the
QuickHelp program is not available,
EXEHDR displays the usage message to the
standard output.
/MAX:nnnn Sets the maximum allocation field to
nnnn paragraphs for DOS.
/MIN:nnnn Sets the minimum allocation field to
nnnn paragraphs for DOS.
/NOLOGO Directs EXEHDR to suppress the sign-on
banner.
/PMTYPE:type Sets the window type for Presentation
Manager programs, where type is one of
PM (equivalent to WINDOWAPI), VIO
(equivalent to WINDOWCOMPAT), or NOVIO
(equivalent to NOTWINDOWCOMPAT).
/RESETERROR Resets the error bit in the header of an
OS/2 or Windows executable file. It has
no effect on DOS executable files.
/STACK:nnnn Sets the stack allocation field to nnnn
for DOS and segmented-executable files.
/VERBOSE Provides more information about
protected mode (OS/2) executable files
and DLLs, including the default flags in
the segment table, all run-time
relocations, and additional fields from
the .EXE header.
The EXP utility expunges (removes) all files from the DELETED subdirectory.
Copies of deleted files are placed in DELETED by PWB (when the backup switch
is on) and by RM.
Syntax
EXP «options» «directory»
If no directory is specified, the current directory's DELETED subdirectory
is used.
Options
/HELP Causes EXP to attempt to call the
QuickHelp program
/Q Specifies quiet mode (the deleted file
names are not displayed on the screen)
/R Causes EXP to operate recursively on all
subdirectories
The HELPMAKE utility creates help files and customizes the help files
supplied with Microsoft language products. It creates a help database from
one or more input files that contain information specially formatted for the
help system.
Syntax
HELPMAKE «options» {/E«n» | /D} sourcefiles
You must supply the /HELP, /E (encode), or /D (decode) option.
Options
/Ac Specifies c as an application-specific
control character for the help database,
marking a line that contains special
information for internal use by the
application.
/C Indicates that the context strings are
case sensitive. At run time, all
searches for help topics are case
sensitive.
/D«letter» Decodes the input file into its
component parts. If a destination file
is not specified with the /O option, the
help file is decoded to stdout. HELPMAKE
decodes the file in different ways,
depending on the letter specified.
Letter Effect
────────────────────────────────────────────────────────────────────────────
/D "Decode." Fully decodes the
help database, leaving all
cross-references and
formatting information
intact.
/DS "Decode split." Splits the
concatenated, compressed
help database into its
components, using their
original names. If the
database was created without
concatenation (the default),
HELPMAKE simply copies it to
a file with its original
name. No decompression
occurs.
/DU "Decode unformatted."
Decompresses the database
and removes all screen
formatting and
cross-references. The output
can still be used later for
input and recompression, but
all of the screen formatting
and
cross-references are lost.
/E«n» Creates ("encodes") a help database from
a specified text file (or files). The
optional n indicates the amount of
compression to take place. If n is
omitted, HELPMAKE compresses the file as
much as possible, thereby reducing the
size of the file by about 50 percent.
The more compression requested, the
longer HELPMAKE takes to create a
database file. The value of n is a
number in the range 0-15. It is the sum
of successive powers of 2 representing
these compression techniques:
Value Technique
────────────────────────────────────────────────────────────────────────────
0 No compression
1 Run-length compression
2 Keyword compression
4 Extended-keyword compression
8 Huffman compression
Add values to combine compression
techniques. For example, use /E3 to get
run-length and keyword compression.
/H Displays a summary of HELPMAKE syntax
and then exits.
/HELP Calls the QuickHelp utility. If the
QuickHelp program is not available,
HELPMAKE displays the most commonly used
HELPMAKE options to the standard output
(without encoding or decoding any files).
/K filename Specifies a file containing
word-separator characters. This file
should consist of a single line of text
containing characters that separate
words. ASCII characters from 0 to 32
(including the space), and character 127,
are always separators. If the /K option
is not specified, the following
characters are also considered
separators:
!"#&'()*+-,/:;<=>?@[\]^_`{\}~
/L Locks the generated file so that it
cannot be decoded by HELPMAKE at a later
time.
/Ooutfile Specifies outfile as the name of the
help database. The name outfile is
optional with the /D option.
/Sn Specifies the type of input file,
according to the following n values:
Option File Type
────────────────────────────────────────────────────────────────────────────
/S1 Rich Text Format (RTF)
/S2 QuickHelp Format (default)
/S3 Minimally Formatted ASCII
/T During encoding, translates dot commands
to application-specific commands. During
decoding, translates application
commands to dot commands.
/V«n» Indicates the "verbosity" of diagnostic
and informational output, depending on
the value of n. If you omit this option
or specify only /V, HELPMAKE gives you
its most verbose output. The possible
values of n are listed below:
Option Effect
────────────────────────────────────────────────────────────────────────────
/V Maximum diagnostic output
/V0 No diagnostic output and no
banner
/V1 Prints only HELPMAKE banner
/V2 Prints pass names
/V3 Prints contexts on first
pass
/V4 Prints contexts on each pass
/V5 Prints any intermediate
steps within each pass
/V6 Prints statistics on help
file and compression
/Wn Indicates the fixed width of the
resulting help text in number of
characters. The value of n can range
from 11 to 255. If /W is omitted, the
default is 76. When encoding RTF source
(/S1), HELPMAKE automatically formats
the text to n. When encoding QuickHelp
(/S2) or minimally formatted ASCII (/S3)
files, HELPMAKE truncates lines to n
characters.
The ILINK utility invokes the Microsoft Incremental Linker.
Syntax
ILINK «options» projname «modulelist»
Options
/A Directs ILINK to check for changes in
the object files since the last linking
process.
/C Specifies case sensitivity for all
public symbol names.
/E "commands" Specifies commands to be executed if
incremental linking fails. The option /E
"LINK /INC" is the default.
/HELP Provides on-line help about the
incremental linker. First /HELP attempts
to execute the QuickHelp program QH.EXE.
If QuickHelp or its database is
unavailable, /HELP lists ILINK options
to the standard output.
/I Specifies that only an incremental link
is to be attempted. If the incremental
link fails, a fatal error follows the
incremental violation message.
/NOLOGO Causes ILINK to suppress the sign-on
banner.
/V Verbose mode. Directs ILINK to list all
changed modules.
/X Prevents ILINK from allocating memory
from an expanded memory manager if one
is present.
/HELP Provides on-line help for LIB. First
/HELP attempts to execute the QuickHelp
program QH.EXE. If QuickHelp or its
database is unavailable, /HELP lists the
LIB options to the standard output.
/I«GNORECASE» Directs LIB to ignore case when
comparing symbols (the default). Use to
combine a library marked /NOI with an
unmarked library for a new unmarked
library.
/NOE«XTDICTIONARY» Prevents LIB from creating an extended
dictionary.
/NOI«GNORECASE» Directs LIB not to ignore case when
comparing symbols.
/NOL«OGO» Causes LIB to suppress the sign-on
banner.
/PA«GESIZE»:n Specifies the library-page size of a new
library, or changes the library-page
size of an existing library. The default
page size for a new library is 16 bytes.
Commands
+filename Appends an object file or library file
to the given library
-filename Deletes a module from the library
-+filename Replaces a module by deleting it from
the library and appending to the library
an object file with the same name
*filename Extracts a module without deleting it
from the library and saves the module as
an
object file with the same name
(copies it)
-*filename Extracts a module and deletes it from
the library after saving it in an object
file with the same name (moves it)
────────────────────────────────────────────────────────────────────────────
NOTE
Place an ampersand (&) at the end of an input line to continue the command
codes on the next line.
────────────────────────────────────────────────────────────────────────────
LINK (Linker)
────────────────────────────────────────────────────────────────────────────
Summary
The Microsoft Segmented-Executable Linker (LINK) combines object files into
a single executable file.
Directs LINK to align segment data in
the executable file along the boundaries
specified by size, where size must be a
power of two. Default is 512.
/BA /BA«TCH»
Suppresses prompts for library or object
files not found. LINK generates error or
warning messages instead, if appropriate.
Also prevents LINK from printing the
sign-on banner and echoing input from
response files.
/CO /CO«DEVIEW»
Creates a special-format executable file
containing the symbolic data and
line-number information needed by the
Microsoft CodeView debugger.
/CP /CP«ARMAXALLOC»:bytes
Sets the program's maximum memory
allocation to bytes.
/DO /DO«SSEG»
For assembly-language programs only.
Forces segments in the executable file
to be ordered as follows:
1. Segments with class name ending in CODE
2. All other segments outside DGROUP
3. DGROUP segments, in the following order:
a. Segments of class BEGDATA
b. Segments not of class BEGDATA, BSS, or STACK
c. Segments of class BSS
d. Segments of class STACK
/DS /DS«ALLOCATE»
For assembly-language programs only.
Directs the linker to load all data
starting at the high end of the data
segment instead of the low end.
/E /E«XEPACK»
Packs the executable file during linking
by removing repeated series of bytes.
/F /F«ARCALLTRANSLATION»
Directs the linker to optimize far calls
to procedures that lie in the same
segment as the caller. Use in
conjunction with /PACKCODE. Far-call
translation is turned on by default.
/HE /HE«LP»
Provides on-line help about the linker.
First LINK attempts to execute the
QuickHelp program QH.EXE. If QuickHelp
or its database is unavailable, LINK
lists all available options to the
standard output.
/HI /HI«GH»
Places the executable file as high in
memory as possible. For real-mode
assembly-language programs only.
/INC /INC«REMENTAL»
Prepares for subsequent incremental
linking with ILINK. Incompatible with /E
and /TINY.
/INF /INF«ORMATION»
Causes the linker to display phase of
linking and names of object files being
linked to the standard output.
/LI /LI«NENUMBERS»
Includes source-file line numbers and
associated addresses in the map file. In
addition, an object file with
line-number information must be given to
LINK. The /Zd option can be used with
most Microsoft compilers to include line
numbers in the object file. If LINK is
given an object file without linenumber
information, the /LI option has no
effect.
/M /M«AP»
Creates a listing file containing all
public (global) symbols defined in the
input modules.
/NOD /NOD«EFAULTLIBRARYSEARCH» «:filename»
Causes default libraries to be ignored.
If filename is specified, LINK searches
all libraries except filename.
/NOE /NOE«XTDICTIONARY»
Prevents the linker from searching the
extended dictionary (an internal list of
intermodule dependencies). Use this
option to suppress error messages about
multiple symbol definitions.
/NOF /NOF«ARCALLTRANSLATION»
Turns off far-call translation
(translation of far calls to near calls
where possible). Far-call translation is
off by default.
/NOI /NOI«GNORECASE»
Causes the linker to distinguish between
uppercase and lowercase letters.
/NOL /NOL«OGO»
Causes the linker to suppress the
sign-on banner.
/NON /NON«ULLSDOSSEG»
Directs the linker to arrange segments
in the executable file in the same order
as they are arranged by the /DOSSEG
option, with no additional bytes at the
beginning of the _TEXT segment (if it is
defined).
/NOP /NOP«ACKCODE»
Turns code-segment packing off (if
code-segment packing has been turned on).
/O /O«VERLAYINTERRUPT»:number
Allows the user to select an interrupt
number other than 63 (the default) for
passing control to overlays.
/PACKC /PACKC«ODE» «:number»
Directs the linker to group neighboring
code segments together in the medium,
large, and huge memory models, where
number specifies the maximum size of
groups formed by /PACKCODE. When used
with /FARCALLTRANSLATION, this produces
smaller code.
/PACKD /PACKD«ATA» «:number»
Directs the linker to group neighboring
data segments together in the compact,
large, and huge memory models, where
number specifies the maximum size of
groups formed by /PACKDATA.
/PADC /PADC«ODE»:padsize
Directs the linker to add filler bytes
to the end of each code module for
subsequent linking with ILINK; padsize
specifies the number of bytes.
/PADD /PADD«ATA»:padsize
Adds padsize bytes to each data segment.
/PAU /PAU«SE»
Causes the linker to pause in the
linking session so that disks can be
changed. This option is provided for
floppy-disk users.
/PM /PM«TYPE»:type
Sets the window type for Presentation
Manager (PM) programs, where type is:
Type Windows Equivalent
────────────────────────────────────────────────────────────────────────────
PM WINDOWAPI keyword in a
module
definition (.DEF) file
VIO WINDOWCOMPAT
NOVIO NOTWINDOWCOMPAT
/Q /Q«UICKLIB»
Produces a Quick library for use with
Microsoft QuickC(R) (early versions only)
or Microsoft QuickBASIC.
/SE /SE«GMENTS»:number
Sets the maximum number of segments the
program can have, which can be any
positive value up to 3,072 bytes. The
default is 128.
/ST /ST«ACK»:number
Sets the stack size to number, which can
be any positive value up to 65,535 bytes.
The default for C programs is 0x800
(2,048) bytes.
/T /T«INY»
Causes the linker to produce .COM files.
Incompatible with /INCREMENTAL.
/W /W«ARNFIXUP»
Issues a warning for each segment offset
previously at the beginning of a group
but altered during linking to no longer
be at the beginning of a group.
Default File-Name Extensions
File Type Default Extension
────────────────────────────────────────────────────────────────────────────
Object .OBJ
Executable .EXE (or .COM with /T option)
Map .MAP
Standard Library .LIB
Dynamic-Link Library .DLL (OS/2 and Windows only)
Module Definitions .DEF (OS/2 and Windows only)
Module-Definition Files
A module-definition file is required for Windows applications and libraries
and for dynamic-link libraries (DLLs) that run under OS/2. Such files are
optional (but desirable) for all OS/2 applications. Each file contains one
or more module statements that describe the module name, attributes of
program segments, and number and names of exported and imported functions.
Following the list of module statements below is a description of each one,
including syntax and fields.
NAME DATA IMPORTS OLD
LIBRARY SEGMENTS STUB REALMODE
DESCRIPTION STACKSIZE HEAPSIZE EXETYPE
CODE EXPORTS PROTMODE
NAME Statement
Summary
The NAME statement identifies the executable file as an application and
optionally defines the name and type.
Syntax
NAME «app_name» «app_type»
Fields
app_name Name of the application. Can be any
valid file name.
Defines the type of application to be
linked in a Windows environment.
WINDOWAPI specifies a Presentation
Manager (PM) application using the API
provided by PM and must be executed in
the PM environment. This is equivalent
to linker option /PMTYPE:PM.
WINDOWCOMPAT specifies a PM-compatible
application that can run inside a PM
window or in a separate screen group
using the proper subset of OS/2 video,
keyboard, and mouse functions supported
in PM applications. This is equivalent
to linker option /PMTYPE:VIO.
NOTWINDOWCOMPAT specifies that the
application is not compatible with PM
and must operate in a separate screen
group from PM. This is equivalent to
linker option
/PMTYPE:NOVIO.
LIBRARY Statement
Summary
The LIBRARY statement identifies the executable file as a dynamic-link
library. It can specify the name of the library or the type of
library-module initialization required.
Syntax
LIBRARY «libraryname» «initialization»
Fields
libraryname Name of the library. Can be any valid
file name.
initialization {INITGLOBAL | INITINSTANCE}
Determines the type of initialization
required. INITGLOBAL specifies that the
library-initialization routine is called
only when the library module is
initially loaded into memory.
INITINSTANCE specifies that the
library-initialization routine is called
each time a new process gains access to
the library. This option is necessary
for DLLs that use the C library
functions.
DESCRIPTION Statement
Summary
The DESCRIPTION statement inserts the specified text into the application or
library.
Syntax
DESCRIPTION 'text'
The text is a one-line string enclosed in single quotation marks.
CODE Statement
Summary
The CODE statement defines the default attributes for code segments within
the application or library. The SEGMENTS statement can override this
default.
Each attribute field can appear one time at most, and order is not
significant.
Fields
load {PRELOAD | LOADONCALL}
Determines when a code segment is loaded.
PRELOAD specifies that the segment is
loaded automatically at the beginning of
the program. LOADONCALL (default)
specifies that the segment is not loaded
until accessed.
executeonly {EXECUTEONLY | EXECUTEREAD}
Determines whether a code segment can be
read as well as executed. EXECUTEONLY
specifies that the segment can only be
executed. EXECUTEREAD (default)
specifies that the segment can be both
executed and read.
iopl {IOPL | NOIOPL}
Determines whether or not a segment has
I/O privilege (OS/2 only). IOPL
specifies that the code segment has I/O
privilege. NOIOPL (default) specifies
that the code segment does not have I/O
privilege.
conforming {CONFORMING | NONCONFORMING}
Determines whether or not a code segment
is a 80286 "conforming" segment.
CONFORMING specifies that the segment is
conforming, which means it can be called
from either Ring 2 or Ring 3 and it
executes at the caller's privilege level.
NONCONFORMING (default) specifies that
the segment is
nonconforming.
shared {SHARED | NONSHARED}
Determines whether all instances of the
program can share an EXECUTEREAD code
segment. SHARED specifies that one copy
of the code segment is loaded and shared
among all processes accessing the module
(the default for dynamic-link libraries).
NONSHARED specifies that the segment
cannot be shared and must be loaded
separately for each process (the default
for applications).
movable {MOVABLE | FIXED}
Determines whether a segment can be
moved around in memory. For use with
real-mode Windows only. FIXED is the
default.
discard {DISCARDABLE | NONDISCARDABLE}
Determines whether a segment of memory
can be discarded to fill a different
memory request. If the discarded memory
contains a function that is called later,
it is reloaded from disk. For use with
real-mode Windows only. NONDISCARDABLE
is the default.
DATA Statement
Summary
The DATA statement defines the default attributes for the data segments
within the application or module.
Syntax
DATA «load» «readonly» «instance» «iopl» «shared» «movable» «discard»
Each field attribute can appear one time at most, and order is not
significant.
Fields
load {PRELOAD | LOADONCALL}
Determines when a code segment is loaded.
PRELOAD specifies that the segment is
loaded automatically at the beginning of
the program. LOADONCALL (default)
specifies that the segment is not loaded
until accessed.
readonly {READONLY | READWRITE}
Determines access rights to a data
segment. READONLY specifies that the
segment can only be read. READWRITE
(default) specifies that the segment can
be both read and
written to.
instance {NONE | SINGLE | MULTIPLE}
Affects the sharing attributes of the
automatic data segment represented by
the group name DGROUP. NONE specifies
that no automatic data segment is
created. SINGLE specifies that a single
automatic data segment is shared by all
instances of the module (default for
dynamic-link libraries). MULTIPLE
specifies that the automatic data
segment is copied for each instance of
the module (default for applications).
iopl {IOPL | NOIOPL}
Determines whether or not a segment has
I/O privilege (OS/2 only). IOPL
specifies that the code segment has I/O
privilege. NOIOPL (default) specifies
that the code segment does not have I/O
privilege.
shared {SHARED | NONSHARED}
Determines whether all instances of the
program can share an EXECUTEREAD code
segment. SHARED specifies that one copy
of the code segment is loaded and shared
among all processes accessing the module
(the default for dynamic-link libraries).
NONSHARED specifies that the segment
cannot be shared and must be loaded
separately for each process (the default
for applications).
movable {MOVABLE | FIXED}
Determines whether a segment can be
moved around in memory. For use with
real-mode Windows only. FIXED is the
default.
discard {DISCARDABLE | NONDISCARDABLE}
Determines whether a segment of memory
can be discarded when not needed. If the
discarded memory contains data that is
accessed later, it is reloaded from disk.
For use with real-mode Windows only.
NONDISCARDABLE is the default.
SEGMENTS Statement
Summary
The SEGMENTS statement defines the attributes of one or more segments in the
application or library on a segment-by-segment basis. The attributes
specified by this statement override defaults set in CODE and DATA
statements.
The SEGMENTS keyword marks the beginning of the segment definitions. This
keyword can be followed by one or more segment definitions, each on a
separate line (limited by the number set by the linker's /SEGMENTS option,
or 128 if the option is not used). The CLASS keyword specifies the class of
the segment.
Fields
load {PRELOAD | LOADONCALL}
Determines when a code segment is loaded.
PRELOAD specifies that the segment is
loaded automatically at the beginning of
the program. LOADONCALL (default)
specifies that the segment is not loaded
until accessed.
readonly {READONLY | READWRITE}
Determines access rights to a data
segment. READONLY specifies that the
segment can only be read. READWRITE
(default) specifies that the segment can
be both read and
written to.
executeonly {EXECUTEONLY | EXECUTEREAD}
Determines whether a code segment can be
read as well as executed. EXECUTEONLY
specifies that the segment can only be
executed. EXECUTEREAD (default)
specifies that the segment can be both
executed and read.
iopl {IOPL | NOIOPL}
Determines whether or not a segment has
I/O privilege (OS/2 only). IOPL
specifies that the code segment has I/O
privilege. NOIOPL (default) specifies
that the code segment does not have I/O
privilege.
conforming {CONFORMING | NONCONFORMING}
Determines whether or not a code segment
is a 80286 "conforming" segment.
CONFORMING specifies that the segment is
conforming, which means it can be called
from either Ring 2 or Ring 3 and it
executes at the caller's privilege level.
NONCONFORMING (default) specifies that
the segment is
nonconforming.
shared {SHARED | NONSHARED}
Determines whether all instances of the
program can share an EXECUTEREAD code
segment. SHARED specifies that one copy
of the code segment is loaded and shared
among all processes accessing the module
(the default for dynamic-link libraries).
NONSHARED specifies that the segment
cannot be shared and must be loaded
separately for each process (default for
applications).
movable {MOVABLE | FIXED}
Determines whether a segment can be
moved around in memory. For use with
real-mode Windows only. FIXED is the
default.
discard {DISCARDABLE | NONDISCARDABLE}
Determines whether a segment of memory
can be discarded to fill a different
memory request. If the discarded memory
contains a function that is called later,
it is reloaded from disk. For use with
real-mode Windows only. NONDISCARDABLE
is the default.
STACKSIZE Statement
Summary
The STACKSIZE statement specifies the size of the stack segment. (The
STACKSIZE statement overrides the /STACKSIZE linker option.)
Syntax
STACKSIZE number
The number must be an integer; it is considered to be in decimal format by
default, but C notation can be used to specify hexadecimal or octal format.
EXPORTS Statement
Summary
The EXPORTS statement declares the names and attributes of the functions
exported to other modules and the functions that run with I/O privilege. The
EXPORTS statement also declares Windows callback functions such as dialog
boxes and timer functions. It is unnecessary to export callback functions
within an OS/2 Presentation Manager program.
The EXPORTS keyword marks the beginning of the export definitions. It can be
followed by up to 3,072 export definitions, each on a separate line.
The optional keyword NODATA is ignored by OS/2, but is provided for use by
real-mode Windows. It means there is no static data in the function.
Fields
entryname Defines the function name as known to
other modules.
internalname Defines the actual export function name
as it appears within the module. Default
is the same as entryname.
ord Defines the function's ordinal position
within the moduledefinition table. Can
contain the optional keyword
RESIDENTNAME, which specifies that the
function name
be kept resident in memory at all times.
pwords Specifies the total size of the
function's parameters in words.
IMPORTS Statement
Summary
The IMPORTS statement defines the names of the functions to be imported for
the application or library.
Syntax
IMPORTS «internalname=»modulename.entry
The IMPORTS keyword marks the beginning of the import definitions. This
keyword is followed by one or more import definitions, each on a separate
line. Note that if you supply an import library, you need not list the
individual functions.
Fields
internalname Specifies the name that the importing
module actually uses to call the
function. By default, internalname is
the same as the name given in entry.
modulename Name of the application or library
containing the function.
entry Determines the function to be imported
and can be a name or an ordinal value.
STUB Statement
Summary
The STUB statement adds a DOS executable file to the beginning of the
application or library being created. Typically, the stub displays a message
and terminates execution.
Syntax
STUB 'filename'
The filename specifies the DOS executable file to be added. If the linker
does not find filename in the current directory, it searches in the list of
directories specified in the PATH environment variable.
HEAPSIZE Statement
Summary
The HEAPSIZE statement defines the size of the application's local heap in
bytes. This value affects the size of the automatic data segment.
Syntax
HEAPSIZE {bytes | MAXVAL}
The bytes field is a decimal integer value by default. However, hexadecimal
and octal numbers can be entered by using C notation. MAXVAL is an optional
keyword which can be substituted for bytes to set the field parameter.
MAXVAL sets the heap size to 64K minus the size of DGROUP.
PROTMODE Statement
Summary
The optional PROTMODE statement specifies that the module runs only in
protected mode and not in Windows or dual mode.
Syntax
PROTMODE
OLD Statement
Summary
The OLD statement directs the linker to search another dynamic-link module
for export ordinals.
Syntax
OLD 'filename'
REALMODE Statement
Summary
The REALMODE statement specifies that the application runs only in real
mode.
Syntax
REALMODE
EXETYPE Statement
Summary
The optional EXETYPE statement specifies in which operating system the
application (or dynamic-link library) is to run.
The NMAKE utility automates the process of compiling and linking project
files. NMAKE is upwardly compatible with the older MAKE utility if the /MAKE
option is used.
Syntax
NMAKE «options» «macrodefinitions» «targets»
Options
/A Executes commands to build all the
targets requested even if they are not
out-of-date.
/C Suppresses the NMAKE copyright message
and prevents nonfatal error or warning
messages from being displayed.
/D Displays the modification date of each
file when the date is checked.
/E Causes environment variables to override
macro definitions within description
files.
/F filename Specifies filename as the name of the
description file to use. If a dash (-)
is entered instead of a file name, NMAKE
accepts input from the standard input
device instead of using a description
file. If /F is not specified, NMAKE uses
MAKEFILE as the description file.
/HELP Calls the QuickHelp utility. If the
QuickHelp program is not available,
NMAKE displays the most commonly used
NMAKE options to the standard output.
/I Ignores exit codes (also called return
or error codes) returned by programs
called from the NMAKE description file.
NMAKE continues executing the rest of
the description file despite the errors.
/N Displays the commands from the
description file that NMAKE would
execute, but does not execute these
commands. This option is useful for
checking which targets are out-of-date
and for debugging description files.
/NOLOGO Suppresses the sign-on banner when NMAKE
executes.
/P Prints all macro definitions and target
descriptions.
/Q Returns a zero exit code if the target
is up-to-date and a nonzero exit code if
it is not. This option is useful when
invoking NMAKE from within a batch file.
/R Ignores inference rules and macros
contained in the TOOLS.INI file.
/S Suppresses display of commands as they
are executed.
/T Changes the modification dates for
outdated target files to the current
date. The file contents are not modified.
/X filename Sends all error output to filename,
which can be either a file or a device.
If a dash is entered instead of a file
name, the error output is sent to the
standard output device.
/Z Internal option for use by the
Programmer's WorkBench.
/? Displays a brief summary of NMAKE syntax
and exits to the operating system.
The following symbols are used in description blocks:
Symbol Meaning
────────────────────────────────────────────────────────────────────────────
# Introduces comment field
*, ? DOS wild-card characters; NMAKE expands
them in target names when it reads the
description file
^ Introduces any escape character in a
description file, including these: # ( )
$ ^ \ { } ! @
Command Modifiers
These characters can be placed in front of a command to modify its effect.
The character must be preceded by at least one space.
Character Action
────────────────────────────────────────────────────────────────────────────
- Turns off error checking for the command
@ Prevents NMAKE from displaying the
command as it executes
! Causes the command to be executed for
each dependent file if the command uses
one of the special macros $? or $**
Macros
Syntax
macroname=macrostring
The macroname can be any combination of alphanumeric characters and the
underscore (_) character. The macrostring can be any valid string.
Having defined the macro, use the following reference to include it in a
dependency line or command:
$(macroname)
Use the following syntax to substitute text within a macro:
$(macroname:string1 = string2)
Specific Macro Names
The following macro names have specific meanings:
Macro Meaning
────────────────────────────────────────────────────────────────────────────
$* The target's base name with the
extension deleted.
$@ The full name of the current target.
$** The complete list of dependent files.
$< The dependent file that is out-of-date
with respect to the target (evaluated
only for inference rules).
$? The list of dependents that are
out-of-date with respect to the target.
$$@ The target that NMAKE is currently
evaluating. A dynamic dependency
parameter used only in dependency lines.
$(CC) The command to invoke the C compiler. By
default, NMAKE predefines this macro as
CC = cl.
$(AS) The command that invokes the Microsoft
Macro Assembler. NMAKE predefines this
macro as AS = masm.
$(MAKE) The name with which NMAKE is invoked.
Used to invoke NMAKE recursively. It
causes the line on which it appears to
be executed even if the /N option is on.
Redefine this macro if you want to
execute another program.
$(MAKEDIR) The directory from which NMAKE was
invoked.
$(MAKEFLAGS) The NMAKE options currently in effect.
If you invoke NMAKE recursively, use the
command $(MAKE)
$(MAKEFLAGS). You cannot redefine this
macro.
Inference Rules
Inference rules are templates that NMAKE uses to generate files with a given
extension.
The following directives conditionally execute commands, display error
messages, include the contents of other files, and turn on or off some of
NMAKE's options.
Directive Description
────────────────────────────────────────────────────────────────────────────
!IF expression Executes the statements between the !IF
keyword and the next !ELSE or !ENDIF
directive if expression evaluates to a
nonzero value. The expression consists
of integer constants, string constants,
or program invocations. Integer
constants can use the C unary operators
for numerical negation (-), one's
complement (~), and logical negation (!),
and can also use the C binary operators
(+, -, *, /, %, &, |, ^, &&, ||, <<, >>,
==, !=, <, >, <=, and >=).
!ELSE Executes the statements between the
!ELSE and !ENDIF directives if the
statements preceding the !ELSE directive
were not executed.
!ENDIF Marks the end of the !IF, !IFDEF, or
!IFNDEF block of statements.
!IFDEF macroname Executes the statements between the
!IFDEF keyword and the next !ELSE or
!ENDIF directive if macroname is defined
in the description file. NMAKE considers
a macro with a null value to be defined.
!IFNDEF macroname Executes the statements between the
!IFNDEF keyword and the next !ELSE or
!ENDIF directive if macroname is not
defined in the description file.
!UNDEF macroname Marks macroname as being undefined in
NMAKE's symbol table.
!ERROR text Causes text to be printed, and then
stops
execution.
!INCLUDE filename Reads and evaluates the file filename
before continuing with the current
description file. If filename is
enclosed by angle brackets (< >), NMAKE
searches for the file in the directories
specified by the
INCLUDE macro; otherwise it looks in the
current directory only. The INCLUDE
macro is initially set to the value of
the
INCLUDE environment variable.
!CMDSWITCHES {+ | -}opt Turns on or off one of four NMAKE
options: /D, /I, /N, and /S. If no
options are specified, the options are
reset to the way they were when NMAKE
was started. Turn an option on by
preceding it with a plus sign (+), or
turn it off by preceding it with a minus
sign (-). Using this directive updates
the MAKEFLAGS macro.
Pseudotargets
A "pseudotarget" is not a file. It is a name that serves as a handle for
building a group of files or executing a group of commands. The NMAKE
utility includes these four predefined pseudotargets that provide special
rules within a description file.
Pseudotarget Action
────────────────────────────────────────────────────────────────────────────
SILENT : Does not display lines as they are
executed. Has same effect as invoking
NMAKE with the /S option.
IGNORE : Ignores exit codes returned by programs
called from the description file. Has
the same effect as invoking NMAKE with
the /I option.
SUFFIXES : extensions... Lists file suffixes for NMAKE to try if
it needs to build a target file for
which no dependents are specified.
PRECIOUS : targets... Tells NMAKE not to delete a target if
the commands that build it are
interrupted. Overrides the NMAKE default.
The Programmer's WorkBench (PWB) provides an integrated environment for
developing programs in C. It runs under OS/2 1.1 and DOS 3.0 and above. With
PWB, you can write and edit source and other text files, define development
projects, and build applications from one or more files.
Syntax
PWB «options» «files»
Options
The options are case sensitive.
/D«init» Prevents PWB from examining
initialization files, where init is one
or more of the following characters:
T Ignore TOOLS.INI
S Ignore CURRENT.STS (implies
P)
P Ignore current program list
If the /D option does not include an
init character, all three files are
ignored.
/e cmdstr Specifies a command on start-up. The
entire string of the argument cmdstr
should be placed in double quotes if it
contains a space.
/m mark Moves the cursor to the specified mark
instead of moving it to the last known
position.
/r Specifies that PWB starts in read-only
mode. Editing of the file is not
permitted.
/t «file«/t«file » »...» Specifies that any files that follow are
temporary. If a single file is specified,
the editor attempts to load it. If
multiple files are specified, the first
file is loaded. When the Exit function
is invoked, the editor saves the current
file and loads the next file in the list.
/? Lists the command-line options available
for starting PWB.
Arguments to PWB Functions
Arg Introduces an argument or function. Type
ALT+A.
Meta Modifies the actions of a function. Type
F9.
Textarg A text argument. Type arg, then the text
to be passed to the PWB function.
Numarg A text argument consisting of characters
in the range 0-9.
Markarg A text argument holding the name of a
bookmark defined by the Mark function.
Linearg When PWB is in line mode, entire lines
of text are manipulated (deleted, moved,
and so on). To select a range of lines,
hold down the SHIFT key while moving the
cursor.
Streamarg When PWB is in stream mode, the text is
treated as a stream of characters. Any
stream of characters can be manipulated.
Boxarg When PWB is in box mode, columns of text
(boxes) can be manipulated.
Categories of PWB Functions
Command Manipulation
FunctionDefault Description
CancelESCCancels the current operation
GraphicMost KeysInserts the ASCII value of the key into the file
LastselectCTRL+URecalls the last cursor-movement argument
LasttextCTRL+ORecalls the last textarg entered
QuoteCTRL+PTreats the next keystroke literally
Repeat─Repeats the previous command
UndoALT+BKSPReverses the effect of the last editing change
File Operation
FunctionDefaultDescription
ExitF8Exits the editor,, with or without saving
Noedit─Toggles the no-edit restriction
RefreshSHIFT+F7Rereads the file,, discarding edits
Saveall─Saves all modified files
SetfileF2Saves the current file or loads a new file
Cursor Movement
FunctionDefaultDescription
BacktabSHIFT+TABMoves the cursor left to the previous tab stop
BegfileCTRL+HOMEMoves the cursor to the beginning of file
BeglineHOMEMoves the cursor left to the beginning of the line
DownDOWNMoves the cursor down one line
EndfileCTRL+ENDMoves the cursor to the end of the file
EndlineENDMoves the cursor to the right of the last character of the line
HomeNUM 5Moves the cursor to the upper-left corner of the window
LeftLEFTMoves the cursor left by one character
MpagePGUPMoves the cursor back by one page
Mpara─Moves the cursor back by paragraphs
MwordCTRL+LEFTMoves the cursor back by words
Newline─Moves the cursor down to the next line
PpagePGDNMoves the cursor forward by one page
Ppara─Moves the cursor forward by paragraphs
PwordCTRL+RIGHTMoves the cursor forward by words
RightRIGHTMoves the cursor right by one character
TabTABMoves the cursor right to the next tab stop
UpUPMoves the cursor up one line
Mark/Goto Position
FunctionDefaultDescription
MarkCTRL+MMoves the cursor to the specified position in the file
Restcur─Restores the cursor position saved with Savecur
Savecur─Saves the cursor position for use with Restcur
Windows
FunctionDefaultDescription
MaximizeCTRL+F10Expands the window to its maximum size
MlinesCTRL+WMoves the window back by lines
PlinesCTRL+ZMoves the window forward by lines
ResizeCTRL+F8Enlarges or shrinks the active window
SetwindowCTRL+]Redisplays the window
WindowF6Creates, removes, or moves between windows
Search/Replace
FunctionDefaultDescription
Mgrep─Searches a series of files
Mreplace─Replaces throughout a series of files
MsearchF4Searches backward
PsearchF3Searches forward
QreplaceCTRL+\Replaces with confirmation
ReplaceCTRL+LReplaces without confirmation
Searchall─Highlights all occurrences of a string
Special Insert
FunctionDefaultDescription
Curdate─Inserts the current date (example: 28-Nov-1990)
Curday─Inserts the current day (example: Sun)
Curfile─Inserts the name of the current file
Curfileext─Inserts the extension of the current file
Curfilenam─Inserts the base name of the current file
Curtime─Inserts the current time (example: 13:45:55)
Insert/Delete
FunctionDefaultDescription
CdeleteCTRL+GDeletes the character to the left, excluding line breaks
CopyCTRL+INSCopies the lines to the Clipboard
DeleteDELDeletes the highlighted area
EmacscdelBKSPDeletes the character to the left, including line breaks
EmacsnewlENTERStarts a new line, breaking the current line
Insert─Inserts spaces into the highlighted area
InsertmodeINSToggles insert mode on and off
LdeleteCTRL+YDeletes lines to the Clipboard
LinsertCTRL+NInserts blank lines
PasteSHIFT+INSInserts text from the Clipboard
Sdelete─Deletes a stream of text, including the line breaks
SinsertCTRL+JInserts blanks, breaking lines if necessary
Programming
FunctionDefaultDescription
CompileCTRL+F3Executes the compile or build command
NextmsgSHIFT+F3Moves the cursor to the next error message
PbalCTRL+[Balances the parentheses and the brackets
Macro Creation
FunctionDefaultDescription
AssignALT+=Defines macros and sets switches
ExecuteF7Executes a series of editor or macro commands
Message─Displays a message on the dialog line
RecordSHIFT+CTRL+RTurns macro recording on or off
TellCTRL+TDisplays an assignment or macro definition
Usercmd─Executes a command added to the PWB Run menu
Help
FunctionDefaultDescription
Pwbhelp─Displays Microsoft Advisor help screens
PwbhelpnextCTRL+F1Displays the next physical topic in Microsoft Advisor
SethelpSHIFT+CTRL+SAdds or deletes single help files
Miscellaneous
FunctionDefaultDescription
Environment─Displays or modifies environment settings
InformationSHIFT+F10Displays a list of previously edited files
InitializeSHIFT+F8Rereads the initialization file
Print─Prints all or part of a file
ShellSHIFT+F9Spawns a command-line shell
PWB Functions
The PWB functions and the syntax for each are listed alphabetically below.
Default keystrokes, if available, are given in parentheses.
╓┌─────────────────────────────┌────────────────────────┌────────────────────►
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg Arg Introduces a function
(ALT+A) argument for a functio
Assign Assign Treats the entire line
(ALT+=) the line break) on whi
is positioned as a fun
assignment or macro de
Arg Assign Treats the text from t
cursor position to the
line (not including th
as a function assignme
definition.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg boxarg Assign Treats each line of th
an individual function
or macro definition. I
lines and
comment lines.
Arg linearg Assign Treats each line as a
function assignment or
definition, ignoring b
and comment lines.
Arg textarg Assign Treats textarg as a fu
assignment or macro de
Arg ? Assign Displays the current f
assignments for all fu
macros.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
macros.
Backtab Backtab Moves the cursor to th
(SHIFT+TAB) tab stop. Tab stops ar
be every nth character
defined by the tabstop
Begfile Begfile Places the cursor at t
(CTRL+HOME) of the file.
Begline Begline Places the cursor on t
(HOME) nonblank character on
Meta Begline Places the cursor in t
character position of
Cancel Cancel Cancels the current op
(ESC) an operation is in pro
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
(ESC) an operation is in pro
canceled. If there is
but a message is on th
the dialog line is res
help window is open, t
closes it.
Cdelete Cdelete Deletes the previous c
(CTRL+G) excluding line breaks.
cursor is in column 1,
moves the cursor to th
previous line. If issu
mode,
Cdelete deletes the pr
character,
reducing the length of
1; otherwise, it delet
previous character and
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
previous character and
with a blank. If the c
beyond the end of the
function is invoked, t
moved to the immediate
last character on
the line.
Compile Compile Displays the status of
(CTRL+F3) compilation (if any) o
line.
Arg Compile Compiles and links the
Uses the extmake comma
matches the file-name
the current file.
Arg textarg Compile Uses the command line
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg textarg Compile Uses the command line
extmake:text. The text
%s in the command line
Arg Arg textarg Compile Invokes the specified
program. Assumed to di
errors in the format
file row column messag
Arg Meta Compile OS/2 only. Halts a pro
compilation running in
background after promp
confirmation.
Copy Copy Copies the current lin
(CTRL+INS) Clipboard.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg Copy Copies text from the i
position to the end of
places it in the Clipb
the line break.
Arg markarg Copy Copies the range of te
the cursor and the loc
file marker to the Cli
stream mode, a stream
selected. In box mode,
treated as a boxarg or
depending on the relat
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
depending on the relat
of the initial cursor
the file marker. In li
lines between the curs
file marker are copied
Arg numarg Copy Copies the specified n
lines to the Clipboard
with the current line.
Curdate Curdate Inserts the current da
cursor in the format o
Curday Curday Inserts the current da
cursor in the format o
Curfile Curfile Inserts the fully qual
name of the current fi
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
name of the current fi
cursor.
Curfileext Curfileext Inserts the extension
current file at the cu
Curfilenam Curfilenam Inserts the base name
current file at the cu
Curtime Curtime Inserts the current ti
cursor in the format o
Delete Delete Deletes the single cha
(DEL) the cursor, excluding
SHIFT+DEL places the d
character in the Clipb
deletes without copyin
to the Clipboard.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
to the Clipboard.
Arg Delete Deletes all text from
cursor position to the
line. The deleted text
the line break) is pla
Clipboard. This comman
effect of joining line
Arg boxarg Delete Deletes the highlighte
Arg linearg Delete deleted text is placed
Arg streamarg Delete Clipboard.
Arg Meta Delete Performs the deletions
Arg boxarg Meta Delete above, except the dele
Arg linearg Meta Delete not placed in the Clip
Arg streamarg Meta
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg streamarg Meta
Delete
Meta Delete Deletes the current ch
current selection. The
is not copied to the C
Down Down Moves the cursor down
(DOWN or CTRL+X) the cursor moves out o
the window is adjusted
the number of lines sp
the vscroll switch.
Meta Down Moves the cursor to th
the window without cha
column position.
Emacscdel Emacscdel Performs similarly to
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Emacscdel Emacscdel Performs similarly to
(BKSP) except that at the beg
line while in insert m
Emacscdel deletes the
between the current li
previous line, joining
lines together.
Emacsnewl Emacsnewl Performs similarly to
(ENTER) except that when in in
breaks the current lin
cursor position.
Endfile Endfile Places the cursor at t
(CTRL+END) file.
Endline Endline Moves the cursor to th
(END) right of the last nonb
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
(END) right of the last nonb
character on the line.
Meta Endline Moves the cursor one c
beyond the column corr
the rightmost edge of
Environment Environment Executes the current l
environment-variable s
Arg boxarg Environment Executes each highligh
Arg linearg Environment line fragment as an
environment-variable s
Arg textarg Environment Executes the text argu
environment-variable s
Arg ? Environment Displays all current
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg ? Environment Displays all current
environment-variable s
Meta Environment Performs environment "
all environment variab
the current line, when
variable appears in th
syntax:
$(environment-variable
or
$(environ:)
For each such environm
appearing on the line,
the variable with the
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
the variable with the
setting.
Arg Meta Environment Performs environment m
description above) for
from the cursor positi
of the line.
Arg linearg Meta Performs environment m
Environment Arg boxarg description above) for
Meta highlighted text.
Environment Arg
streamarg Meta
Environment
Execute Execute Executes a PWB functio
(F7) macrolist.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg Execute Treats the line from t
cursor position to the
series of PWB commands
executes them.
Arg linearg Execute Treats the specified t
Arg textarg Execute commands and executes
following the standard
macro execution.
Exit Exit Exits PWB. If the auto
(F8) is set
to yes, the file in me
automatically saved. I
files are specified on
line, PWB proceeds to
file.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
file.
Meta Exit Performs similarly to
that the current file
Arg Exit Performs similarly to
that if multiple files
specified on the comma
exits without advancin
file.
Arg Meta Exit Performs similarly to
except that PWB does n
current file.
Graphic Graphic Inserts the ASCII valu
( ' ) specified key into the
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Home Home Places the cursor in t
(Keypad 5) corner of the current
Information Information Loads an information f
(SHIFT+F10) contains a list of all
memory along with the
of files that you have
size of this list is c
the tmpsav switch, whi
default value of 20.
Initialize Initialize Reads all the editor s
(SHIFT+F8) from the [PWB] section
Arg Initialize Reads the editor state
the TOOLS.INI file, us
continuous string of n
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
continuous string of n
characters, starting w
initial cursor positio
name.
Arg textarg Initialize Reads all the editor s
from the [PWB-textarg]
TOOLS.INI.
Insert Insert Inserts a single blank
current cursor positio
Arg Insert Inserts a carriage ret
initial cursor positio
the line.
Insertmode Insertmode Toggles between insert
(INS or CTRL+V) overtype mode.
Lastselect Lastselect Recalls the last curso
(CTRL+U) argument. This functio
the same result as ret
last Arg position, inv
function, and then rec
last cursor-movement a
Lasttext Lasttext Recalls the last texta
(CTRL+O) function produces the
as typing arg once and
retyping the previous
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Ldelete Ldelete Deletes the current li
(CTRL+Y) it in the Clipboard.
Arg Ldelete Deletes text, starting
initial cursor positio
end of the line, and p
the Clipboard. Note th
not join the current l
next line.
Arg boxarg Ldelete Deletes the specified
Arg linearg Ldelete file and places it in
treating the argument
or boxarg regardless o
PWB is in.
Left Left Moves the cursor one c
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Left Left Moves the cursor one c
(LEFT or CTRL+S) the left. If this resu
cursor moving out of t
the window is adjusted
by the number of colum
by the hscroll switch.
Meta Left Moves the cursor to th
position in the window
line.
Linsert Linsert Inserts one blank line
(CTRL+N) current line.
Arg Linsert Inserts or deletes bla
beginning of a line to
first nonblank charact
under the cursor.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
under the cursor.
Arg boxarg Linsert Fills the specified ar
Arg linearg Linsert blanks, treating the a
linearg or boxarg rega
what mode PWB is in.
Mark Mark Moves the cursor to th
(CTRL+M) of
the file.
Arg Mark Restores the cursor to
location. PWB remember
location prior to the
movement.
Arg numarg Mark Moves the cursor to th
of the specified line,
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
of the specified line,
specifies the line num
file.
Arg textarg Mark Moves the cursor to th
file marker.
Arg Arg textarg Mark Defines a file marker
initial cursor positio
markfile switch contai
name for saving marks,
be added to the file w
PWB.
Arg Arg textarg Meta Deletes a marker defin
Mark
Maximize Maximize Expands the window to
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Maximize Maximize Expands the window to
(CTRL+F10) size.
Meta Maximize Restores the window to
size.
Message Message Clears the dialog line
Arg textarg Message Prints the text argume
dialog line.
Meta Message Forces a screen update
Meta Meta Modifies the action of
(F9) it is used with. Refer
individual functions f
information.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Mgrep Mgrep Searches for the previ
string or pattern. PWB
files listed in the mg
Arg Mgrep Searches files for the
defined as the charact
initial cursor positio
first blank character.
Arg textarg Mgrep Searches files for the
text.
Arg Arg Mgrep Searches files for the
expression defined as
characters from the in
position to the first
character.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
character.
Arg Arg textarg Mgrep Searches files for a r
expression as defined
Meta Mgrep Performs similarly to
Arg Meta Mgrep form above, except tha
Arg textarg Meta Mgrep of the case switch is
Arg Arg Meta Mgrep reversed.
Arg Arg textarg Meta
Mgrep
Mlines Mlines Moves the window back
(CTRL+W) of lines specified by
switch.
Arg Mlines Moves the window until
that the cursor is on
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
that the cursor is on
bottom of the window.
Arg numarg Mlines Moves the window back
specified number of li
Mpage Mpage Moves backward in the
(PGUP or CTRL+R) window.
Mpara Mpara Moves the cursor to th
line preceding the cur
paragraph.
Meta Mpara Moves the cursor to th
previous line that has
Mreplace Mreplace Performs a search-and-
across multiple files,
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
across multiple files,
for the search and rep
strings, and prompting
occurrence for confirm
function searches all
in the mgreplist macro
Arg Arg Mreplace Performs the same acti
Mreplace, but uses
regular-expression syn
Msearch Msearch Searches backward for
(F4) previously defined str
pattern. If the string
is found, the window i
display it and the mat
or pattern is highligh
match is found, no cur
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
match is found, no cur
takes place and a mess
displayed.
Arg Msearch Searches backward in t
the string defined as
characters from the in
position to the first
character.
Arg streamarg Msearch Searches backward for
Arg textarg Msearch text.
Arg Arg Msearch Searches backward in t
the regular expression
the characters from th
cursor position to the
character.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
character.
Arg Arg textarg Msearch Searches backward for
expression as defined
Meta Msearch Performs similarly to
Arg Meta Msearch form above, except tha
Arg textarg Meta of the case switch is
Msearch reversed.
Arg Arg Meta Msearch
Arg Arg textarg Meta
Msearch
Mword Mword Moves the cursor to th
(CTRL+LEFT of the current word. I
or CTRL+A) is not currently in a
at the first character
the beginning of the p
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
the beginning of the p
Meta Mword Moves the cursor to th
right of the previous
Newline Newline Moves the cursor to a
(SHIFT+ENTER) tries to place the cur
appropriate position b
type of file. If the f
program and the softcr
set, PWB tries to tab
based on continuation
open blocks. If the ne
blank, PWB places the
the column correspondi
first
nonblank character of
line. If neither of th
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
line. If neither of th
true, PWB places the
first nonblank charact
line.
Meta Newline Moves the cursor to co
next line.
Nextmsg Nextmsg Advances to the next e
(SHIFT+F3)
Arg numarg Nextmsg Moves forward or backw
error messages. A numa
moves to the next mess
of -1 moves back to th
message.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Arg Nextmsg Moves to the next erro
(within the current se
that does not refer to
file.
Arg Arg Nextmsg Positions the text-fil
the line with the erro
in the error message a
cursor position in the
pseudofile. This messa
the current error mess
equivalent of Nextmsg
arguments is executed.
following Nextmsg comm
the next error message
<compile> pseudofile.
Function Syntax Description
(Default)
─────────────────────────────────────────────────────────────────────────────
Meta Nextmsg OS/2 only. Advance to
of error messages, in
corresponds to all the
messages for a single
After this command is
previous set is delete
can still view all sub
of error messages in t
pseudofile until it is
deleted).
PWB Functions (continued)
╓┌────────────────────────────┌─────────────────────────────┌────────────────►
Function (Default) Syntax Description
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Noedit Noedit Reverses the no-ed
condition, so that
was started with t
(read-only) option
command removes th
limitation. If PWB
the no-edit state,
command disallows
editing commands t
a file.
Meta Noedit Reverses the no-ed
condition for the
file.
Paste Paste Inserts the conten
(SHIFT+INS) Clipboard above th
line if the conten
placed there in a
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
placed there in a
line-oriented way,
with linearg or nu
Otherwise, inserts
contents of the Cl
the current cursor
Arg streamarg Paste Replaces the speci
Arg linearg Paste with the contents
Arg boxarg Paste Clipboard.
Arg Paste Inserts the text f
initial cursor pos
the end of the lin
initial cursor pos
Arg textarg Paste Places the specifi
the Clipboard and
that text at the i
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
that text at the i
cursor position.
Arg Arg textarg Paste Interprets textarg
name and inserts t
contents of that f
the current file a
current line.
Arg Arg !textarg Paste Treats the text as
OS/2 command and i
output to stdout i
current file at th
cursor position.
Pbal Pbal Scans backward thr
(CTRL+[) file, balancing pa
and brackets. The
unbalanced one is
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
unbalanced one is
highlighted when f
it is found and is
visible, PWB displ
matching line on t
line, with the hig
matching character
corresponding char
placed into the fi
current cursor pos
Note that the sear
not include the cu
cursor position an
scan looks only fo
left brackets or p
than right, not ju
unequal number.
Arg Pbal Performs similarly
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Pbal Performs similarly
except that it sca
in the file and lo
more right bracket
parentheses than l
Meta Pbal Performs similarly
except that the fi
updated.
Arg Meta Pbal Performs similarly
Pbal, except that
is not updated.
Plines Plines Adjusts the cursor
(CTRL+Z) by the number of l
specified by the v
switch.
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Plines Moves the cursor d
the line that the
on is at the top o
window.
Arg numarg Plines Moves the cursor f
specified number o
Ppage Ppage Moves forward in t
(PGDN or one window.
CTRL+C)
Ppara Ppara Moves the cursor f
paragraph and plac
cursor on the firs
the new paragraph.
Meta Ppara Moves the cursor t
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Meta Ppara Moves the cursor t
first blank line f
the current paragr
Print Print Prints the current
the printcmd switc
this function uses
system-level comma
in the switch. Oth
the function copie
to LPT1.
Arg textarg Print Prints all the fil
in the text argume
names should be se
with a space. Macr
lists are allowed.
Arg linearg Print Prints the highlig
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg linearg Print Prints the highlig
Arg boxarg Print
Arg streamarg Print
Prompt Prompt Allows macros to p
text arguments.
Arg Prompt Uses the text from
cursor to the end
line as the prompt
Arg textarg Prompt Uses the specified
argument as the pr
Arg linearg Prompt Uses the selected
Arg boxarg Prompt the first line of
Arg streamarg Prompt selected area as t
Meta Prompt Uses the selected
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Meta Prompt Uses the selected
the first line of
selected area as t
and passes it to t
function.
Psearch Psearch Searches forward f
(F3) previously defined
pattern. If the st
pattern is found,
is moved to displa
the matched string
pattern is highlig
it is not found, t
does not move and
is displayed.
Arg Psearch Searches forward i
for the string def
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
for the string def
the characters fro
initial cursor pos
the first blank ch
Arg textarg Psearch Searches forward f
specified text.
Arg Arg Psearch Searches forward i
for the regular ex
defined as the cha
from the initial c
position to the fi
character.
Arg Arg textarg Psearch Searches forward f
regular expression
defined by textarg
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Meta Psearch Performs similarly
Arg Meta Psearch command form above
Arg textarg Meta Psearch that the value of
Arg Arg Meta Psearch switch is temporar
Arg Arg textarg Meta reversed.
Psearch
Pwbhelp Pwbhelp Microsoft Advisor
screens.
Arg Pwbhelp Displays help on t
at the cursor posi
Arg Displays help on t
single-line-cursor-movement argument highlight
Pwbhelp screen.
Arg textarg Pwbhelp Displays help on t
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg textarg Pwbhelp Displays help on t
specified text arg
Meta Pwbhelp Prompts the user f
keystroke and disp
on the function as
with that keystrok
this command to wo
cursor cannot be r
a help topic.
Pwbhelpnext Pwbhelpnext Displays the next
(CTRL+F1) topic in the
Microsoft Advisor
system.
Meta Pwbhelpnext Displays the previ
topic on the backt
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Pwbhelpnext Displays the next
of the current hel
within the Microso
help system.
Pword Pword Moves the cursor f
(CTRL+RIGHT the beginning of t
or CTRL+F) word.
Meta Pword Moves the cursor t
immediate right of
current word or, i
cursor is not in a
the right of the n
Qreplace Qreplace Performs a
(CTRL+\) search-and-replace
prompting for the
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
prompting for the
replacement string
prompting at each
for confirmation.
begins at the curs
position and conti
through the end of
Arg boxarg Qreplace Performs the
Arg linearg Qreplace search-and-replace
Arg streamarg Qreplace the highlighted ar
prompting at each
for confirmation.
Arg markarg Qreplace Performs the
search-and-replace
the cursor positio
specified file mar
prompting at each
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
prompting at each
for confirmation.
Arg numarg Qreplace Performs the
search-and-replace
specified number o
starting with the
line, prompting at
occurrence for con
Arg Arg Qreplace Performs the same
Arg Arg boxarg Qreplace corresponding comm
Arg Arg linearg Qreplace above, except that
Arg Arg streamarg Qreplace search pattern is
Arg Arg markarg Qreplace expression and the
Arg Arg numarg Qreplace replacement patter
select special tag
sections of the se
selective replacem
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
selective replacem
Quote Quote Reads one keystrok
(CTRL+P) keyboard and treat
literally.
Record Record Toggles the macro
(SHIFT+CTRL+R) When a recording i
PWB assigns all th
commands to the de
macro name RECORDV
During the recordi
name of each comma
written to the <re
pseudofile, which
placed in a window
viewed as it is dy
updated.
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg textarg Record Toggles the macro
and names the macr
Meta Record Toggles the macro
but no editing com
executed until the
is turned off.
Arg Record Performs identical
Arg Arg textarg Record corresponding comm
Arg Arg Meta Record above, but appends
commands to the en
macro.
Refresh Refresh Asks for confirmat
(SHIFT+F7) then rereads the f
disk, discarding a
since the file was
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
since the file was
saved.
Arg Refresh Asks for confirmat
then discards the
memory and from th
history. The most
edited previous fi
the current file.
Repeat Repeat Repeats the last e
command, using pre
same arguments and
condition used by
command. However,
command is execute
to the new cursor
Arg numarg Repeat Performs the last
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg numarg Repeat Performs the last
command for the nu
times specified by
Note that Repeat m
assigned to a key
execute this comma
Replace Replace Performs a
(CTRL+L) search-and-replace
confirmation, prom
the search string
replacement string
search begins at t
position and conti
through the end of
Arg markarg Replace Performs the
search-and-replace
the cursor and the
file marker.
Arg numarg Replace Performs the
search-and-replace
specified number o
starting with the
line.
Arg Arg Replace Performs the same
Arg Arg boxarg Replace corresponding comm
Arg Arg linearg Replace above, except that
Arg Arg streamarg Replace search pattern is
Arg Arg markarg Replace expression and the
Arg Arg numarg Replace replacement patter
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Arg numarg Replace replacement patter
select special tag
sections of the se
selective replacem
Resize Resize Enlarges or shrink
(CTRL+F8) active window. You
at least two windo
use this function.
Restcur Restcur Restores the curso
saved with Savecur
Right (RIGHT or CTRL+D) Right Moves the cursor o
character to the r
this would move th
off the screen, th
moves right by the
columns specified
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
columns specified
hscroll switch.
Meta Right Moves the cursor t
window's rightmost
Saveall Saveall Saves to disk all
have been altered
yet saved.
Savecur Savecur Saves the current
position. Restores
Restcur.
Sdelete Sdelete Deletes the single
under the cursor,
line breaks. It do
place the deleted
in the Clipboard.
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
in the Clipboard.
Arg Sdelete Deletes from the c
line at the point
cursor position.Th
deleted (including
break) is placed i
Clipboard.
Arg streamarg Sdelete Deletes the stream
from the initial c
position up to the
cursor position an
it in the Clipboar
regardless of the
selection mode.
Searchall Searchall Highlights all occ
of the previously
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
of the previously
string or pattern.
string exists in t
the cursor moves t
first occurrence.
Arg Searchall Highlights all occ
of the string defi
characters from th
cursor position to
blank character.
Arg textarg Searchall Highlights all occ
of the specified t
Arg Arg Searchall Highlights all occ
of the regular exp
defined as the cha
from the initial c
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
from the initial c
position to the fi
character.
Arg Arg textarg Searchall Highlights all occ
of a regular expre
defined by textarg
Meta Searchall Performs similarly
Arg Meta Searchall command above, exc
Arg textarg Meta Searchall the value of the c
Arg Arg Meta Searchall is temporarily rev
Arg Arg textarg Meta
Searchall
Selcur Selcur Selects a portion
(box, stream, or l
the current cursor
to an anchor marke
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
to an anchor marke
Savecur function.
Selmode Selmode Toggles between st
line mode, and box
Select Select In combination wit
(SHIFT+DOWN) cursor-movement ke
a box, stream, or
text to be passed
PWB function.
Setfile Setfile Switches to the pr
(F2) edited file, savin
any changes made t
current file if th
switch is set to y
Arg Setfile Switches to the fi
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Setfile Switches to the fi
under the cursor b
at the initial cur
position.
Arg textarg Setfile Switches to the fi
specified by texta
text argument is a
directory, PWB cha
current drive or d
Meta Setfile Performs similarly
Arg Meta Setfile corresponding comm
Arg textarg Meta Setfile above, but does no
changes made to th
file.
Arg Arg textarg Setfile Saves the current
the name specified
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
the name specified
textarg.
Arg Arg Setfile Saves the current
Sethelp Sethelp Adds or deletes in
(SHIFT+CTRL+S) help files from th
files PWB searches
on-line help. Unli
helpfiles switch,
lists the complete
help files to be u
Sethelp adds or re
individual files f
help-file list wit
affecting the rest
list. Sethelp affe
the current PWB se
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
Arg Sethelp Adds the file name
current cursor pos
the list of help f
searched.
Arg streamarg Sethelp Adds the highlight
name to the list o
searched.
Arg textarg Sethelp Adds the file name
by textarg to the
help files searche
Arg ? Sethelp Lists all currentl
help files.
Arg Meta Sethelp Removes the file n
the current cursor
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
the current cursor
from the list of h
searched.
Arg Streamarg Meta Sethelp Removes the highli
name from the list
searched.
Arg textarg Meta Sethelp Removes the file n
specified as texta
the list of files
Setwindow Setwindow Redisplays the ent
(CTRL+])
Arg Setwindow Adjusts the window
the initial cursor
becomes the home p
(upper left corner
Function (Default) Syntax Description
─────────────────────────────────────────────────────────────────────────────
(upper left corner
Meta Setwindow Redisplays the cur
Shell Shell Saves the current
(SHIFT+F9) the autosave switc
