Microsoft C - REFERENCE ──────────────────────────────────────────────────────────────────────────── 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 ──────────────────────────────────────────────────────────────────────────── BIND CL (Compiler) CodeView CVPACK EXEHDR EXP HELPMAKE ILINK (Incremental Linker) LIB LINK (Linker) NMAKE Programmer's WorkBench QuickHelp RM UNDEL PART II Language Reference ──────────────────────────────────────────────────────────────────────────── Language Reference PART III Run-time Library Functions ──────────────────────────────────────────────────────────────────────────── Routines by Category Buffer Manipulation Character Classification and Conversion Data Conversion Directory Control File Handling Graphics Input and Output Internationalization Math Memory Allocation Process and Environment Control Searching and Sorting String Manipulation System Calls Time Variable-Length Argument Lists abort abs access acos acosl alloca _arc _arc_w _arc_wxy asctime asin asinl assert atan atanl atan2 atan2l atexit atof atoi atol _atold _bcalloc bdos _beginthread _bexpand _bfree _bfreeseg _bheapadd _bheapchk _bheapmin _bheapseg _bheapset _bheapwalk _bios_disk _bios_equiplist _bios_keybrd _bios_memsize _bios_printer _bios_serialcom _bios_timeofday _bmalloc _bmsize _brealloc bsearch cabs cabsl calloc ceil ceill _cexit _c_exit cgets _chain_intr chdir _chdrive chmod chsize _clear87 clearerr _clearscreen clock close _control87 cos cosh coshl cosl cprintf cputs creat cscanf ctime cwait dieeetomsbin difftime _disable _displaycursor div dmsbintoieee _dos_allocmem _dos_close _dos_creat _dos_creatnew dosexterr _dos_findfirst _dos_findnext _dos_freemem _dos_getdate _dos_getdiskfree _dos_getdrive _dos_getfileattr _dos_getftime _dos_gettime _dos_getvect _dos_keep _dos_open _dos_read _dos_setblock _dos_setdate _dos_setdrive _dos_setfileattr _dos_setftime _dos_settime _dos_setvect _dos_write dup dup2 ecvt _ellipse _ellipse_w _ellipse_wxy _enable _endthread eof execl execle execlp execlpe execv execve execvp execvpe exit _exit exp _expand expl fabs fabsl _fcalloc fclose fcloseall fcvt fdopen feof ferror _fexpand fflush _ffree fgetc fgetchar fgetpos fgets _fheapchk _fheapmin _fheapset _fheapwalk fieeetomsbin filelength fileno _floodfill _floodfill_w floor floorl flushall _fmalloc _fmemccpy _fmemchr _fmemcmp _fmemcpy _fmemicmp _fmemmove _fmemset fmod fmodl fmsbintoieee _fmsize fopen FP_OFF _fpreset fprintf FP_SEG fputc fputchar fputs fread _frealloc free _freect freopen frexp frexpl fscanf fseek fsetpos _fsopen fstat _fstrcat _fstrchr _fstrcmp _fstrcpy _fstrcspn _fstrdup _fstricmp _fstrlen _fstrlwr _fstrncat _fstrncmp _fstrncpy _fstrnicmp _fstrnset _fstrpbrk _fstrrchr _fstrrev _fstrset _fstrspn _fstrstr _fstrtok _fstrupr ftell ftime _fullpath fwrite gcvt _getactivepage _getarcinfo _getbkcolor getc getch getchar getche _getcolor _getcurrentposition _getcurrentposition_w getcwd _getdcwd _getdrive getenv _getfillmask _getfontinfo _getgtextextent _getgtextvector _getimage _getimage_w _getimage_wxy _getlinestyle _getphyscoord getpid _getpixel _getpixel_w gets _gettextcolor _gettextcursor _gettextposition _gettextwindow _getvideoconfig _getviewcoord _getviewcoord_w _getviewcoord_wxy _getvisualpage getw _getwindowcoord _getwritemode gmtime _grstatus halloc _harderr _hardresume _hardretn _heapadd _heapchk _heapmin _heapset _heapwalk hfree hypot hypotl _imagesize _imagesize_w _imagesize_wxy inp inpw intdos intdosx int86 int86x isalnum isalpha isascii isatty iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit itoa jn _jnl j1 _j1l j0 _j0l kbhit labs ldexp ldexpl ldiv lfind _lineto _lineto_w localeconv localtime locking log logl log10 log10l longjmp _lrotl _lrotr lsearch lseek ltoa _makepath malloc matherr _matherrl max _memavl memccpy memchr memcmp memcpy memicmp _memmax memmove memset min mkdir mktemp mktime modf modfl movedata _moveto _moveto_w _msize _ncalloc _nexpand _nfree _nheapchk _nheapmin _nheapset _nheapwalk _nmalloc _nmsize _nrealloc _nstrdup onexit open _outgtext _outmem outp outpw _outtext _pclose perror _pg_analyzechart _pg_analyzechartms _pg_analyzepie _pg_analyzescatter _pg_analyzescatterms _pg_chart _pg_chartms _pg_chartpie _pg_chartscatter _pg_chartscatterms _pg_defaultchart _pg_getchardef _pg_getpalette _pg_getstyleset _pg_hlabelchart _pg_initchart _pg_resetpalette _pg_resetstyleset _pg_setchardef _pg_setpalette _pg_setstyleset _pg_vlabelchart _pie _pie_w _pie_wxy _pipe _polygon _polygon_w _polygon_wxy _popen pow powl printf putc putch putchar putenv _putimage _putimage_w puts putw qsort raise rand read realloc _rectangle _rectangle_w _rectangle_wxy _registerfonts _remapallpalette _remappalette remove rename rewind rmdir rmtmp _rotl _rotr scanf _scrolltextwindow _searchenv segread _selectpalette _setactivepage _setbkcolor setbuf _setcliprgn _setcolor _setfillmask _setfont _setgtextvector setjmp _setlinestyle setlocale setmode _setpixel _setpixel_w _settextcolor _settextcursor _settextposition _settextrows _settextwindow setvbuf _setvideomode _setvideomoderows _setvieworg _setviewport _setvisualpage _setwindow _setwritemode signal sin sinh sinhl sinl sopen spawnl spawnle spawnlp spawnlpe spawnv spawnve spawnvp spawnvpe _splitpath sprintf sqrt sqrtl srand sscanf stackavail stat _status87 strcat strchr strcmp strcoll strcpy strcspn _strdate strdup strerror _strerror strftime stricmp strlen strlwr strncat strncmp strncpy strnicmp strnset strpbrk strrchr strrev strset strspn strstr _strtime strtod strtok strtol _strtold strtoul strupr strxfrm swab system tan tanh tanhl tanl tell tempnam time tmpfile tmpnam toascii tolower _tolower toupper _toupper tzset ultoa umask ungetc ungetch unlink _unregisterfonts utime va_arg va_end va_start vfprintf vprintf vsprintf wait _wrapon write yn _ynl y1 _y1l y0 _y0l Appendix A printf/scanf Format Specifiers Appendix B Compiler Limits and Numerical Ranges Compiler Limits Numerical Ranges Numerical Values Defined in FLOAT.H Introduction ──────────────────────────────────────────────────────────────────────────── 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. ──────────────────────────────────────────────────────────────────────────── NOTE 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 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 ──────────────────────────────────────────────────────────────────────────── BIND ──────────────────────────────────────────────────────────────────────────── Summary 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. Syntax BIND infile «implibs» «linklibs» «/O outfile» «/N@file» «/N functions» «/Mmapfile» 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. /? Displays the syntax of the BIND utility. CL (Compiler) ──────────────────────────────────────────────────────────────────────────── Summary The CL utility compiles and links one or more C source files. Syntax CL «options » « filename» ... «libraries link-options» Options /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). /Zs sourcefiles Performs a syntax check only. CodeView ──────────────────────────────────────────────────────────────────────────── Summary 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 Toggle memory window SHIFT+F3 Click Options menu Memory formats Window command Switch to output screen F4 Click View menu Output command Action Keyboard Mouse ──────────────────────────────────────────────────────────────────────────── Close window CTRL+F4 Click button in upper left corner of window Go to next Breakpoint F5 Click Left button on Go or to program end on status line Switch to next window F6 Click desired window Switch to previous SHIFT+F6 Click desired window window Execute to cursor F7 Click Right button at location on status line Trace into procedure F8 Click Left button on Trace Action Keyboard Mouse ──────────────────────────────────────────────────────────────────────────── Display previous SHIFT+F8 ─ command in history Change window size CTRL+F8 Click Left button on window border and drag Toggle Breakpoint at F9 at location Double-click Left button line with cursor at location and drag Step over procedure F10 Click Left button on Step Display next command in SHIFT+F10 ─ history Maximize window CTRL+F10 Click button in upper right corner of window Action Keyboard Mouse ──────────────────────────────────────────────────────────────────────────── 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 ──────────────────────────────────────────────────────────────────────────── Dialog Commands ╓┌────────────────────┌──────────────────────────────────────────┌───────────► Name Syntax Description ───────────────────────────────────────────────────────────────────────────── address « «segment | register»: »offset Identifies th (type *) constant of an express various comma Name Syntax Description ───────────────────────────────────────────────────────────────────────────── various comma Add Watch W? expression«, format» Displays expr memory range Watch window Assemble A «address» Assembles mne starting at a 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 Examine X«L|*|?«module!» «function.» Displays spec Symbols «symbol» «*» » symbols Execute E Executes in s 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 View V « «viewaddress».line number» Displays sour 8087 7 Displays 80x8 registers ───────────────────────────────────────────────────────────────────────────── Size Specifiers Use these data types with Dump and Enter dialog commands: Data Type Description ──────────────────────────────────────────────────────────────────────────── None Default type A ASCII (8-bit) characters B Byte (8-bit) hexadecimal values D Double-word (32-bit) hexadecimal values I Signed integer (16-bit) decimal values; equivalent to C signed int L Long (64-bit) floating-point (real) values; equivalent to C double S Short (32-bit) floating-point values; equivalent to C float T 10-byte (80-bit) floating-point values; equivalent to C long double U Unsigned integer (16-bit) decimal values; equivalent to C unsigned int W Word (16-bit) hexadecimal values Format Specifiers Character Output Format ──────────────────────────────────────────────────────────────────────────── d Signed decimal integer i Signed decimal integer u Unsigned decimal integer o Unsigned octal integer x | X Hexadecimal integer f Signed value in floating-point decimal format with six decimal places e | E Signed value in scientific-notation format with up to six decimal places (trailing zeros and decimal point truncated) g | G Signed value with floating-point decimal or scientific-notation format, whichever is more compact c Single character s Characters printed up to the first null character ──────────────────────────────────────────────────────────────────────────── NOTE 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. CVPACK ──────────────────────────────────────────────────────────────────────────── Summary 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 /P Packs the file to the smallest possible size EXEHDR ──────────────────────────────────────────────────────────────────────────── Summary 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. EXP ──────────────────────────────────────────────────────────────────────────── Summary 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 HELPMAKE ──────────────────────────────────────────────────────────────────────────── Summary 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. ILINK (Incremental Linker) ──────────────────────────────────────────────────────────────────────────── Summary 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. LIB ──────────────────────────────────────────────────────────────────────────── Summary The LIB utility helps create, organize, and maintain run-time libraries. Syntax LIB inlibrary «options» «commands» «,«listfile» «,«outlibrary» » » « ; » Options /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. Syntax LINK «options» objfiles «,«exefile» «,« mapfile» «,«libraries» «,«deffile» » » » » « ; » Options /A /A«LIGNMENT»:size 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. app_type {WINDOWAPI | WINDOWCOMPAT | NOTWINDOWCOMPAT} 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. Syntax CODE «load» «executeonly» «iopl» «conforming» «shared» «movable» «discard» 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. Syntax SEGMENTS « ' » segmentname« ' » «CLASS 'classname'» «load» «readonly» «executeonly» «iopl» «conforming» «shared» «movable» «discard» 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. Syntax EXPORTS entryname «=internalname» «@ord«RESIDENTNAME» » «pwords» «NODATA» 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. Syntax EXETYPE « OS2 | WINDOWS | UNKNOWN » NMAKE ──────────────────────────────────────────────────────────────────────────── Summary 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. NMAKE Macro Statements Description Block Format Syntax target... : «dependent» «;command» «#comment» «command» «#comment» «#comment» | «command» . . . 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. Syntax . fromext.toext: command «command»... NMAKE uses these predefined inference rules: ╓┌───────────────┌────────────────────────┌──────────────────────────────────╖ Inference Rule Command Default Action ──────────────────────────────────────────────────────────────────────────── .C.OBJ $(CC) $(CFLAGS) /C $*.C CL /C $*.C .C.EXE $(CC) $(CFLAGS) $*.C CL $*.C .ASM.OBJ $(AS) $(AFLAGS) $*; MASM $*; ──────────────────────────────────────────────────────────────────────────── Directives 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. Programmer's WorkBench ──────────────────────────────────────────────────────────────────────────── Summary 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 boxarg Copy Copies the highlighted Arg linearg Copy Clipboard. Arg streamarg Copy Arg textarg Copy 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. Arg streamarg Insert Inserts blank spaces i Arg linearg Insert highlighted area. Function Syntax Description (Default) ───────────────────────────────────────────────────────────────────────────── Arg linearg Insert highlighted area. Arg boxarg Insert 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 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